GitLab CI/CD Pipelines¶

What is a Gitlab Pipeline?¶

A GitLab CI/CD pipeline is an automated workflow that runs predefined tasks whenever changes occur in a Git repository. These tasks typically include building software, running tests, performing analysis, and deploying applications.

Pipelines allow development processes to be automated and executed consistently without manual intervention and consist of the following components:

• YAML Configuration File
• Jobs
• Stages
• Docker Images

Each of these components is described in more detail below, except for Docker Images as noted at the top of the page.

The YAML Configuration File¶

What is a Gitlab CI/CD YAML configuration file?¶

The CI/CD pipelines on Gitlab require a YAML configuration file (.gitlab-ci.yml) to exist in the root of your repository. The YAML configuration file consits of:

• Global YAML keywords that control the overall behavior of the project’s pipelines.
• Jobs that execute commands to accomplish a task. For example, a job could compile, test, or deploy code. Jobs run independently from each other, and are executed by runners.
• Stages, which define how to group jobs together. Stages run in sequence, while the jobs in a stage run in parallel. For example, an early stage could have jobs that lint and compile code, while later stages could have jobs that test and deploy code. If all jobs in a stage succeed, the pipeline moves on to the next stage. If any job in a stage fails, the next stage is not (usually) executed and the pipeline ends early.

How does the YAML configuration file work?¶

An example configuration file for building a Jekyll Website is shown below:

variables: # (1)
    JEKYLL_SITE_DIR: "$SITE_ARTIFACTS"
    JEKYLL_VENDOR_CACHE_DIR: $CI_PROJECT_DIR/vendor-cache
    GIT_DEPTH: "1"
    GIT_STRATEGY: fetch

Build Jekyll Site: # (2)
  stage: build  # (3)
  image: ruby:2.3 # (4)
  script:
    - cd ./source
    - bundle install --path $JEKYLL_VENDOR_CACHE_DIR
    - bundle exec jekyll build --strict_front_matter -d $CI_PROJECT_DIR/$JEKYLL_SITE_DIR
  artifacts: # (5)
    paths:
    - $JEKYLL_SITE_DIR
    expire_in: 1 week
  tags: # (6)
    - shared-docker-runner
  rules: # (7)
    - if: '$CI_COMMIT_BRANCH == $CI_DEFAULT_BRANCH' 

The example YAML configuration file can be broken down as follows:

• (1). These are variables that are set for the CI/CD pipeline, they are similar to Environment Variables that you can set on the Unix OS.
• (2). This defines a job within the CI/CD pipeline. A job represents a single unit of work that the pipeline will execute, such as building, testing, or deploying an application. The name (Build Jekyll Site) is an arbitrary identifier used to label the job in the pipeline.
• (3). The stage specifies which phase of the pipeline the job belongs to. GitLab pipelines are organized into ordered stages (e.g., build, test, deploy). All jobs in the same stage run in parallel, while stages themselves run sequentially according to the pipeline’s stage order.
• (4). The image specifies the container image used to run the job when using a Docker-based runner. In this case, the job runs inside the ruby:2.3 container, which provides the required Ruby runtime and tooling needed to build the Jekyll site.
• (5). The artifacts section defines files or directories produced by the job that should be preserved after the job finishes. These artifacts can be downloaded later or passed to subsequent jobs in later stages. The expire_in parameter specifies how long GitLab will retain these artifacts.
• (6). Tags are used to select which GitLab Runner should execute the job. Runners are registered with specific tags, and a job will only be picked up by runners that have matching tags. This allows jobs to target specific execution environments.
• (7). Rules define conditions that determine whether the job should be included in the pipeline. In this example, the job only runs when the commit occurs on the repository’s default branch ($CI_DEFAULT_BRANCH). This prevents the job from executing on other branches unless the rule evaluates to true.

Using the Gitlab CI/CD Pipeline.¶

As shonw in the example configuration above, you can set rules in the configuration that limit when the pipeline will be triggered to run. By default if no rule is included in the .gitlab-ci.yml file then the pipeline will trigger for each commit to the branch that contains the configuration file

Pipeline Status¶

When a CI/CD pipeline is triggered, a status symbol is added to the status banner on your repositories Gitlab webpage. The status symbol has three variations, the first one you will see is the empty circle with a blue slice indicating the pipeline is in-progress, which will then change to a green circle with a green check mark if the pipeline succeeded or a red circle with red cross to indicate the pipeline failed. The image below shows an example of a successful pipeline run:

Pipeline Details¶

When a CI/CD pipeline is in-progress, you can click on the status symbol to be taken to the pipelines detailed page as shown in the image below:

Inspecting a Pipeline Job¶

From there, you can select a Job to view the live logs of that job. As an example, from the image above you could directly click on the pages Job and would then be taken to a screen that looks like the following:

Here you can view the live log of the Runner as it attempts to execute the instructions from the .gitlab-ci.yml file, should a job not complete for any reason this is where you will find out what the error was.

See the gitlab docs for more info about the CI/CD file: https://git.cs.sun.ac.za/help/ci/yaml/index.md

Enabling Shared Runners¶

The CS GitLab system has a number of shared runners that students can make use of.

To enable "shared runners" a user should turn them on in the settings of their project. If your project is managed for you, you may need to ask the Lecturer to do this.

The shared runners also require the use of tags for the runner to pickup your job.

There are a few tags that users can make use of, and they can be viewed in the "runners" section of a projects "settings".

Below, a picture showing where to find the "enable" button and the shared runners tags which is shown as the blue labels for each of the listed runners.

Further info¶

Please submit suggestions for this page at the link in the bar on the left.