README.md 8.74 KB
Newer Older
Marcia Ramos's avatar
Marcia Ramos committed
1
---
2 3 4
stage: Verify
group: Continuous Integration
info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/engineering/ux/technical-writing/#designated-technical-writers
Marcia Ramos's avatar
Marcia Ramos committed
5 6 7
type: reference
---

8
# Getting started with GitLab CI/CD
Douwe Maan's avatar
Douwe Maan committed
9

Marcel Amirault's avatar
Marcel Amirault committed
10
GitLab offers a [continuous integration](https://about.gitlab.com/stages-devops-lifecycle/continuous-integration/) service. For each commit or push to trigger your CI
11
[pipeline](../pipelines/index.md), you must:
12

Nick Gaskill's avatar
Nick Gaskill committed
13 14
- Add a [`.gitlab-ci.yml` file](#creating-a-gitlab-ciyml-file) to your repository's root directory.
- Ensure your project is configured to use a [Runner](#configuring-a-runner).
15

Nick Gaskill's avatar
Nick Gaskill committed
16 17
The `.gitlab-ci.yml` file tells the GitLab Runner what to do. A simple pipeline commonly has
three [stages](../yaml/README.md#stages):
18

Nick Gaskill's avatar
Nick Gaskill committed
19 20 21
- `build`
- `test`
- `deploy`
Douwe Maan's avatar
Douwe Maan committed
22

Nick Gaskill's avatar
Nick Gaskill committed
23
You do not need to use all three stages; stages with no jobs are ignored.
24

Nick Gaskill's avatar
Nick Gaskill committed
25 26 27 28 29
The pipeline appears under the project's **CI/CD > Pipelines** page. If everything runs OK (no non-zero
return values), you get a green check mark 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 job (test) log. Many projects use
GitLab's CI service to run the test suite, so developers get immediate feedback if they broke
something.
Douwe Maan's avatar
Douwe Maan committed
30

Nick Gaskill's avatar
Nick Gaskill committed
31 32
It's also common to use pipelines to automatically deploy
tested code to staging and production environments.
Douwe Maan's avatar
Douwe Maan committed
33

34 35 36 37 38
If you're already familiar with general CI/CD concepts, you can review which
[pipeline architectures](../pipelines/pipeline_architectures.md) can be used
in your projects. If you're coming over to GitLab from Jenkins, you can check out
our [reference](../migration/jenkins.md) for converting your pre-existing pipelines
over to our format.
39

Marcia Ramos's avatar
Marcia Ramos committed
40
This guide assumes that you have:
41

Philipp C. H.'s avatar
Philipp C. H. committed
42
- A working GitLab instance of version 8.0+ or are using
Marcia Ramos's avatar
Marcia Ramos committed
43 44
  [GitLab.com](https://gitlab.com).
- A project in GitLab that you would like to use CI for.
45
- Maintainer or owner access to the project
46

Marcel Amirault's avatar
Marcel Amirault committed
47
Let's break it down to pieces and work on solving the GitLab CI/CD puzzle.
Douwe Maan's avatar
Douwe Maan committed
48

49
## Creating a `.gitlab-ci.yml` file
50

51 52
Before you create `.gitlab-ci.yml` let's first explain in brief what this is
all about.
Douwe Maan's avatar
Douwe Maan committed
53

54
### What is `.gitlab-ci.yml`
Douwe Maan's avatar
Douwe Maan committed
55

56 57
The `.gitlab-ci.yml` file is where you configure what CI does with your project.
It lives in the root of your repository.
Douwe Maan's avatar
Douwe Maan committed
58

59
On any push to your repository, GitLab will look for the `.gitlab-ci.yml`
60
file and start jobs on _Runners_ according to the contents of the file,
61
for that commit.
Douwe Maan's avatar
Douwe Maan committed
62

Mark Pundsack's avatar
Mark Pundsack committed
63 64 65 66
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
67
blog about it](https://about.gitlab.com/blog/2015/05/06/why-were-replacing-gitlab-ci-jobs-with-gitlab-ci-dot-yml/).
68 69 70

### Creating a simple `.gitlab-ci.yml` file

71
NOTE: **Note:**
72 73 74
A GitLab team member has made an [unofficial visual pipeline editor](https://unofficial.gitlab.tools/visual-pipelines/).
There is a [plan to make it an official part of GitLab](https://gitlab.com/groups/gitlab-org/-/epics/4069)
in the future, but it's available for anyone who wants to try it at the above link.
75

76 77
You need to create a file named `.gitlab-ci.yml` in the root directory of your
repository. This is a [YAML](https://en.wikipedia.org/wiki/YAML) file
78 79
so you have to pay extra attention to indentation. Always use spaces, not tabs.

80
Below is an example for a Ruby on Rails project:
Douwe Maan's avatar
Douwe Maan committed
81 82

```yaml
83 84
image: "ruby:2.5"

Douwe Maan's avatar
Douwe Maan committed
85
before_script:
86 87 88
  - apt-get update -qq && apt-get install -y -qq sqlite3 libsqlite3-dev nodejs
  - ruby -v
  - which ruby
89
  - gem install bundler --no-document
90
  - bundle install --jobs $(nproc)  "${FLAGS[@]}"
Douwe Maan's avatar
Douwe Maan committed
91 92 93 94 95 96 97 98 99 100

rspec:
  script:
    - bundle exec rspec

rubocop:
  script:
    - bundle exec rubocop
```

101
This is the simplest possible configuration that will work for most Ruby
102 103
applications:

104 105
1. Define two jobs `rspec` and `rubocop` (the names are arbitrary) with
   different commands to be executed.
106 107 108
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
109 110
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.
111
Jobs are used to create jobs, which are then picked by
112
[Runners](../runners/README.md) and executed within the environment of the Runner.
113 114

What is important is that each job is run independently from each other.
Douwe Maan's avatar
Douwe Maan committed
115

116
If you want to check whether the `.gitlab-ci.yml` of your project is valid, there is a
Damian Nowak's avatar
Damian Nowak committed
117
Lint tool under the page `/-/ci/lint` of your project namespace. You can also find
118
a "CI Lint" button to go to this page under **CI/CD ➔ Pipelines** and
119
**Pipelines ➔ Jobs** in your project.
Douwe Maan's avatar
Douwe Maan committed
120

Mark Pundsack's avatar
Mark Pundsack committed
121
For more information and a complete `.gitlab-ci.yml` syntax, please read
122
[the reference documentation on `.gitlab-ci.yml`](../yaml/README.md).
Douwe Maan's avatar
Douwe Maan committed
123

124
### Push `.gitlab-ci.yml` to GitLab
Douwe Maan's avatar
Douwe Maan committed
125

126
Once you've created `.gitlab-ci.yml`, you should add it to your Git repository
127
and push it to GitLab.
Douwe Maan's avatar
Douwe Maan committed
128

129
```shell
Douwe Maan's avatar
Douwe Maan committed
130
git add .gitlab-ci.yml
131
git commit -m "Add .gitlab-ci.yml"
Douwe Maan's avatar
Douwe Maan committed
132 133 134
git push origin master
```

Mark Pundsack's avatar
Mark Pundsack committed
135 136
Now if you go to the **Pipelines** page you will see that the pipeline is
pending.
137

138
NOTE: **Note:**
139
If you have a [mirrored repository where GitLab pulls from](../../user/project/repository/repository_mirroring.md#pulling-from-a-remote-repository-starter),
140 141 142
you may need to enable pipeline triggering in your project's
**Settings > Repository > Pull from a remote repository > Trigger pipelines for mirror updates**.

143
You can also go to the **Commits** page and notice the little pause icon next
144 145 146 147
to the commit SHA.

![New commit pending](img/new_commit.png)

148
Clicking on it you will be directed to the jobs page for that specific commit.
149

150
![Single commit jobs page](img/single_commit_status_pending.png)
151

152 153 154
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.
155

156
The next step is to configure a Runner so that it picks the pending jobs.
157

158
## Configuring a Runner
159

160
In GitLab, Runners run the jobs that you define in `.gitlab-ci.yml`. A Runner
Evan Read's avatar
Evan Read committed
161
can be a virtual machine, a VPS, a bare-metal machine, a Docker container or
Mark Pundsack's avatar
Mark Pundsack committed
162
even a cluster of containers. GitLab and the Runners communicate through an API,
Ben Bodenmiller's avatar
Ben Bodenmiller committed
163 164
so the only requirement is that the Runner's machine has network access to the
GitLab server.
165 166 167 168 169 170 171 172

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
173
**Settings ➔ CI/CD**. Setting up a Runner is easy and straightforward. The
174 175
official Runner supported by GitLab is written in Go and its documentation
can be found at <https://docs.gitlab.com/runner/>.
176

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

179
1. [Install it](https://docs.gitlab.com/runner/install/)
Suzanne Selhorn's avatar
Suzanne Selhorn committed
180
1. [Configure it](https://docs.gitlab.com/runner/configuration/)
181

182 183 184
Follow the links above to set up your own Runner or use a Shared Runner as
described in the next section.

185
Once the Runner has been set up, you should see it on the Runners page of your
186
project, following **Settings ➔ CI/CD**.
Douwe Maan's avatar
Douwe Maan committed
187

188
![Activated runners](img/runners_activated.png)
Douwe Maan's avatar
Douwe Maan committed
189

190
### Shared Runners
Douwe Maan's avatar
Douwe Maan committed
191

192
If you use [GitLab.com](https://gitlab.com/) you can use the **Shared Runners**
193
provided by GitLab Inc.
Douwe Maan's avatar
Douwe Maan committed
194

195 196
These are special virtual machines that run on GitLab's infrastructure and can
build any project.
Douwe Maan's avatar
Douwe Maan committed
197

198
To enable the **Shared Runners** you have to go to your project's
199
**Settings ➔ CI/CD** and click **Enable shared runners**.
Douwe Maan's avatar
Douwe Maan committed
200

201
[Read more on Shared Runners](../runners/README.md).
Douwe Maan's avatar
Douwe Maan committed
202

203
## Seeing the status of your pipeline and jobs
Douwe Maan's avatar
Douwe Maan committed
204

205
After configuring the Runner successfully, you should see the status of your
206
last commit change from _pending_ to either _running_, _success_ or _failed_.
Douwe Maan's avatar
Douwe Maan committed
207

Mark Pundsack's avatar
Mark Pundsack committed
208 209 210 211
You can view all pipelines by going to the **Pipelines** page in your project.

![Commit status](img/pipelines_status.png)

212
Or you can view all jobs, by going to the **Pipelines ➔ Jobs** page.
Douwe Maan's avatar
Douwe Maan committed
213

214
![Commit status](img/builds_status.png)
Douwe Maan's avatar
Douwe Maan committed
215

216 217
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
218
you expected.
Douwe Maan's avatar
Douwe Maan committed
219

220
![Build log](img/build_log.png)
Douwe Maan's avatar
Douwe Maan committed
221

222
You are also able to view the status of any commit in the various pages in
223
GitLab, such as **Commits** and **Merge requests**.
Douwe Maan's avatar
Douwe Maan committed
224

Achilleas Pipinellis's avatar
Achilleas Pipinellis committed
225 226
## Examples

227
Visit the [examples README](../examples/README.md) to see a list of examples using GitLab
Achilleas Pipinellis's avatar
Achilleas Pipinellis committed
228
CI with various languages.