Pipeline Overview📜

Note

This sample pipeline is a quick and sample guide to get started with GitLab. This sample pipeline is for development purposes only. It walks users through all the normal steps of a pipeline (build > test > deploy) but each of those steps would have to be modified specifically for the environment that it’s running in.

GitLab offers a continuous integration service. If you add a .gitlab-ci.yml file to the root directory of your repository, and configure your GitLab project to use a Runner, then each commit or push, triggers your CI pipeline.

The .gitlab-ci.yml file tells the GitLab runner what to do. By default, it runs a pipeline with three stages: build, test, and deploy. You don’t need to use all three stages: stages with no jobs are simply ignored. If everything runs OK (no non-zero return values), you’ll get a nice green checkmark associated with the commit. This makes it easy to see whether a commit caused any of the tests to fail before you even look at the code.

Most projects use GitLab’s CI service to run the test suite so that developers get immediate feedback if they broke something. Steps needed to have a working CI can be summed up to:

Add .gitlab-ci.yml to the root directory of your repository
Configure a Runner.

From there on, every push to your Git repository, the Runner will automatically start the pipeline and the pipeline will appear under the project’s Pipelines page.

This guide assumes that you:

have a working GitLab instance of version 8.0+r or are using GitLab.com
have a project in GitLab that you would like to use CI for

Let’s break it down to pieces - Creating a .gitlab-ci.yml file

Before you create .gitlab-ci.yml let’s first explain in brief what this is all about.

What is `.gitlab-ci.yml`📜

The .gitlab-ci.yml file is where you configure what CI does with your project. It lives in the root of your repository.

On any push to your repository, GitLab will look for the .gitlab-ci.yml file and start jobs on Runners according to the contents of the file, for that commit.

Because .gitlab-ci.yml is in the repository and is version controlled, old versions still build successfully, forks can easily make use of CI, branches can have different pipelines and jobs, and you have a single source of truth for CI.

Creating a simple .gitlab-ci.yml file

Note

.gitlab-ci.yml is a YAML file so you have to pay extra attention to indentation. Always use spaces, not tabs.

You need to create a file named .gitlab-ci.yml in the root directory of your repository. For more information and a complete .gitlab-ci.yml syntax, please read the reference documentation on .gitlab-ci.yml.

Push .gitlab-ci.yml to GitLab Once you have created .gitlab-ci.yml, you should add it to your GIT repository and push it to GITLab.

git add .gitlab-ci.yml
git commit -m "Add .gitlab-ci.yml"
git push origin master

Example `.gitlab-ci.yml` file📜

# This file is a template, and might need editing before it works on your project.
# This is a sample GitLab CI/CD configuration file that should run without any modifications.
# It demonstrates a basic 3 stage CI/CD pipeline. Instead of real tests or scripts,
# it uses echo commands to simulate the pipeline execution.
#
# A pipeline is composed of independent jobs that run scripts, grouped into stages.
# Stages run in sequential order, but jobs within stages run in parallel.
#
# For more information, see: https://docs.gitlab.com/ee/ci/yaml/index.html#stages
#
# You can copy and paste this template into a new `.gitlab-ci.yml` file.
# You should not add this template to an existing `.gitlab-ci.yml` file by using the `include:` keyword.
#
# To contribute improvements to CI/CD templates, please follow the Development guide at:
# https://docs.gitlab.com/ee/development/cicd/templates.html
# This specific template is located at:
# https://gitlab.com/gitlab-org/gitlab/-/blob/master/lib/gitlab/ci/templates/Getting-Started.gitlab-ci.yml

# Source reusable pipeline components
include:
  - local: '/cicd/scripts.yaml'

# Single place to define values that are used throughout this pipeline
variables:
  PIPELINE_REPO: https://repo1.dso.mil/platform-one/onboarding/big-bang/sample-pipeline.git
  PIPELINE_REPO_DESTINATION: "../cicd"
  PIPELINE_REPO_BRANCH: main

