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. Access your User settings

    2. Select Account

    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.

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 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

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#