Skip to content
Snippets Groups Projects
Select Git revision
  • master default protected
  • tpa-rfc-80-merge-tor-and-tails-support-policies
  • puppet-merge-costs
  • rfc-77-improv
  • tails-merge-admin-mailing-lists
  • mkdocs
  • new-blog-doc
7 results
Blame Permalink
gitlab.md 41.58 KiB

GitLab is a web-based DevOps lifecycle tool that provides a Git-repository manager providing wiki, issue-tracking and continuous integration/continuous deployment pipeline features, using an open-source license, developed by GitLab Inc (Wikipedia). Tor uses GitLab mainly for issue tracking, wiki hosting and code review for now, at https://gitlab.torproject.org, after migrating from howto/trac.

Note that continuous integration is documented separately, in the CI page.

Tutorial

How to get an account?

You might already have an account! If you were active on Trac, your account was migrated with the same username and email address as Trac, unless you have an LDAP account, in which case that was used. So head over to the password reset page to get access to your account.

If your account was not migrated, send a mail to gitlab-admin@torproject.org to request a new one.

If you did not have an account in Trac and want a new account, you should request a new one at https://gitlab.onionize.space/.

How to report an issue in Tor software?

You first need to figure out which project the issue resides in. The project list is a good place to get started. Here are a few quick links for popular projects:

If you do not have a GitLab account or can't figure it out for any reason, you can also use the mailing lists. The tor-dev@lists.torproject.org mailing list is the best for now.

How to report an issue in the bugtracker itself?

If you have access to GitLab, you can file a new issue after you have searched the GitLab project for similar bugs.

If you do not have access to GitLab, you can email gitlab-admin@torproject.org.

Note about confidential issues

Note that you can mark issues as "confidentials" which will make them private to the members of the project the issue is reported on (the "developers" group and above, specifically).

Keep in mind, however, that it is still possible issue information gets leaked in cleartext, however. For example, GitLab sends email notifications in cleartext for private issue, an known upstream issue. (We have decided we cannot fix this ourselves in GitLab for now.) Some repositories might also have "web hooks" that notify IRC bots in clear text as well, although at the time of writing all projects are correctly configured.

How to contribute code?

As reporting an issue, you first need to figure out which project you are working on in the GitLab project list. Then, if you are not familiar with merge requests, you should read the merge requests introduction in the GitLab documentation. If you are unfamiliar with merge requests but familiar with GitHub's pull requests, those are similar.

Note that we do not necessarily use merge requests in all teams yet, and Gitolite still has the canonical version of the code. See issue 36 for a followup on this.

Also note that different teams might have different workflows. If a team has a special workflow that diverges from the one here, it should be documented here. Those are the workflows we know about:

If you do not have access to GitLab, please use one of the mailing lists: tor-dev@lists.torproject.org would be best.

How to quote a comment in a reply?

The "Reply" button only creates a new comment without any quoted text by default. It seems the solution to that is currently highlighting the text to quote and then pressing the r-key. See also the other keyboard shortcuts.

Alternatively, you can copy-paste the text in question in the comment form, select the pasted text, and hit the Insert a quote button which look like a styled, curly, and closing quotation mark ”.

How-to

Continuous Integration (CI)

All CI documentation resides in a different document see service/ci.

Email interactions

You can interact with GitLab by email too.

Creating a new issue

Clicking on the project issues gives a link at the bottom of the page, which says say "Email a new issue to this project".

That link should go into the "To" field of your email. The email subject becomes the title of the issue and the body the description. You can use shortcuts in the body, like /assign @foo, /estimate 1d, etc.

See the upstream docs for more details.

Commenting on an issue

If you just reply to the particular comment notification you received by email, as you would reply to an email in a thread, that comment will show up in the issue.

You need to have email notifications enabled for this to work, naturally.

You can also add a new comment to any issue by copy-pasting the issue-specific email address in the right sidebar (labeled "Issue email", introduced in GitLab 13.8).

This also works with shortcuts like /estimate 1d or /spend -1h. Note: for those you won't get notification emails back, though, while for others like /assign @foo you would.

See the upstream docs for more details.

Quick status updates by email

There are a bunch of quick actions available which are handy to update an issue. As mentioned above they can be sent by email as well, both within a comment (be it as a reply to a previous one or in a new one) or just instead of it. So, for example, if you want to update the amount of time spent on ticket $foo by one hour, find any notification email for that issue and reply to it by replacing any quoted text with /spend 1h.

How to migrate a Git repository from legacy to GitLab?

Important: this policy is still being debated. It is not clear if any or all repositories should be migrated to GitLab, see issue 36 for the discussion on this topic.

As an example of a repository migration, I have moved the wiki from gitolite to gitlab just now. I have followed the following procedure:

  1. create a project on gitlab (in tpo/tpa/wiki-archive in my case)

  2. push (manually) the latest git references present on git-rw to gitlab (git push --mirror...)

  3. if the repository is to be archived on GitLab, make it so in Settings -> General -> Advanced -> Archive project

  4. make an (executable) pre-receive hook in git-rw with an exit status of 1 warning about the new code location, example:

    $ cat /srv/git.torproject.org/repositories/project/help/wiki.git/hooks/pre-receive 
#!/bin/sh

cat <<EOF
This repository has been migrated to GitLab:

https://gitlab.torproject.org/tpo/tpa/services/-/wikis/home

Update your remotes to:

    git@gitlab.torproject.org:tpo/tpa/services.wiki.git

