Understanding GitLab at SKAO#

Learn why SKAO uses GitLab and how the development workflow fits together.

Why GitLab?#

The SKA Software team uses GitLab as the main Git repository manager for CI/CD tools. GitLab combines:

  • Version control — Git repository hosting with branch protection and merge requests

  • CI/CD pipelines — Automated testing, building, and deployment

  • Code review — Inline comments, approval workflows, and merge request discussions

  • Project management — Integration with Jira for issue tracking and sprint planning

We host all SKA Observatory repositories at gitlab.com/ska-telescope.

The Development Workflow#

SKAO follows a branch-based development workflow that ensures code quality and traceability:

1. Create branch → 2. Make changes → 3. Push → 4. Merge request → 5. Review → 6. Merge

1. Create a branch

Start each piece of work from a Jira ticket. Include the Jira ID in the branch name to link the code change to the requirement it addresses.

2. Make changes

Develop your feature or fix locally. Include the Jira ID in commit messages to trace every change back to a specific story or task.

3. Push to GitLab

Pushing your branch triggers the CI pipeline, which runs tests, linters, and quality checks before code review.

4. Create a merge request

The merge request enables collaboration. It provides space for discussion, shows pipeline results, and tracks approval status.

5. Code review

Team members review your changes, suggest improvements, and verify the implementation meets requirements. Most projects require at least one approval.

6. Merge to main

Once approved and all checks pass, merge the code into the main branch. The pipeline runs again to ensure successful integration.

Branching Policy#

SKAO uses a simplified branching model based on trunk-based development:

Main branch

  • The main branch contains production-ready code

  • We block direct commits to main — all changes go through merge requests

  • Every merge triggers deployment pipelines

Work branches

  • Create from main for each Jira ticket

  • Name with the Jira ID prefix (e.g., abc-123-feature-name)

  • Keep short-lived — merge back to main when work completes

  • Delete after merge to keep the repository clean

Why this approach?

  • Traceability — Every change links to a Jira ticket

  • Continuous integration — Small, frequent merges reduce integration problems

  • Clear history — The main branch tells a clean story of the project’s evolution

Commit Practices#

Good commit practices make the codebase easier to understand and maintain.

Atomic commits

Each commit represents one logical change. If you describe your commit with “and,” split it into multiple commits.

Meaningful messages

Commit messages explain what changed and why. The Jira ID prefix provides context, and the description gives detail:

ABC-123: Add retry logic to API client

The external service occasionally returns 503 errors during peak load.
This change adds exponential backoff with a maximum of 3 retries.

Signed commits

GPG-signed commits verify that commits came from the claimed author. We strongly encourage this for all SKAO development, especially for security-sensitive repositories.

Why Institutional Email?#

SKAO requires institutional email addresses for GitLab accounts:

Identity verification

Institutional emails confirm that contributors belong to recognised SKAO partner organisations. This matters for a project involving multiple international institutions.

Access management

When someone leaves an organisation, their institutional email becomes invalid. This provides a natural mechanism for identifying accounts that need access review.

Communication

GitLab notifications and team communication use email. Institutional addresses ensure messages reach contributors through official channels.

Why 2FA is Required#

Two-factor authentication (2FA) is mandatory for all SKAO GitLab accounts:

Protecting the codebase

The SKA software represents years of development effort across multiple international teams. Compromised accounts could lead to malicious code injection or data loss.

Compliance

Many SKAO partner institutions require 2FA for access to collaborative development platforms.

Industry standard

Software development uses 2FA as standard practice. GitLab strongly recommends 2FA for all users.

Merge Request Quality#

Merge requests at SKAO serve multiple purposes beyond merging code:

Documentation

The MR description becomes part of the project’s history. Future developers understand why you made changes by reading the discussion and context.

Knowledge sharing

Code review spreads knowledge across the team. Reviewers learn about parts of the codebase they might not normally work with, and authors receive feedback that improves their skills.

Quality gate

Automated checks (pipeline) and human review (approvals) catch issues before they reach the main branch. This costs far less than fixing problems in production.

External Resources#

Learning Git:

GitLab Documentation:

See Also#