How to work with GitLab at SKAO#

Step-by-step instructions for common GitLab tasks.

Configure Git#

Set your institutional email#

Configure Git to use your institutional email for signing commits. Set this globally:

git config --global user.email "your@institutional.email"

Or set the email per project:

cd your/git/project
git config user.email "your@institutional.email"

Configure GitLab#

Access SKA Observatory repositories#

Find SKA Observatory repositories at gitlab.com/ska-telescope.

Request access through the System Team Support Center to link your account to the SKA GitLab group.

Use your institutional email#

Create a GitLab account using your institutional email at gitlab.com.

If you have a GitLab account, add your institutional email at GitLab Profile Emails and click Add new email.

Enable 2FA (two-factor authentication)#

SKAO requires 2FA for every GitLab user. It adds a second layer of protection to your account.

Prerequisites:

Install an authenticator app. SKAO IT recommends Google Authenticator as it works in locations without mobile connectivity. We also support Microsoft Authenticator and Aegis Authenticator.

Warning

Google Authenticator offers sync to your Google Account — this creates a security risk. Keep sync disabled (the cloud icon with a line through it shows sync is off).

Steps:

  1. In GitLab:

    1. Select Edit profile

    2. In the left sidebar, select Access > Password and authentication

    3. Select Enable Two-factor Authentication

  2. On your device (phone):

    1. Install a compatible authenticator application

    2. Add a new entry by scanning the QR code displayed by GitLab, or enter details manually

  3. In GitLab:

    1. Enter the six-digit pin from your authenticator app

    2. Enter your current password

    3. Select Submit

Important

Back up your recovery codes in a safe place. If you lose them, you can’t regain access until a GitLab admin resets your account. SKAO can’t reset MFA codes because they attach to gitlab.com itself.

Set up SSH key#

Link your SSH key to your GitLab user at GitLab SSH Keys.

Sign your commits with GPG#

Sign your Git commits with a GPG key — this is the SKAO standard for commit signing. To obtain a key and add it to GitLab, follow Sign commits with GPG, or go straight to uploading your public key at GPG Keys.

Sign a commit with the -S flag:

git commit -S -m "ABC-123: Add awesome code"

To sign every commit automatically without the -S flag:

git config --global commit.gpgsign true

Sign commits on a remote machine#

When you work on a remote machine over SSH, you can forward your local GPG key to it — known as agent forwarding — so you can sign commits on the remote machine without copying your private key onto it:

  1. Find your local socket: gpgconf --list-dir agent-extra-socket

  2. Find the remote socket: gpgconf --list-dir agent-socket

  3. In your local SSH config, add this line after the host settings, then reconnect to apply it:

    RemoteForward <remote-agent-socket> <local-agent-extra-socket>

  4. On the remote machine, add StreamLocalBindUnlink yes to /etc/ssh/sshd_config and restart sshd so the forwarding socket is removed when the SSH session ends.

Commit with 2FA enabled#

With 2FA enabled, you can’t use your password to authenticate with Git over HTTPS or the GitLab API. Use your SSH key (preferred) or a personal access token instead.

Switch your repository from HTTPS to SSH:

# Quick method
git remote set-url origin $(git remote get-url origin | sed -e 's/https:\/\/\([^/]*\)\/\(.*\)/git@\1:\2/')

# Or step by step:
# 1. Check current remote URL
git remote -v
# > origin  https://gitlab.com/ska-telescope/ska-snippets.git (fetch)

# 2. Change to SSH URL
git remote set-url origin git@gitlab.com:ska-telescope/ska-snippets.git

# 3. Verify the update
git remote -v
# > origin  git@gitlab.com:ska-telescope/ska-snippets.git (fetch)

Create a work branch#

Create work branches from the main branch. Always pull the latest changes first:

git pull origin main

Name your branch following these rules:

  • Prefix with the Jira story ID

  • Use all lower case

  • Use hyphens - to separate words

Example: abc-123-the-new-widget

git checkout -b abc-123-the-new-widget

The branch now exists only locally. Make your changes and commit them.

Commit message format:

  • Prefix with the Jira ID in UPPER CASE

  • Follow with a colon and space

git add .  # adds all changes to staging
git commit -m "ABC-123: Add awesome code"

Push code and branch#

Push your branch to the remote repository:

git push

If this is the first push for this branch, Git will prompt you to set the upstream:

git push --set-upstream origin abc-123-the-new-widget

Git displays output with a URL to create a merge request:

remote: To create a merge request for abc-123-the-new-widget, visit:
remote:   https://gitlab.com/ska-telescope/awesome-project/-/merge_requests/new?merge_request%5B...

Create a merge request#

Merge requests enable code reviews and continuous branch testing.

GitLab provides a URL to create the merge request after you push your branch. You can also create one manually via Code → Merge Request in the GitLab interface.

Merge request checklist:

  • Title starts with Jira ID (e.g., “ABC-123: Add new feature”)

  • Description explains what changed and why

  • Assign reviewers from your team

  • Link to related Jira ticket

  • All pipeline checks pass

Code review#

Every merge request to an SKAO repository must be reviewed by another developer before it merges. Code review keeps design and implementation consistent, improves test coverage, spreads knowledge across the team, and catches problems early — so review throughout development, not only at the end.

As the author, assign one or more reviewers on the merge request and share the merge request link with them.

As a reviewer, check that the change:

  • follows SKAO coding standards and naming conventions

  • includes adequate test coverage

  • is clear and maintainable, with no typos or obvious defects

  • has no simpler or more suitable approach available

To review in GitLab:

  1. Open the merge request and select the Changes tab.

  2. Comment on a line by hovering over it and clicking the speech-bubble icon — drag to select multiple lines.

  3. On your first comment, select Start a review; your review comments stay hidden from others until you submit them.

  4. Add further comments with Add to review.

  5. Select Submit review to publish your comments and approve or request changes.

Share code snippets#

Share code snippets within SKA Observatory using the ska-snippets repository. You can also use project-level snippets if your project enables them.

Next steps#