1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
|
# Quick Start
GitLab Continuous Integration (CI) is fully integrated into GitLab itself. You
only need to enable it in the Services settings of your project.
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
In brief, the steps needed to have a working CI can be summed up to:
1. Create a new project
1. Add `.gitlab-ci.yml` to the git repository and push to GitLab
1. Configure a Runner
From there on, on every push to your git repository the build will be
automagically started by the runner and will appear under the project's `/builds`
page.
Now, let's break it down to pieces and work on solving the GitLab CI puzzle.
## 1. Creating a `.gitlab-ci.yml` file
**GitLab CI** service is enabled automatically on the first push of a
`.gitlab-ci.yml` file in your repository and this is the recommended way.
For other methods read [how to enable the GitLab CI service](../enable_ci.md).
### What is `.gitlab-ci.yml`
The `.gitlab-ci.yml` file is where you configure what CI does with your project.
It lives in the root of your repository.
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.
Because `.gitlab-ci.yml` is in the repository, it is version controlled,
old versions still build succesfully, forks can easily make use of CI,
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].
`.gitlab-ci.yml` is a [YAML](https://en.wikipedia.org/wiki/YAML) file.
### 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.
```yaml
before_script:
- 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[@]}"
rspec:
script:
- bundle exec rspec
rubocop:
script:
- bundle exec rubocop
```
This is the simplest possible build configuration that will work for most Ruby
applications:
1. Define two jobs `rspec` and `rubocop` with different commands to be executed.
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
they should be run. The jobs are defined as top-level elements with a name and
always have to contain the `script` name. Jobs are used to create builds,
which are then picked by [Runners](../runners/README.md) and executed within
the environment of the Runner.
What is important is that each job is run independently from each other.
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
the link under **Settings** -> **CI settings** in your project.
For more information and a complete `.gitlab-ci.yml` syntax, please check
[the documentation on .gitlab-ci.yml](../yaml/README.md).
### Push `.gitlab-ci.yml` to GitLab
Once you've created `.gitlab-ci.yml`, you should add it to your git repository
and push it to GitLab.
```bash
git add .gitlab-ci.yml
git commit -m "Add .gitlab-ci.yml"
git push origin master
```
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.
The next step is to configure a Runner so that it picks the pending jobs.
## 2. Configuring a Runner
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
Runner is configured to have Internet access.
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
**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
<https://gitlab.com/gitlab-org/gitlab-ci-multi-runner>.
In order to have a functional Runner you need to:
1. [Install it][runner-install]
2. [Configure it](../runners/README.md#registering-a-specific-runner)
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
project, following **Settings** -> **Runners**.
![Activated runners](img/runners_activated.png)
### Shared Runners
If you use [GitLab.com](https://gitlab.com/) you can use **Shared Runners**
provided by GitLab Inc.
These are special virtual machines that are run on GitLab's infrastructure that
can build any project.
To enable **Shared Runners** you have to go to your project's
**Settings** -> **Runners** and click **Enable shared runners**.
[Read more on Shared Runners](../runners/README.md).
## 3. Seeing the status of your build
After configuring the Runner succesfully, you should see the status of your
last commit change from _pending_ to either _running_, _success_ or _failed_.
You can view all builds, by going to the **Builds** page in your project.
![Commit status](img/builds_status.png)
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.
![Build log](img/build_log.png)
You are also able to view the status of any commit in the various pages in
GitLab, such as **Commits** and **Merge Requests**.
## Next steps
Awesome! You started using CI in GitLab!
Next you can look into doing more with the CI. Many people are using GitLab
to package, containerize, test and deploy software.
We have a number of [examples](../examples/README.md) available.
[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/
|