Read about our upcoming Code of Conduct on this issue

settings.md 7.32 KB
Newer Older
1
# Pipelines settings
2

3
To reach the pipelines settings navigate to your project's
Evan Read's avatar
Evan Read committed
4
**Settings > CI/CD**.
5

6
The following settings can be configured per project.
7

8
9
10
11
12
## Git strategy

With Git strategy, you can choose the default way your repository is fetched
from GitLab in a job.

Evan Read's avatar
Evan Read committed
13
There are two options. Using:
14

Evan Read's avatar
Evan Read committed
15
- `git clone`, which is slower since it clones the repository from scratch
16
  for every job, ensuring that the project workspace is always pristine.
Evan Read's avatar
Evan Read committed
17
- `git fetch`, which is faster as it re-uses the project workspace (falling
18
19
  back to clone if it doesn't exist).

Evan Read's avatar
Evan Read committed
20
The default Git strategy can be overridden by the [GIT_STRATEGY variable](../../../ci/yaml/README.md#git-strategy)
21
in `.gitlab-ci.yml`.
22

23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
## Git shallow clone

> [Introduced](https://gitlab.com/gitlab-org/gitlab-ce/merge_requests/28919) in GitLab 12.0.

NOTE: **Note**: As of GitLab 12.0, newly created projects will automaticallyl have a default 
`git depth` value of `50`.

It is possible to limit the number of changes that GitLab CI/CD will fetch when cloning 
a repository. Setting a limit to `git depth` can speed up Pipelines execution. Maximum
allowed value is `1000`.

To disable shallow clone and make GitLab CI/CD fetch all branches and tags each time,
keep the value empty or set to `0`.

This value can also be [overridden by `GIT_DEPTH`](../../../ci/large_repositories/index.md#shallow-cloning) variable in `.gitlab-ci.yml` file.

39
40
## Timeout

41
Timeout defines the maximum amount of time in minutes that a job is able run.
Takuya Noguchi's avatar
Takuya Noguchi committed
42
This is configurable under your project's **Settings > CI/CD > General pipelines settings**.
43
44
45
The default value is 60 minutes. Decrease the time limit if you want to impose
a hard limit on your jobs' running time or increase it otherwise. In any case,
if the job surpasses the threshold, it is marked as failed.
46

Tomasz Maczukin's avatar
Tomasz Maczukin committed
47
48
### Timeout overriding on Runner level

Evan Read's avatar
Evan Read committed
49
> [Introduced](https://gitlab.com/gitlab-org/gitlab-ce/merge_requests/17221) in GitLab 10.7.
Tomasz Maczukin's avatar
Tomasz Maczukin committed
50
51

Project defined timeout (either specific timeout set by user or the default
Evan Read's avatar
Evan Read committed
52
60 minutes timeout) may be [overridden on Runner level](../../../ci/runners/README.html#setting-maximum-job-timeout-for-a-runner).
Tomasz Maczukin's avatar
Tomasz Maczukin committed
53

54
## Custom CI config path
55

Evan Read's avatar
Evan Read committed
56
> [Introduced](https://gitlab.com/gitlab-org/gitlab-ce/merge_requests/12509) in GitLab 9.4.
57

Lin Jen-Shin's avatar
Lin Jen-Shin committed
58
59
By default we look for the `.gitlab-ci.yml` file in the project's root
directory. If you require a different location **within** the repository,
60
you can set a custom filepath that will be used to lookup the config file,
61
62
63
64
this filepath should be **relative** to the root.

Here are some valid examples:

65
66
67
68
- `.gitlab-ci.yml`
- `.my-custom-file.yml`
- `my/path/.gitlab-ci.yml`
- `my/path/.my-custom-file.yml`
69

70
71
72
## Test coverage parsing

If you use test coverage in your code, GitLab can capture its output in the
73
job log using a regular expression. In the pipelines settings, search for the
74
"Test coverage parsing" section.
75

76
77
78
![Pipelines settings test coverage](img/pipelines_settings_test_coverage.png)

Leave blank if you want to disable it or enter a ruby regular expression. You
Evan Read's avatar
Evan Read committed
79
can use <http://rubular.com> to test your regex.
80
81

If the pipeline succeeds, the coverage is shown in the merge request widget and
82
in the jobs table.
83
84
85
86
87
88
89

![MR widget coverage](img/pipelines_test_coverage_mr_widget.png)

![Build status coverage](img/pipelines_test_coverage_build.png)

A few examples of known coverage tools for a variety of languages can be found
in the pipelines settings page.
90
91
92

## Visibility of pipelines

93
94
Access to pipelines and job details (including output of logs and artifacts)
is checked against your current user access level and the **Public pipelines**
95
project setting under your project's **Settings > CI/CD > General pipelines settings**.
96
97
98

If **Public pipelines** is enabled (default):

Evan Read's avatar
Evan Read committed
99
100
101
- For **public** projects, anyone can view the pipelines and access the job details
  (output logs and artifacts).
- For **internal** projects, any logged in user can view the pipelines
102
  and access the job details
Evan Read's avatar
Evan Read committed
103
104
  (output logs and artifacts).
- For **private** projects, any member (guest or higher) can view the pipelines
105
  and access the job details
Evan Read's avatar
Evan Read committed
106
  (output logs and artifacts).
107
108
109

If **Public pipelines** is disabled:

Evan Read's avatar
Evan Read committed
110
111
112
113
114
115
116
- For **public** projects, anyone can view the pipelines, but only members
  (reporter or higher) can access the job details (output logs and artifacts).
- For **internal** projects, any logged in user can view the pipelines.
  However, only members (reporter or higher) can access the job details (output logs
  and artifacts).
- For **private** projects, only members (reporter or higher)
  can view the pipelines and access the job details (output logs and artifacts).
117

118
119
## Auto-cancel pending pipelines

Evan Read's avatar
Evan Read committed
120
> [Introduced](https://gitlab.com/gitlab-org/gitlab-ce/merge_requests/9362) in GitLab 9.1.
121

122
123
If you want to auto-cancel all pending non-HEAD pipelines on branch, when
new pipeline will be created (after your git push or manually from UI),
124
125
check **Auto-cancel pending pipelines** checkbox and save the changes.

126
## Pipeline Badges
127

128
In the pipelines settings page you can find pipeline status and test coverage
129
badges for your project. The latest successful pipeline will be used to read
130
the pipeline status and test coverage values.
131

132
Visit the pipelines settings page in your project to see the exact link to
133
134
135
136
137
your badges, as well as ways to embed the badge image in your HTML or Markdown
pages.

![Pipelines badges](img/pipelines_settings_badges.png)

138
### Pipeline status badge
139

140
Depending on the status of your job, a badge can have the following values:
141

142
- pending
143
- running
144
- passed
145
146
- failed
- skipped
147
- canceled
148
149
- unknown

150
You can access a pipeline status badge image using the following link:
151

Evan Read's avatar
Evan Read committed
152
```text
153
https://example.gitlab.com/<namespace>/<project>/badges/<branch>/pipeline.svg
154
```
155

156
### Test coverage report badge
157

Evan Read's avatar
Evan Read committed
158
GitLab makes it possible to define the regular expression for [coverage report](#test-coverage-parsing),
159
that each job log will be matched against. This means that each job in the
160
pipeline can have the test coverage percentage value defined.
161

162
The test coverage badge can be accessed using following link:
163

Evan Read's avatar
Evan Read committed
164
```text
165
166
https://example.gitlab.com/<namespace>/<project>/badges/<branch>/coverage.svg
```
167

168
169
170
171
If you would like to get the coverage report from a specific job, you can add
the `job=coverage_job_name` parameter to the URL. For example, the following
Markdown code will embed the test coverage report badge of the `coverage` job
into your `README.md`:
172

173
174
175
```markdown
![coverage](https://gitlab.com/gitlab-org/gitlab-ce/badges/master/coverage.svg?job=coverage)
```
176

Fabian Schneider's avatar
Fabian Schneider committed
177
178
179
180
181
182
### Badge styles

Pipeline badges can be rendered in different styles by adding the `style=style_name` parameter to the URL. Currently two styles are available:

#### Flat (default)

Evan Read's avatar
Evan Read committed
183
```text
Fabian Schneider's avatar
Fabian Schneider committed
184
185
186
187
188
189
190
https://example.gitlab.com/<namespace>/<project>/badges/<branch>/coverage.svg?style=flat
```

![Badge flat style](https://gitlab.com/gitlab-org/gitlab-ce/badges/master/coverage.svg?job=coverage&style=flat)

#### Flat square

Evan Read's avatar
Evan Read committed
191
192
193
> [Introduced](https://gitlab.com/gitlab-org/gitlab-ce/issues/30120) in GitLab 11.8.

```text
Fabian Schneider's avatar
Fabian Schneider committed
194
195
196
197
198
199
https://example.gitlab.com/<namespace>/<project>/badges/<branch>/coverage.svg?style=flat-square
```

![Badge flat square style](https://gitlab.com/gitlab-org/gitlab-ce/badges/master/coverage.svg?job=coverage&style=flat-square)

## Environment Variables
200

201
[Environment variables](../../../ci/variables/README.html#gitlab-cicd-environment-variables) can be set in an environment to be available to a runner.