BigW Consortium Gitlab

README.md 8.09 KB
Newer Older
1
# Getting started with GitLab CI/CD
2

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 8
GitLab offers a [continuous integration][ci] service. If you
[add a `.gitlab-ci.yml` file][yaml] to the root directory of your repository,
Alex Karnovsky committed
9
and configure your GitLab project to use a [Runner], then each commit or
10
push, triggers your CI [pipeline].
11

Mark Pundsack committed
12 13 14
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.
15 16

If everything runs OK (no non-zero return values), you'll get a nice green
Alex Karnovsky committed
17 18
checkmark associated with the commit. This makes it
easy to see whether a commit caused any of the tests to fail before
19 20
you even look at the code.

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

24 25 26
There's a growing trend to use continuous delivery and continuous deployment to
automatically deploy tested code to staging and production environments.

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 33
From there on, on every push to your Git repository, the Runner will
automagically start the pipeline and the pipeline will appear under the
34
project's **Pipelines** page.
35

36 37 38 39
---

This guide assumes that you:

40
- have a working GitLab instance of version 8.0+r or are using
41
  [GitLab.com](https://gitlab.com)
42 43 44
- 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
On any push to your repository, GitLab will look for the `.gitlab-ci.yml`
57
file and start jobs on _Runners_ according to the contents of the file,
58
for that commit.
59

Mark Pundsack committed
60 61 62 63 64
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].
65 66 67

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

68 69 70 71
>**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.

72 73
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
This is the simplest possible configuration that will work for most Ruby
93 94
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
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.
102
Jobs are used to create jobs, which are then picked by
103
[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
a "CI Lint" button to go to this page under **CI/CD ➔ Pipelines** and
110
**Pipelines ➔ Jobs** in your project.
111

Mark Pundsack committed
112
For more information and a complete `.gitlab-ci.yml` syntax, please read
113
[the reference documentation on .gitlab-ci.yml](../yaml/README.md).
114

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

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

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

Mark Pundsack committed
126 127
Now if you go to the **Pipelines** page you will see that the pipeline is
pending.
128

129
You can also go to the **Commits** page and notice the little pause icon next
130 131 132 133
to the commit SHA.

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

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

136
![Single commit jobs page](img/single_commit_status_pending.png)
137 138 139

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
140
yet for these jobs.
141

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

144
## Configuring a Runner
145

146
In GitLab, Runners run the jobs that you define in `.gitlab-ci.yml`. A Runner
Mark Pundsack committed
147 148
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,
149
so the only requirement is that the Runner's machine has [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
**Settings ➔ CI/CD**. Setting up a Runner is easy and straightforward. The
159 160
official Runner supported by GitLab is written in Go and its documentation
can be found at <https://docs.gitlab.com/runner/>.
161

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
Once the Runner has been set up, you should see it on the Runners page of your
171
project, following **Settings ➔ CI/CD**.
172

173
![Activated runners](img/runners_activated.png)
174

175
### Shared Runners
176

177
If you use [GitLab.com](https://gitlab.com/) you can use the **Shared Runners**
178
provided by GitLab Inc.
179

180 181
These are special virtual machines that run on GitLab's infrastructure and can
build any project.
182

183
To enable the **Shared Runners** you have to go to your project's
184
**Settings ➔ CI/CD** and click **Enable shared runners**.
185

186
[Read more on Shared Runners](../runners/README.md).
187

188
## Seeing the status of your pipeline and jobs
189

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

Mark Pundsack committed
193 194 195 196
You can view all pipelines by going to the **Pipelines** page in your project.

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

197
Or you can view all jobs, by going to the **Pipelines ➔ Jobs** page.
198

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

201 202
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
203
you expected.
204

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

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

210 211 212 213 214
## Examples

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

215
[runner-install]: https://docs.gitlab.com/runner/install/
216
[blog-ci]: https://about.gitlab.com/2015/05/06/why-were-replacing-gitlab-ci-jobs-with-gitlab-ci-dot-yml/
217
[examples]: ../examples/README.md
218 219 220 221 222
[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
Mark Pundsack committed
223
[pipeline]: ../pipelines.md
224
[internet]: https://about.gitlab.com/images/theinternet.png