or:

    https://gitlab.torproject.org/tpo/tpa/services.wiki.git

See this issue for details:

https://gitlab.torproject.org/tpo/tpa/services/-/issues/34437
EOF

exit 1

    or in the case of a fully archived repository (non-writable):

    $ cat /srv/git.torproject.org/repositories/project/help/infra.git/hooks/pre-receive 
#!/bin/sh

cat <<EOF
This repository has been migrated to GitLab:

https://gitlab.torproject.org/tpo/tpa/wiki-infra-archive

We have migrated away from ikiwiki so it is not necessary anymore.

See this issue for details:

https://gitlab.torproject.org/tpo/tpa/services/-/issues/34437
EOF

exit 1

  5. in Gitolite, make the project part of the "Attic", for example

    @@ -328,13 +328,13 @@ admin/trac/TracAccountManager "The Tor Project" = "Tor specific changes to Matth
 
 repo project/help/infra
     RW+                                      = @torproject-admin
-    config gitweb.category                   = Infrastructure and Administration
-project/help/infra "The Tor Project" = "help.torproject.org infrastructure"
+    config gitweb.category                   = Attic
+project/help/infra "The Tor Project" = "help.torproject.org infrastructure (archived to GitLab: https://gitlab.torproject.org/tpo/tpa/wiki-infra-archive')"
 
 repo project/help/wiki
     RW                                       = anarcat
-    config gitweb.category                   = Infrastructure and Administration
-project/help/wiki "The Tor Project" = "help.torproject.org content"
+    config gitweb.category                   = Attic
+project/help/wiki "The Tor Project" = "help.torproject.org content (archived to GitLab: https://gitlab.torproject.org/tpo/tpa/wiki-archive')"
 
 repo project/jenkins/jobs
     RW                                       = @jenkins-admins

The only downside with that approach is that a git clone will not warn about the project redirection, but I am not sure there's a way to fix that.

See issue 36 for further discussion.

How to find the right emoji?

It's possible to add "reaction emojis" to comments and issues and merge requests in GitLab. Just hit the little smiley face and a dialog will pop up. You can then browse through the list and pick the right emoji for how you feel about the comment, but remember to be nice!

It's possible you get lost in the list. You can type the name of the emoji to restrict your search, but be warned that some emojis have particular, non-standard names that might not be immediately obvious. For example, 🎉, U+1F389 PARTY POPPER, is found as tada in the list! See this upstream issue for more details.

Hooking up a project with the bots

By default, new projects do not have notifications setup in #tor-bots like all the others. To do this, you need to configure a "Webhook", in the Settings -> Webhooks section of the project. The URL should be:

https://kgb-bot.torproject.org/webhook/

... and you should select the notifications you wish to see in #tor-bots. You can also enable notifications to other channels by adding more parameters to the URL, like (say) ?channel=%23tor-foo. The parameters are documented the KGB documentation.

Note that GitLab admins might be able to configure system-wide hooks in the admin section, although it's not entirely clear how does relate to the per-project hooks so those have not been enabled. Furthermore, it is possible for GitLab admins with root access to enable webhooks on all projects, with the webhook rake task. For example, running this on the GitLab server (currently gitlab-02) will enable the above hook on all repositories:

sudo gitlab-rake gitlab:web_hook:add URL='https://kgb-bot.torproject.org/webhook/'

Note that by default, the rake task only enables Push events. You need the following patch to enable others:

modified   lib/tasks/gitlab/web_hook.rake
@@ -10,7 +10,19 @@ namespace :gitlab do
       puts "Adding webhook '#{web_hook_url}' to:"
       projects.find_each(batch_size: 1000) do |project|
         print "- #{project.name} ... "
-        web_hook = project.hooks.new(url: web_hook_url)
+        web_hook = project.hooks.new(
+          url: web_hook_url,
+          push_events: true,
+          issues_events: true,
+          confidential_issues_events: false,
+          merge_requests_events: true,
+          tag_push_events: true,
+          note_events: true,
+          confidential_note_events: false,
+          job_events: true,
+          pipeline_events: true,
+          wiki_page_events: true,
+        )
         if web_hook.save
           puts "added".color(:green)
         else

See also the upstream issue and our GitLab issue 7 for details.

You can also remove a given hook from all repos with:

sudo gitlab-rake gitlab:web_hook:rm URL='https://kgb-bot.torproject.org/webhook/'

And, finally, list all hooks with:

sudo gitlab-rake gitlab:web_hook:list

Setting up two-factor authentication (2FA)

We strongly recommend you enable two-factor authentication on GitLab. This is well documented in the GitLab manual, but basically:

  1. first, pick a 2FA "app" (and optionally a hardware token) if you don't have one already

  2. head to your account settings

  3. register your 2FA app and save the recovery codes somewhere. if you need to enter a URL by hand, you can scan the qrcode with your phone or create one by following this format:

    otpauth://totp/$ACCOUNT?secret=$KEY&issuer=gitlab.torproject.org

    where...

    • $ACCOUNT is the Account field in the 2FA form
    • $KEY is the Key field in the 2FA form, without spaces

  4. register the 2FA hardware token if available

GitLab requires a 2FA "app" even if you intend to use a hardware token. The 2FA "app" must implement the TOTP protocol, for example the Google Authenticator or a free alternative (for example free OTP plus, see also this list from the Nextcloud project). The hardware token must implement the U2F protocol, which is supported by security tokens like the YubiKey, Nitrokey, or similar.