Commit 4635b47a authored by Achilleas Pipinellis's avatar Achilleas Pipinellis

Merge branch 'doc/improve-coverage-badge-docs' into 'master'

Document CI pipelines settings

See merge request !5847
parents 084dde9e 6309fbf1
......@@ -5,33 +5,59 @@
%h4.prepend-top-0
= page_title
.col-lg-9
%h5.prepend-top-0
Pipelines
= form_for @project, url: namespace_project_pipelines_settings_path(@project.namespace.becomes(Namespace), @project) do |f|
%fieldset.builds-feature
- unless @repository.gitlab_ci_yml
.form-group
%p Pipelines need to be configured before you can begin using Continuous Integration.
= link_to 'Get started with CI/CD Pipelines', help_page_path('ci/quick_start/README'), class: 'btn btn-info'
%hr
.form-group.append-bottom-default
= f.label :runners_token, "Runner token", class: 'label-light'
= f.text_field :runners_token, class: "form-control", placeholder: 'xEeFCaDAB89'
%p.help-block The secure token used by the Runner to checkout the project
%hr
.form-group
%p Get recent application code using the following command:
%h5.prepend-top-0
Git strategy for pipelines
%p
Choose between <code>clone</code> or <code>fetch</code> to get the recent application code
= link_to icon('question-circle'), help_page_path('user/project/pipelines/settings', anchor: 'git-strategy')
.radio
= f.label :build_allow_git_fetch_false do
= f.radio_button :build_allow_git_fetch, 'false'
%strong git clone
%br
%span.descr Slower but makes sure you have a clean dir before every build
%span.descr
Slower but makes sure the project workspace is pristine as it clones the repository from scratch for every job
.radio
= f.label :build_allow_git_fetch_true do
= f.radio_button :build_allow_git_fetch, 'true'
%strong git fetch
%br
%span.descr Faster
%span.descr
Faster as it re-uses the project workspace (falling back to clone if it doesn't exist)
%hr
.form-group
= f.label :build_timeout_in_minutes, 'Timeout', class: 'label-light'
= f.number_field :build_timeout_in_minutes, class: 'form-control', min: '0'
%p.help-block per build in minutes
%p.help-block
Per job in minutes. If a job passes this threshold, it will be marked as failed.
= link_to icon('question-circle'), help_page_path('user/project/pipelines/settings', anchor: 'timeout')
%hr
.form-group
.checkbox
= f.label :public_builds do
= f.check_box :public_builds
%strong Public pipelines
.help-block
Allow everyone to access pipelines for public and internal projects
= link_to icon('question-circle'), help_page_path('user/project/pipelines/settings', anchor: 'visibility-of-pipelines')
%hr
.form-group
= f.label :build_coverage_regex, "Test coverage parsing", class: 'label-light'
.input-group
......@@ -39,8 +65,9 @@
= f.text_field :build_coverage_regex, class: 'form-control', placeholder: '\(\d+.\d+\%\) covered'
%span.input-group-addon /
%p.help-block
We will use this regular expression to find test coverage output in build trace.
Leave blank if you want to disable this feature
A regular expression that will be used to find the test coverage
output in the build trace. Leave blank to disable
= link_to icon('question-circle'), help_page_path('user/project/pipelines/settings', anchor: 'test-coverage-parsing')
.bs-callout.bs-callout-info
%p Below are examples of regex for existing tools:
%ul
......@@ -57,21 +84,9 @@
gcovr (C/C++) -
%code ^TOTAL.*\s+(\d+\%)$
%li
tap --coverage-report=text-summary (Node.js) -
tap --coverage-report=text-summary (NodeJS) -
%code ^Statements\s*:\s*([^%]+)
.form-group
.checkbox
= f.label :public_builds do
= f.check_box :public_builds
%strong Public builds
.help-block Allow everyone to access builds traces for Public and Internal projects
.form-group.append-bottom-default
= f.label :runners_token, "Runners token", class: 'label-light'
= f.text_field :runners_token, class: "form-control", placeholder: 'xEeFCaDAB89'
%p.help-block The secure token used to checkout project.
= f.submit 'Save changes', class: "btn btn-save"
%hr
......
......@@ -19,4 +19,5 @@
- [Build permissions](../user/permissions.md#build-permissions)
- [API](../api/ci/README.md)
- [CI services (linked docker containers)](services/README.md)
- [CI/CD pipelines settings](../user/project/pipelines/settings.md)
- [**New CI build permissions model**](../user/project/new_ci_build_permissions_model.md) Read about what changed in GitLab 8.12 and how that affects your builds. There's a new way to access your Git submodules and LFS objects in builds.
......@@ -5,9 +5,9 @@ Introduced in GitLab 8.8.
## Pipelines
A pipeline is a group of [builds] that get executed in [stages] \(batches). All
of the builds in a stage are executed in parallel (if there are enough
concurrent [runners]), and if they all succeed, the pipeline moves on to the
A pipeline is a group of [builds][] that get executed in [stages][](batches).
All of the builds in a stage are executed in parallel (if there are enough
concurrent [Runners]), and if they all succeed, the pipeline moves on to the
next stage. If one of the builds fails, the next stage is not (usually)
executed.
......@@ -25,8 +25,8 @@ See full [documentation](yaml/README.md#jobs).
## Seeing pipeline status
You can find the current and historical pipeline runs under **Pipelines** for your
project.
You can find the current and historical pipeline runs under **Pipelines** for
your project.
## Seeing build status
......@@ -36,42 +36,11 @@ cancel the build, retry it, or erase the build trace.
## Badges
There are build status and test coverage report badges available.
Go to pipeline settings to see available badges and code you can use to embed
badges in the `README.md` or your website.
### Build status badge
You can access a build status badge image using following link:
```
http://example.gitlab.com/namespace/project/badges/branch/build.svg
```
### Test coverage report badge
GitLab makes it possible to define the regular expression for coverage report,
that each build log will be matched against. This means that each build in the
pipeline can have the test coverage percentage value defined.
You can access test coverage badge using following link:
```
http://example.gitlab.com/namespace/project/badges/branch/coverage.svg
```
If you would like to get the coverage report from the specific job, you can add
a `job=coverage_job_name` parameter to the URL. For example, it is possible to
use following Markdown code to embed the est coverage report into `README.md`:
```markdown
![coverage](http://gitlab.com/gitlab-org/gitlab-ce/badges/master/coverage.svg?job=coverage)
```
The latest successful pipeline will be used to read the test coverage value.
Build status and test coverage report badges are available. You can find their
respective link in the [Pipelines settings] page.
[builds]: #builds
[jobs]: yaml/README.md#jobs
[stages]: yaml/README.md#stages
[runners]: runners/README.md
[runners]: runners/READM
[pipelines settings]: ../user/project/pipelines/settings.md
# CI/CD pipelines settings
To reach the pipelines settings:
1. Navigate to your project and click the cog icon in the upper right corner.
![Project settings menu](../img/project_settings_list.png)
1. Select **CI/CD Pipelines** from the menu.
The following settings can be configured per project.
## Git strategy
With Git strategy, you can choose the default way your repository is fetched
from GitLab in a job.
There are two options:
- Using `git clone` which is slower since it clones the repository from scratch
for every job, ensuring that the project workspace is always pristine.
- Using `git fetch` which is faster as it re-uses the project workspace (falling
back to clone if it doesn't exist).
The default Git strategy can be overridden by the [GIT_STRATEGY variable][var]
in `.gitlab-ci.yml`.
## Timeout
Timeout defines the maximum amount of time in minutes that a job is able run.
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.
## Test coverage parsing
If you use test coverage in your code, GitLab can capture its output in the
build log using a regular expression. In the pipelines settings, search for the
"Test coverage parsing" section.
![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
can use http://rubular.com to test your regex.
If the pipeline succeeds, the coverage is shown in the merge request widget and
in the builds table.
![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.
## Visibility of pipelines
For public and internal projects, the pipelines page can be accessed by
anyone and those logged in respectively. If you wish to hide it so that only
the members of the project or group have access to it, uncheck the **Public
pipelines** checkbox and save the changes.
## Badges
In the pipelines settings page you can find build status and test coverage
badges for your project. The latest successful pipeline will be used to read
the build status and test coverage values.
Visit the pipelines settings page in your project to see the exact link to
your badges, as well as ways to embed the badge image in your HTML or Markdown
pages.
![Pipelines badges](img/pipelines_settings_badges.png)
### Build status badge
Depending on the status of your build, a badge can have the following values:
- running
- success
- failed
- skipped
- unknown
You can access a build status badge image using the following link:
```
https://example.gitlab.com/<namespace>/<project>/badges/<branch>/build.svg
```
### Test coverage report badge
GitLab makes it possible to define the regular expression for [coverage report],
that each build log will be matched against. This means that each build in the
pipeline can have the test coverage percentage value defined.
The test coverage badge can be accessed using following link:
```
https://example.gitlab.com/<namespace>/<project>/badges/<branch>/coverage.svg
```
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`:
```markdown
![coverage](https://gitlab.com/gitlab-org/gitlab-ce/badges/master/coverage.svg?job=coverage)
```
[var]: ../../../ci/yaml/README.md#git-strategy
[coverage report]: #test-coverage-parsing
Markdown is supported
0%
or
You are about to add 0 people to the discussion. Proceed with caution.
Finish editing this message first!
Please register or to comment