README.md 8.4 KB
Newer Older
1 2
# Quick Start

3 4 5
>**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.
6

7
The TL;DR version of how GitLab CI works is the following.
8

9 10 11 12 13 14 15 16 17 18 19 20 21 22 23 24 25
---

GitLab offers a [continuous integration][ci] service. If you
[add a `.gitlab-ci.yml` file][yaml] to the root directory of your repository,
and configure your GitLab project to use a [Runner], then each merge request or
push triggers a build.

The `.gitlab-ci.yml` file tells the GitLab runner what do to. By default it
runs three [stages]: `build`, `test`, and `deploy`.

If everything runs OK (no non-zero return values), you'll get a nice green
checkmark associated with the pushed commit or merge request. This makes it
easy to see whether a merge request will cause any of the tests to fail before
you even look at the code.

Most projects only use GitLab's CI service to run the test suite so that
developers get immediate feedback if they broke something.
26

27
So in brief, the steps needed to have a working CI can be summed up to:
28

29
1. Add `.gitlab-ci.yml` to the root directory of your repository
30
1. Configure a Runner
31

32
From there on, on every push to your Git repository, the build will be
33
automagically started by the Runner and will appear under the project's
34
`/builds` page.
35

36 37 38 39 40 41 42 43 44
---

This guide assumes that you:

- have a working GitLab instance of version 8.0 or higher or are using
  [GitLab.com](https://gitlab.com/users/sign_in)
- 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.
45

46
## Creating a `.gitlab-ci.yml` file
47

48 49
Before you create `.gitlab-ci.yml` let's first explain in brief what this is
all about.
50

51
### What is `.gitlab-ci.yml`
52

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

56 57 58
On any push to your repository, GitLab will look for the `.gitlab-ci.yml`
file and start builds on _Runners_ according to the contents of the file,
for that commit.
59

60
Because `.gitlab-ci.yml` is in the repository, it is version controlled,
61
old versions still build successfully, forks can easily make use of CI,
62 63 64 65
branches can have separate builds 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].

66
**Note:** `.gitlab-ci.yml` is a [YAML](https://en.wikipedia.org/wiki/YAML) file
67
so you have to pay extra attention to the indentation. Always use spaces, not
68
tabs.
69 70 71 72 73

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

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.
74 75 76

```yaml
before_script:
77 78 79 80 81
  - apt-get update -qq && apt-get install -y -qq sqlite3 libsqlite3-dev nodejs
  - ruby -v
  - which ruby
  - gem install bundler --no-ri --no-rdoc
  - bundle install --jobs $(nproc)  "${FLAGS[@]}"
82 83 84 85 86 87 88 89 90 91

rspec:
  script:
    - bundle exec rspec

rubocop:
  script:
    - bundle exec rubocop
```

92 93 94
This is the simplest possible build configuration that will work for most Ruby
applications:

95 96
1. Define two jobs `rspec` and `rubocop` (the names are arbitrary) with
   different commands to be executed.
97 98 99
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
100 101 102 103
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.
Jobs are used to create builds, which are then picked by
[Runners](../runners/README.md) and executed within the environment of the Runner.
104 105

What is important is that each job is run independently from each other.
106

107 108
If you want to check whether your `.gitlab-ci.yml` file is valid, there is a
Lint tool under the page `/ci/lint` of your GitLab instance. You can also find
109
the link under **Settings > CI settings** in your project.
110

111 112
For more information and a complete `.gitlab-ci.yml` syntax, please check
[the documentation on .gitlab-ci.yml](../yaml/README.md).
113

114
### Push `.gitlab-ci.yml` to GitLab
115

116 117
Once you've created `.gitlab-ci.yml`, you should add it to your git repository
and push it to GitLab.
118 119 120

```bash
git add .gitlab-ci.yml
121
git commit -m "Add .gitlab-ci.yml"
122 123 124
git push origin master
```

125 126 127 128 129 130 131 132 133 134 135 136 137 138 139 140
Now if you go to the **Builds** page you will see that the builds are pending.

You can also go to the **Commits** page and notice the little clock icon next
to the commit SHA.

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

Clicking on the clock icon you will be directed to the builds page for that
specific commit.

![Single commit builds page](img/single_commit_status_pending.png)

Notice that there are two jobs pending which are named after what we wrote in
`.gitlab-ci.yml`. The red triangle indicates that there is no Runner configured
yet for these builds.

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

143
## Configuring a Runner
144 145 146 147 148

In GitLab, Runners run the builds 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 needed requirement is that the machine on which the
Mike Milonakis's avatar
Mike Milonakis committed
149
Runner is configured to have Internet access.
150 151 152 153 154 155 156 157

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
158 159
**Settings > Runners**. Setting up a Runner is easy and straightforward. The
official Runner supported by GitLab is written in Go and can be found at
160 161
<https://gitlab.com/gitlab-org/gitlab-ci-multi-runner>.

162
In order to have a functional Runner you need to follow two steps:
163 164 165 166

1. [Install it][runner-install]
2. [Configure it](../runners/README.md#registering-a-specific-runner)

167 168 169
Follow the links above to set up your own Runner or use a Shared Runner as
described in the next section.

170 171 172 173
For other types of unofficial Runners written in other languages, see the
[instructions for the various GitLab Runners](https://about.gitlab.com/gitlab-ci/#gitlab-runner).

Once the Runner has been set up, you should see it on the Runners page of your
174
project, following **Settings > Runners**.
175

176
![Activated runners](img/runners_activated.png)
177

178
### Shared Runners
179

180 181
If you use [GitLab.com](https://gitlab.com/) you can use **Shared Runners**
provided by GitLab Inc.
182

183 184
These are special virtual machines that run on GitLab's infrastructure and can
build any project.
185

186
To enable **Shared Runners** you have to go to your project's
187
**Settings > Runners** and click **Enable shared runners**.
188

189
[Read more on Shared Runners](../runners/README.md).
190

191
## Seeing the status of your build
192

193
After configuring the Runner successfully, you should see the status of your
194
last commit change from _pending_ to either _running_, _success_ or _failed_.
195

196
You can view all builds, by going to the **Builds** page in your project.
197

198
![Commit status](img/builds_status.png)
199

200 201 202
By clicking on a Build ID, you will be able to see the log of that build.
This is important to diagnose why a build failed or acted differently than
you expected.
203

204
![Build log](img/build_log.png)
205

206 207
You are also able to view the status of any commit in the various pages in
GitLab, such as **Commits** and **Merge Requests**.
208

209 210
## Enabling build emails

211 212 213
If you want to receive e-mail notifications about the result status of the
builds, you should explicitly enable the **Builds Emails** service under your
project's settings.
214

215 216
For more information read the [Builds emails service documentation]
(../../project_services/builds_emails.md).
217

218 219 220 221 222
## Builds badge

You can access a builds badge image using following link:

```
223
http://example.gitlab.com/namespace/project/badges/branch/build.svg
224 225
```

226 227
Awesome! You started using CI in GitLab!

228 229 230 231 232
## Examples

Visit the [examples README][examples] to see a list of examples using GitLab
CI with various languages.

233 234
[runner-install]: https://gitlab.com/gitlab-org/gitlab-ci-multi-runner/tree/master#installation
[blog-ci]: https://about.gitlab.com/2015/05/06/why-were-replacing-gitlab-ci-jobs-with-gitlab-ci-dot-yml/
235
[examples]: ../examples/README.md
236 237 238 239 240
[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