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