Index

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 aRunner, 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 thre e 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:

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

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

This guide assumes that you:

  1. have a working GitLab instance of version 8.0+r or are using GitLab.com
  2. 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

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:

  1. Install it
  2. 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.