2017-11-01 11:56:40 -04:00
# Getting started with GitLab CI/CD
2015-08-25 21:42:46 -04:00
2016-03-01 03:26:53 -05:00
>**Note:** Starting from version 8.0, GitLab [Continuous Integration][ci] (CI)
is fully integrated into GitLab itself and is [enabled] by default on all
projects.
2015-08-25 21:42:46 -04:00
2016-03-01 03:26:53 -05:00
GitLab offers a [continuous integration][ci] service. If you
[add a `.gitlab-ci.yml` file][yaml] to the root directory of your repository,
2017-03-08 06:46:06 -05:00
and configure your GitLab project to use a [Runner], then each commit or
2018-09-05 12:54:08 -04:00
push triggers your CI [pipeline].
2016-03-01 03:26:53 -05:00
2016-06-14 21:12:39 -04:00
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.
2016-03-01 03:26:53 -05:00
If everything runs OK (no non-zero return values), you'll get a nice green
2017-03-08 06:46:06 -05:00
checkmark associated with the commit. This makes it
easy to see whether a commit caused any of the tests to fail before
2016-03-01 03:26:53 -05:00
you even look at the code.
2016-06-14 20:58:20 -04:00
Most projects use GitLab's CI service to run the test suite so that
2016-03-01 03:26:53 -05:00
developers get immediate feedback if they broke something.
2015-08-25 21:42:46 -04:00
2016-06-14 20:58:20 -04:00
There's a growing trend to use continuous delivery and continuous deployment to
automatically deploy tested code to staging and production environments.
2016-03-01 03:26:53 -05:00
So in brief, the steps needed to have a working CI can be summed up to:
2015-08-25 21:42:46 -04:00
2016-03-01 03:26:53 -05:00
1. Add `.gitlab-ci.yml` to the root directory of your repository
2015-11-05 10:53:05 -05:00
1. Configure a Runner
2015-08-25 21:42:46 -04:00
2016-06-14 20:58:20 -04:00
From there on, on every push to your Git repository, the Runner will
automagically start the pipeline and the pipeline will appear under the
2017-02-13 11:59:57 -05:00
project's **Pipelines** page.
2015-08-25 21:42:46 -04:00
2016-03-01 03:26:53 -05:00
---
This guide assumes that you:
2017-02-13 11:59:57 -05:00
- have a working GitLab instance of version 8.0+r or are using
2016-06-14 20:58:20 -04:00
[GitLab.com ](https://gitlab.com )
2016-03-01 03:26:53 -05:00
- have a project in GitLab that you would like to use CI for
Let's break it down to pieces and work on solving the GitLab CI puzzle.
2015-08-25 21:42:46 -04:00
2015-12-01 03:05:24 -05:00
## Creating a `.gitlab-ci.yml` file
2015-11-06 03:43:28 -05:00
2015-12-01 03:05:24 -05:00
Before you create `.gitlab-ci.yml` let's first explain in brief what this is
all about.
2015-08-25 21:42:46 -04:00
2015-11-05 10:53:05 -05:00
### What is `.gitlab-ci.yml`
2015-08-25 21:42:46 -04:00
2015-11-05 10:53:05 -05:00
The `.gitlab-ci.yml` file is where you configure what CI does with your project.
It lives in the root of your repository.
2015-08-25 21:42:46 -04:00
2015-11-05 10:53:05 -05:00
On any push to your repository, GitLab will look for the `.gitlab-ci.yml`
2017-02-13 11:59:57 -05:00
file and start jobs on _Runners_ according to the contents of the file,
2015-11-05 10:53:05 -05:00
for that commit.
2015-08-25 21:42:46 -04:00
2016-06-14 21:12:39 -04:00
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.
You can read more about the reasons why we are using `.gitlab-ci.yml` [in our
blog about it][blog-ci].
2015-11-05 10:53:05 -05:00
### Creating a simple `.gitlab-ci.yml` file
2017-02-13 11:59:57 -05:00
>**Note:**
`.gitlab-ci.yml` is a [YAML ](https://en.wikipedia.org/wiki/YAML ) file
so you have to pay extra attention to indentation. Always use spaces, not tabs.
2015-11-05 10:53:05 -05:00
You need to create a file named `.gitlab-ci.yml` in the root directory of your
repository. Below is an example for a Ruby on Rails project.
2015-08-25 21:42:46 -04:00
```yaml
before_script:
2015-11-05 10:53:05 -05:00
- apt-get update -qq && apt-get install -y -qq sqlite3 libsqlite3-dev nodejs
- ruby -v
- which ruby
2018-12-27 09:19:41 -05:00
- gem install bundler --no-document
2015-11-05 10:53:05 -05:00
- bundle install --jobs $(nproc) "${FLAGS[@]}"
2015-08-25 21:42:46 -04:00
rspec:
script:
- bundle exec rspec
rubocop:
script:
- bundle exec rubocop
```
2017-02-13 11:59:57 -05:00
This is the simplest possible configuration that will work for most Ruby
2015-11-05 10:53:05 -05:00
applications:
2015-12-01 03:05:24 -05:00
1. Define two jobs `rspec` and `rubocop` (the names are arbitrary) with
different commands to be executed.
2015-11-05 10:53:05 -05:00
1. Before every job, the commands defined by `before_script` are executed.
The `.gitlab-ci.yml` file defines sets of jobs with constraints of how and when
2015-12-01 03:05:24 -05:00
they should be run. The jobs are defined as top-level elements with a name (in
our case `rspec` and `rubocop` ) and always have to contain the `script` keyword.
2017-02-13 11:59:57 -05:00
Jobs are used to create jobs, which are then picked by
2015-12-01 03:05:24 -05:00
[Runners ](../runners/README.md ) and executed within the environment of the Runner.
2015-11-05 10:53:05 -05:00
What is important is that each job is run independently from each other.
2015-08-25 21:42:46 -04:00
2018-03-22 16:22:31 -04:00
If you want to check whether the `.gitlab-ci.yml` of your project is valid, there is a
Lint tool under the page `/ci/lint` of your project namespace. You can also find
2017-09-09 09:44:14 -04:00
a "CI Lint" button to go to this page under **CI/CD ➔ Pipelines** and
2017-02-13 11:59:57 -05:00
**Pipelines ➔ Jobs** in your project.
2015-08-25 21:42:46 -04:00
2016-06-14 21:12:39 -04:00
For more information and a complete `.gitlab-ci.yml` syntax, please read
2017-02-13 11:59:57 -05:00
[the reference documentation on .gitlab-ci.yml ](../yaml/README.md ).
2015-08-25 21:42:46 -04:00
2015-11-05 10:53:05 -05:00
### Push `.gitlab-ci.yml` to GitLab
2015-08-25 21:42:46 -04:00
2017-02-13 11:59:57 -05:00
Once you've created `.gitlab-ci.yml` , you should add it to your Git repository
2015-11-05 10:53:05 -05:00
and push it to GitLab.
2015-08-25 21:42:46 -04:00
```bash
git add .gitlab-ci.yml
2015-11-05 10:53:05 -05:00
git commit -m "Add .gitlab-ci.yml"
2015-08-25 21:42:46 -04:00
git push origin master
```
2016-06-14 21:12:39 -04:00
Now if you go to the **Pipelines** page you will see that the pipeline is
pending.
2015-11-05 10:53:05 -05:00
2018-03-27 07:34:55 -04:00
NOTE: **Note:**
2019-02-02 01:47:09 -05:00
If you have a [mirrored repository where GitLab pulls from ](https://docs.gitlab.com/ee/workflow/repository_mirroring.html#pulling-from-a-remote-repository-starter ),
2018-03-27 07:34:55 -04:00
you may need to enable pipeline triggering in your project's
**Settings > Repository > Pull from a remote repository > Trigger pipelines for mirror updates**.
2017-02-13 11:59:57 -05:00
You can also go to the **Commits** page and notice the little pause icon next
2015-11-05 10:53:05 -05:00
to the commit SHA.
![New commit pending ](img/new_commit.png )
2017-02-13 11:59:57 -05:00
Clicking on it you will be directed to the jobs page for that specific commit.
2015-11-05 10:53:05 -05:00
2017-02-13 11:59:57 -05:00
![Single commit jobs page ](img/single_commit_status_pending.png )
2015-11-05 10:53:05 -05:00
2018-01-19 13:50:45 -05:00
Notice that there is a pending job which is named after what we wrote in
`.gitlab-ci.yml` . "stuck" indicates that there is no Runner configured
yet for this job.
2015-11-05 10:53:05 -05:00
2017-02-13 11:59:57 -05:00
The next step is to configure a Runner so that it picks the pending jobs.
2015-11-10 14:16:12 -05:00
2015-12-01 03:05:24 -05:00
## Configuring a Runner
2015-11-05 10:53:05 -05:00
2017-02-13 11:59:57 -05:00
In GitLab, Runners run the jobs that you define in `.gitlab-ci.yml` . A Runner
2016-06-14 21:12:39 -04:00
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,
2018-05-03 21:11:05 -04:00
so the only requirement is that the Runner's machine has network access to the
GitLab server.
2015-11-05 10:53:05 -05:00
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 ](../runners/README.md ) documentation.
You can find whether any Runners are assigned to your project by going to
2017-09-09 09:44:14 -04:00
**Settings ➔ CI/CD**. Setting up a Runner is easy and straightforward. The
2017-02-13 11:59:57 -05:00
official Runner supported by GitLab is written in Go and its documentation
can be found at < https: / / docs . gitlab . com / runner / > .
2015-11-05 10:53:05 -05:00
2015-12-01 03:05:24 -05:00
In order to have a functional Runner you need to follow two steps:
2015-11-05 10:53:05 -05:00
1. [Install it][runner-install]
2018-11-12 19:39:21 -05:00
1. [Configure it ](../runners/README.md#registering-a-specific-runner )
2015-11-05 10:53:05 -05:00
2015-12-01 03:05:24 -05:00
Follow the links above to set up your own Runner or use a Shared Runner as
described in the next section.
2015-11-05 10:53:05 -05:00
Once the Runner has been set up, you should see it on the Runners page of your
2017-09-09 09:44:14 -04:00
project, following **Settings ➔ CI/CD** .
2015-08-25 21:42:46 -04:00
2015-11-05 10:53:05 -05:00
![Activated runners ](img/runners_activated.png )
2015-08-25 21:42:46 -04:00
2015-11-05 10:53:05 -05:00
### Shared Runners
2015-08-25 21:42:46 -04:00
2017-02-13 11:59:57 -05:00
If you use [GitLab.com ](https://gitlab.com/ ) you can use the **Shared Runners**
2015-11-05 10:53:05 -05:00
provided by GitLab Inc.
2015-08-25 21:42:46 -04:00
2015-12-01 03:05:24 -05:00
These are special virtual machines that run on GitLab's infrastructure and can
build any project.
2015-08-25 21:42:46 -04:00
2017-02-13 11:59:57 -05:00
To enable the **Shared Runners** you have to go to your project's
2017-09-09 09:44:14 -04:00
**Settings ➔ CI/CD** and click **Enable shared runners** .
2015-08-25 21:42:46 -04:00
2015-11-05 10:53:05 -05:00
[Read more on Shared Runners ](../runners/README.md ).
2015-08-25 21:42:46 -04:00
2017-02-13 11:59:57 -05:00
## Seeing the status of your pipeline and jobs
2015-08-25 21:42:46 -04:00
2016-02-19 16:17:28 -05:00
After configuring the Runner successfully, you should see the status of your
2015-11-05 10:53:05 -05:00
last commit change from _pending_ to either _running_ , _success_ or _failed_ .
2015-08-25 21:42:46 -04:00
2016-06-14 21:12:39 -04:00
You can view all pipelines by going to the **Pipelines** page in your project.
![Commit status ](img/pipelines_status.png )
2017-02-13 11:59:57 -05:00
Or you can view all jobs, by going to the **Pipelines ➔ Jobs** page.
2015-08-25 21:42:46 -04:00
2015-11-05 10:53:05 -05:00
![Commit status ](img/builds_status.png )
2015-08-25 21:42:46 -04:00
2017-02-13 11:59:57 -05:00
By clicking on a job's status, you will be able to see the log of that job.
This is important to diagnose why a job failed or acted differently than
2015-11-05 10:53:05 -05:00
you expected.
2015-08-25 21:42:46 -04:00
2015-11-05 10:53:05 -05:00
![Build log ](img/build_log.png )
2015-08-25 21:42:46 -04:00
2015-11-05 10:53:05 -05:00
You are also able to view the status of any commit in the various pages in
2017-02-13 11:59:57 -05:00
GitLab, such as **Commits** and **Merge requests** .
2015-08-25 21:42:46 -04:00
2016-02-29 07:50:08 -05:00
## Examples
Visit the [examples README][examples] to see a list of examples using GitLab
CI with various languages.
2017-02-13 11:59:57 -05:00
[runner-install]: https://docs.gitlab.com/runner/install/
2015-11-05 10:53:05 -05:00
[blog-ci]: https://about.gitlab.com/2015/05/06/why-were-replacing-gitlab-ci-jobs-with-gitlab-ci-dot-yml/
2016-02-29 07:50:08 -05:00
[examples]: ../examples/README.md
2016-03-01 03:26:53 -05:00
[ci]: https://about.gitlab.com/gitlab-ci/
[yaml]: ../yaml/README.md
[runner]: ../runners/README.md
[enabled]: ../enable_or_disable_ci.md
[stages]: ../yaml/README.md#stages
2016-06-22 01:15:21 -04:00
[pipeline]: ../pipelines.md