Tutorial: Make Your First Contribution#

A step-by-step guide to submitting your first merge request at SKAO.

What You’ll Learn#

By the end of this tutorial, you’ll have:

  • Configured Git with your institutional email

  • Set up SSH keys for GitLab authentication

  • Created a branch linked to a Jira ticket

  • Made a commit with the correct message format

  • Pushed your changes and created a merge request

Time required: 30-45 minutes

Prerequisites:

  • Git installed on your machine

  • A GitLab account linked to the SKA group — see New developer to set one up

  • A Jira ticket assigned to you (ask your Scrum Master if you need one)

  • An authenticator app installed on your phone

Step 1: Configure Git#

Tell Git who you are. Use your institutional email — SKAO requires this for all contributions.

Open your terminal and run:

git config --global user.name "Your Name"
git config --global user.email "your@institutional.email"

Verify your configuration:

git config --list

This displays your name and email in the output.

Step 2: Set Up SSH Keys#

SSH keys let you authenticate with GitLab without entering your password each time.

Check for existing keys:

ls -la ~/.ssh

If you see files named id_rsa or id_ed25519, skip to “Add your key to GitLab.”

Generate a new key:

ssh-keygen -t ed25519 -C "your@institutional.email"

Press Enter to accept the default file location. Enter a passphrase when prompted (recommended for security).

Add your key to GitLab:

  1. Copy your public key:

    cat ~/.ssh/id_ed25519.pub

  2. Go to GitLab SSH Keys

  3. Click Add a new key

  4. Paste the key into the Key field

  5. Give it a title (e.g., “Work Laptop”)

  6. Click Add key

Test the connection:

ssh -T git@gitlab.com

This displays: “Welcome to GitLab, @yourusername!”

Step 3: Enable Two-Factor Authentication#

2FA is required for all SKAO contributors.

  1. Open your authenticator app on your phone

  2. Select Edit profile in GitLab

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

  4. Click Enable Two-factor Authentication

  5. Scan the QR code with your authenticator app

  6. Enter the 6-digit code from your app

  7. Enter your GitLab password

  8. Click Submit

Note

If these steps are outdated, refer to the official GitLab documentation on enabling 2FA and raise a support ticket so the Developer Portal can be updated.

Important

Save your recovery codes! Store them in a secure location. These codes provide the only way to recover your account if you lose access to your authenticator.

Step 4: Clone a Repository#

Clone a repository you have access to. Ask your team which repository to use, or use a training repository if available.

git clone git@gitlab.com:ska-telescope/your-project.git
cd your-project

Verify you are on the main branch:

git branch

This displays * main in the output. Older repositories may use * master instead.

Step 5: Create a Branch#

Every change at SKAO starts with a Jira ticket. Your branch name includes the Jira ID.

Get the latest code:

git pull origin main

Create your branch:

Replace ABC-123 with your actual Jira ticket ID and add a short description:

git checkout -b abc-123-my-first-contribution

Notice the format:

  • Jira ID in lower case

  • Words separated by hyphens

  • Short, descriptive name

Verify you are on your new branch:

git branch

This displays * abc-123-my-first-contribution.

Step 6: Make a Change#

Make a small change to practice the workflow. Add your name to a contributors file or fix a typo in documentation.

Example — add a comment to a file:

Open any file in your editor and add a small, meaningful change. Save the file.

Check what changed:

git status

This lists your modified file in red.

Step 7: Commit Your Change#

Stage your changes:

git add .

Commit with a properly formatted message. The Jira ID must be in UPPER CASE:

git commit -m "ABC-123: Add my first contribution"

The format is: JIRA-ID: Description

Verify your commit:

git log --oneline -1

This displays your commit with the message you wrote.

Step 8: Push Your Branch#

Push your branch to GitLab:

git push --set-upstream origin abc-123-my-first-contribution

Git will display output including a URL to create a merge request. It looks like:

remote: To create a merge request for abc-123-my-first-contribution, visit:
remote:   https://gitlab.com/ska-telescope/your-project/-/merge_requests/new?...

Step 9: Create a Merge Request#

  1. Click the URL from the git push output, or go to your project in GitLab and click Create merge request

  2. Fill in the merge request:

    • Title: ABC-123: Add my first contribution (same format as commit)

    • Description: Explain what you changed and why

    • Assignee: Assign to yourself

    • Reviewer: Add a team member to review your code

  3. Click Create merge request

Step 10: Wait for Pipeline and Review#

After creating the merge request:

  1. Pipeline runs automatically — watch for the green checkmark

  2. Reviewer provides feedback — respond to comments and make changes as needed

  3. Push additional commits — commit and push to the same branch if changes are requested

  4. Merge — the reviewer (or you) merges the code once approved and the pipeline passes

Congratulations!#

You have successfully:

✅ Configured Git with your institutional email

✅ Set up SSH keys for secure authentication

✅ Enabled two-factor authentication

✅ Created a branch linked to a Jira ticket

✅ Made a properly formatted commit

✅ Pushed your code and created a merge request

You are now ready to contribute to SKA projects!

Troubleshooting#

“Permission denied (publickey)” when pushing:

Your SSH key needs correction. Verify:

ssh -T git@gitlab.com

If this fails, re-add your public key to GitLab.

“remote: You aren’t allowed to push code to this project”:

You lack write access to the repository. Contact the System Team Support Center to request access.

Pipeline failures:

See How to Work with CI/CD at SKAO for how to troubleshoot a failing pipeline.

Next Steps#