# List of stages for jobs, and their order of execution
stages:
  - build
  - test
  - deploy

# This job runs in the build stage, which runs first.
build:
  image: docker:latest
  stage: build
  services:
    - docker:dind
  before_script:
    - docker login -u "$CI_REGISTRY_USER" -p "$CI_REGISTRY_PASSWORD" $CI_REGISTRY
  # Default branch leaves tag empty (= latest tag)
  # All other branches are tagged with the escaped branch name (commit ref slug)
  script:
    - |
      if [[ "$CI_COMMIT_BRANCH" == "$CI_DEFAULT_BRANCH" ]]; then
        tag=""
        echo "Running on default branch '$CI_DEFAULT_BRANCH': tag = 'latest'"
      else
        tag=":$CI_COMMIT_REF_SLUG"
        echo "Running on branch '$CI_COMMIT_BRANCH': tag = $tag"
      fi
    - docker build --pull -t "$CI_REGISTRY_IMAGE${tag}" .
    - docker push "$CI_REGISTRY_IMAGE${tag}"
  # Run this job in a branch where a Dockerfile exists
  rules:
    - if: $CI_COMMIT_BRANCH
      exists:
        - Dockerfile

# This job runs in the test stage.
# It only starts when the job in the build stage completes successfully.
unit-test:
  stage: test
  extends:
    - .scripts
  script:
    - unit_test

# This job also runs in the test stage.
# It can run at the same time as unit-test (in parallel).
code-lint:
  stage: test
  extends:
    - .scripts
  script:
    - code_lint

# This job runs in the deploy stage.
# It only runs when *both* jobs in the test stage complete successfully.
deploy-job:
  stage: deploy
  extends:
    - .scripts
  environment: production
  script:
    - kubeconfig
    - deploy

Configuring a Runner📜

In GitLab, Runners run the jobs that you define in .gitlab-ci.yml. A Runner can be a virtual machine, a VPS, a bare-metal machine, a docker container or even a cluster of containers. GitLab and the Runners communicate through an API, so the only requirement is that the Runner’s machine has network access to the GitLab server.

A Runner can be specific to a certain project or serve multiple projects in GitLab. If it serves all projects, it’s called a Shared Runner.

Find more information about different Runners in the Runners documentation.

You can find whether any Runners are assigned to your project by going to Settings ➔ CI/CD. Setting up a Runner is easy and straightforward. The official Runner supported by GitLab is written in Go and its documentation can be found at https://docs.gitlab.com/runner/.

In order to have a functional Runner you need to follow two steps:

Install it
Configure it

Follow the links https://docs.gitlab.com/runner/ to set up your own Runner or use a Shared Runner as described in the next section.

Once the Runner has been set up, you should see it on the Runners page of your project, following Settings ➔ CI/CD.

Quiz Questions📜

What does the .gitlab-ci.yml file do?

The .gitlab-ci.yml file is where you configure what CI does with your project. It lives in the root of your repository.

If you add a .gitlab-ci.yml file to the root directory of your repository, and configure your GitLab project to use a Runner, then each commit or push, triggers your CI pipeline.

It tells the GitLab runner what to do. By default, it runs a pipeline with three stages: build, test, and deploy.

Should you use spaces or tabs when making a .gitlab-ci.yml file?

You should always use spaces, not tabs

What is a GitLab Runner?

A GitLab Runner runs the jobs that you define in .gitlab-ci.yml. A Runner can be a virtual machine, a VPS, a bare-metal machine, a docker container or even a cluster of containers.

GitLab and the Runners communicate through an API, so the only requirement is that the Runner’s machine has network access to the GitLab server.

Pipeline Overview📜

What is .gitlab-ci.yml📜

Example .gitlab-ci.yml file📜

Configuring a Runner📜

Quiz Questions📜

What is `.gitlab-ci.yml`📜

Example `.gitlab-ci.yml` file📜