Tutorial: Set Up Your First CI/CD Pipeline#

Configure a CI/CD pipeline for your SKAO project with this step-by-step guide.

What You’ll Learn#

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

  • Created a .gitlab-ci.yml configuration file

  • Included the SKAO templates repository

  • Run your first pipeline

  • Understood the standard pipeline stages

Time required: 30-45 minutes

Prerequisites:

  • A project in the ska-telescope GitLab group

  • Basic familiarity with Git and GitLab

Note

To have SKA runners available, your project must be under the SKA Telescope group. Projects can only be added to the SKA group by the System Team — refer to the guide to /howto/create-a-new-project.

Step 1: Create the Configuration File#

Create a file called .gitlab-ci.yml in the root of your repository. This file defines how your project is built.

Find an example in the ska-python-skeleton project.

Step 2: Include the SKAO Templates#

SKAO provides standardised templates that automate common pipeline tasks. Include them in your .gitlab-ci.yml:

include:
  - project: 'ska-telescope/templates-repository'
    file: 'gitlab-ci/includes/python.gitlab-ci.yml'

For other artefact types, replace python.gitlab-ci.yml with the appropriate template:

  • helm.gitlab-ci.yml — Helm charts

  • oci-image.gitlab-ci.yml — Container images

  • docs.gitlab-ci.yml — Documentation

See the templates-repository for all available templates.

Step 3: Include the Finaliser#

To automate metrics collection and badge creation, include the finaliser template:

include:
  - project: 'ska-telescope/templates-repository'
    file: 'gitlab-ci/includes/finaliser.gitlab-ci.yml'

This automatically collects metrics from your pipeline stages when you follow the requirements in CI/CD Reference.

Step 4: Run Your Pipeline#

Run the pipeline in two ways:

Option 1: Commit to GitLab

Push your changes to the repository. The pipeline starts automatically when GitLab mirrors the commit.

Option 2: Run manually

  1. Go to your project in GitLab

  2. Navigate to CI/CD → Pipelines

  3. Click Run Pipeline

  4. Select the branch (e.g., main)

  5. Click Run Pipeline

Step 5: View Pipeline Results#

View these results after the pipeline runs:

  • Pipeline status — CI/CD → Pipelines

  • Job logs — Click any stage to see detailed output

  • Test reports — Appear in the merge request when configured

  • Artefacts — Downloadable build outputs

Understanding Pipeline Stages#

SKAO pipelines follow a standard set of stages:

Build → Lint → Test → Scan → Publish → Pages

Each stage has specific inputs and outputs. See CI/CD Reference for details on each stage.

Congratulations!#

You now have a working CI/CD pipeline. Your pipeline will:

  • Build your project

  • Run linting and tests

  • Collect code health metrics

  • Publish artefacts (on tagged releases)

Next Steps#