Configuring a gitlab pipeline file

What is GitLab?

GitLab is a version-controlled (git) platform for hosting code in repositories. We can define CI/CD pipelines (e.g., .gitlab-ci.yml ) to automate things like code scanning and deployment.


This is the configuration file used to define CI/CD jobs for your pipeline. The configuration file gets written in YAML and a syntax reference can be found on the official GitLab docs.

For reference, I have a fully functional file hosted here for a past project I developed. Let's break down some of the keywords.


Stages is where we define the names and order of the pipeline stages.

Here I have two stages shown and each runs jobs. For example, the security_scan stage runs the security code scanning job. The other runs a job that ensures my terraform code is valid.

    - security_scan
    - validate


Variables is where we define any variables needed throughout the pipeline.

Here I have a few. When needed throughout my code, I can simply use WEB_S3 (or any other variable) instead of writing out the full name. This makes it super easy to change the name in a single place rather than updating multiple places in the code.

  TF_ROOT: "$CI_PROJECT_DIR/terraforms"
  WEB_S3: ""


Jobs get defined and execute commands. For example, the job shown below is called deploy. It gets run as part of the stage, stage: deploy (I purposely gave it the same name for simplicity).

This job does a few things,

  1. script lets us execute shell commands on the runner (the container).

    • Two terraform commands get run

  2. when let's us define when this job gets run.

    • manual means I initiate this job in the console by clicking a button

  3. allow_failure determines whether a job can fail or not

    • false means if the job fails, subsequent jobs cannot run

    • true lets subsequent jobs run despite this job failing

  4. rules define conditions that must be met to run this job

    • if: $CI_COMMIT_BRANCH == "main" means only run this job if the code is being committed to a branch called main

  stage: deploy
    - terraform init
    - terraform apply plan
  when: manual
  allow_failure: false
    - if: $CI_COMMIT_BRANCH == "main"

Last updated