Skip to content

G
gitlab-ce
Commit 22e7bf19 authored by Marcel Amirault's avatar Marcel Amirault
Browse files
Options

Merge branch '30459-move-remaining-pipeline-docs' into 'master' 

Doc: Move the settings and index docs to CI folder

See merge request gitlab-org/gitlab!26859
parents 5adab09a 207d9c98
Hide whitespace changes
Inline Side-by-side
Showing with 929 additions and 919 deletions
app/views/admin/application_settings/_ci_cd.html.haml
View file @ 22e7bf19
......@@ -58,6 +58,6 @@
= f.text_field :default_ci_config_path, class: 'form-control', placeholder: '.gitlab-ci.yml'
%p.form-text.text-muted
= _("The default CI configuration path for new projects.").html_safe
= link_to icon('question-circle'), help_page_path('user/project/pipelines/settings', anchor: 'custom-ci-configuration-path'), target: '_blank'
= link_to icon('question-circle'), help_page_path('ci/pipelines/settings', anchor: 'custom-ci-configuration-path'), target: '_blank'
= f.submit _('Save changes'), class: "btn btn-success"
app/views/projects/settings/ci_cd/_form.html.haml
View file @ 22e7bf19
......@@ -8,7 +8,7 @@
= _("Git strategy for pipelines")
%p
= _("Choose between <code>clone</code> or <code>fetch</code> to get the recent application code").html_safe
= link_to icon('question-circle'), help_page_path('user/project/pipelines/settings', anchor: 'git-strategy'), target: '_blank'
= link_to icon('question-circle'), help_page_path('ci/pipelines/settings', anchor: 'git-strategy'), target: '_blank'
.form-check
= f.radio_button :build_allow_git_fetch, 'false', { class: 'form-check-input' }
= f.label :build_allow_git_fetch_false, class: 'form-check-label' do
......@@ -38,7 +38,7 @@
= f.text_field :build_timeout_human_readable, class: 'form-control'
%p.form-text.text-muted
= _('If any job surpasses this timeout threshold, it will be marked as failed. Human readable time input language is accepted like "1 hour". Values without specification represent seconds.')
= link_to icon('question-circle'), help_page_path('user/project/pipelines/settings', anchor: 'timeout'), target: '_blank'
= link_to icon('question-circle'), help_page_path('ci/pipelines/settings', anchor: 'timeout'), target: '_blank'
- if can?(current_user, :update_max_artifacts_size, @project)
%hr
......@@ -55,7 +55,7 @@
= f.text_field :ci_config_path, class: 'form-control', placeholder: '.gitlab-ci.yml'
%p.form-text.text-muted
= _("The path to the CI configuration file. Defaults to <code>.gitlab-ci.yml</code>").html_safe
= link_to icon('question-circle'), help_page_path('user/project/pipelines/settings', anchor: 'custom-ci-configuration-path'), target: '_blank'
= link_to icon('question-circle'), help_page_path('ci/pipelines/settings', anchor: 'custom-ci-configuration-path'), target: '_blank'
%hr
.form-group
......@@ -65,7 +65,7 @@
%strong= _("Public pipelines")
.form-text.text-muted
= _("Allow public access to pipelines and job details, including output logs and artifacts")
= link_to icon('question-circle'), help_page_path('user/project/pipelines/settings', anchor: 'visibility-of-pipelines'), target: '_blank'
= link_to icon('question-circle'), help_page_path('ci/pipelines/settings', anchor: 'visibility-of-pipelines'), target: '_blank'
.bs-callout.bs-callout-info
%p #{_("If enabled")}:
%ul
......@@ -86,7 +86,7 @@
%strong= _("Auto-cancel redundant, pending pipelines")
.form-text.text-muted
= _("New pipelines will cancel older, pending pipelines on the same branch")
= link_to icon('question-circle'), help_page_path('user/project/pipelines/settings', anchor: 'auto-cancel-pending-pipelines'), target: '_blank'
= link_to icon('question-circle'), help_page_path('ci/pipelines/settings', anchor: 'auto-cancel-pending-pipelines'), target: '_blank'
.form-group
.form-check
......@@ -95,7 +95,7 @@
%strong= _("Skip older, pending deployment jobs")
.form-text.text-muted
= _("When a deployment job is successful, skip older deployment jobs that are still pending")
= link_to icon('question-circle'), help_page_path('user/project/pipelines/settings', anchor: 'skip-older-pending-deployment-jobs'), target: '_blank'
= link_to icon('question-circle'), help_page_path('ci/pipelines/settings', anchor: 'skip-older-pending-deployment-jobs'), target: '_blank'
%hr
.form-group
......@@ -108,7 +108,7 @@
.input-group-text /
%p.form-text.text-muted
= _("A regular expression that will be used to find the test coverage output in the job log. Leave blank to disable")
= link_to icon('question-circle'), help_page_path('user/project/pipelines/settings', anchor: 'test-coverage-parsing'), target: '_blank'
= link_to icon('question-circle'), help_page_path('ci/pipelines/settings', anchor: 'test-coverage-parsing'), target: '_blank'
.bs-callout.bs-callout-info
%p= _("Below are examples of regex for existing tools:")
%ul
......
doc/README.md
View file @ 22e7bf19
......@@ -238,7 +238,7 @@ The following documentation relates to the DevOps **Verify** stage:
| [GitLab CI/CD](ci/README.md) | Explore the features and capabilities of Continuous Integration with GitLab. |
| [JUnit test reports](ci/junit_test_reports.md) | Display JUnit test reports on merge requests. |
| [Multi-project pipelines](ci/multi_project_pipelines.md) **(PREMIUM)** | Visualize entire pipelines that span multiple projects, including all cross-project inter-dependencies. |
| [Pipeline Graphs](ci/pipelines.md#visualizing-pipelines) | Visualize builds. |
| [Pipeline Graphs](ci/pipelines/index.md#visualizing-pipelines) | Visualize builds. |
| [Review Apps](ci/review_apps/index.md) | Preview changes to your application right from a merge request. |
<div align="right">
......
doc/administration/compliance.md
View file @ 22e7bf19
......@@ -17,4 +17,4 @@ GitLab’s [security features](../security/README.md) may also help you meet rel
|**[Audit logs](audit_events.md)**<br>To maintain the integrity of your code, GitLab Enterprise Edition Premium gives admins the ability to view any modifications made within the GitLab server in an advanced audit log system, so you can control, analyze, and track every change.|Premium+||
|**[Auditor users](auditor_users.md)**<br>Auditor users are users who are given read-only access to all projects, groups, and other resources on the GitLab instance.|Premium+||
|**[Credentials inventory](../user/admin_area/credentials_inventory.md)**<br>With a credentials inventory, GitLab administrators can keep track of the credentials used by all of the users in their GitLab instance. |Ultimate||
|**Separation of Duties using [Protected branches](../user/project/protected_branches.md#protected-branches-approval-by-code-owners-premium) and [custom CI Configuration Paths](../user/project/pipelines/settings.md#custom-ci-configuration-path)**<br> GitLab Silver and Premium users can leverage GitLab's cross-project YAML configuration's to define deployers of code and developers of code. View the [Separation of Duties Deploy Project](https://gitlab.com/guided-explorations/separation-of-duties-deploy/blob/master/README.md) and [Separation of Duties Project](https://gitlab.com/guided-explorations/separation-of-duties/blob/master/README.md) to see how to use this set up to define these roles.|Premium+||
|**Separation of Duties using [Protected branches](../user/project/protected_branches.md#protected-branches-approval-by-code-owners-premium) and [custom CI Configuration Paths](../ci/pipelines/settings.md#custom-ci-configuration-path)**<br> GitLab Silver and Premium users can leverage GitLab's cross-project YAML configuration's to define deployers of code and developers of code. View the [Separation of Duties Deploy Project](https://gitlab.com/guided-explorations/separation-of-duties-deploy/blob/master/README.md) and [Separation of Duties Project](https://gitlab.com/guided-explorations/separation-of-duties/blob/master/README.md) to see how to use this set up to define these roles.|Premium+||
doc/api/projects.md
View file @ 22e7bf19
......@@ -1174,7 +1174,7 @@ PUT /projects/:id
| `auto_cancel_pending_pipelines` | string | no | Auto-cancel pending pipelines (Note: this is not a boolean, but enabled/disabled |
| `build_coverage_regex` | string | no | Test coverage parsing |
| `ci_config_path` | string | no | The path to CI config file |
| `ci_default_git_depth` | integer | no | Default number of revisions for [shallow cloning](../user/project/pipelines/settings.md#git-shallow-clone) |
| `ci_default_git_depth` | integer | no | Default number of revisions for [shallow cloning](../ci/pipelines/settings.md#git-shallow-clone) |
| `auto_devops_enabled` | boolean | no | Enable Auto DevOps for this project |
| `auto_devops_deploy_strategy` | string | no | Auto Deploy strategy (`continuous`, `manual` or `timed_incremental`) |
| `repository_storage` | string | no | Which storage shard the repository is on. Available only to admins |
......
doc/ci/README.md
View file @ 22e7bf19
......@@ -80,13 +80,13 @@ GitLab CI/CD supports numerous configuration options:
| Configuration | Description |
|:--------------|:-------------|
| [Pipelines](pipelines.md) | Structure your CI/CD process through pipelines. |
| [Pipelines](pipelines/index.md) | Structure your CI/CD process through pipelines. |
| [Environment variables](variables/README.md) | Reuse values based on a variable/value key pair. |
| [Environments](environments.md) | Deploy your application to different environments (e.g., staging, production). |
| [Job artifacts](pipelines/job_artifacts.md) | Output, use, and reuse job artifacts. |
| [Cache dependencies](caching/index.md) | Cache your dependencies for a faster execution. |
| [Schedule pipelines](pipelines/schedules.md) | Schedule pipelines to run as often as you need. |
| [Custom path for `.gitlab-ci.yml`](../user/project/pipelines/settings.md#custom-ci-configuration-path) | Define a custom path for the CI/CD configuration file. |
| [Custom path for `.gitlab-ci.yml`](pipelines/settings.md#custom-ci-configuration-path) | Define a custom path for the CI/CD configuration file. |
| [Git submodules for CI/CD](git_submodules.md) | Configure jobs for using Git submodules.|
| [SSH keys for CI/CD](ssh_keys/README.md) | Using SSH keys in your CI pipelines. |
| [Pipelines triggers](triggers/README.md) | Trigger pipelines through the API. |
......@@ -149,7 +149,7 @@ As a GitLab administrator, you can change the default behavior
of GitLab CI/CD for:
- An [entire GitLab instance](../user/admin_area/settings/continuous_integration.md).
- Specific projects, using [pipelines settings](../user/project/pipelines/settings.md).
- Specific projects, using [pipelines settings](pipelines/settings.md).
See also:
......
doc/ci/environments.md
View file @ 22e7bf19
......@@ -47,7 +47,7 @@ can even access a [web terminal](#web-terminals) for your environment from withi
Configuring environments involves:
1. Understanding how [pipelines](pipelines.md) work.
1. Understanding how [pipelines](pipelines/index.md) work.
1. Defining environments in your project's [`.gitlab-ci.yml`](yaml/README.md) file.
1. Creating a job configured to deploy your application. For example, a deploy job configured with [`environment`](yaml/README.md#environment) to deploy your application to a [Kubernetes cluster](../user/project/clusters/index.md).
......
doc/ci/examples/test-scala-application.md
View file @ 22e7bf19
......@@ -60,7 +60,7 @@ You can use other versions of Scala and SBT by defining them in
Add the `Coverage was \[\d+.\d+\%\]` regular expression in the
**Settings ➔ Pipelines ➔ Coverage report** project setting to
retrieve the [test coverage](../../user/project/pipelines/settings.md#test-coverage-report-badge)
retrieve the [test coverage](../pipelines/settings.md#test-coverage-report-badge)
rate from the build trace and have it displayed with your jobs.
**Pipelines** must be enabled for this option to appear.
......
doc/ci/jenkins/index.md
View file @ 22e7bf19
......@@ -48,7 +48,7 @@ There are some high level differences between the products worth mentioning:
- on push
- on [schedule](../pipelines/schedules.md)
- from the [GitLab UI](../pipelines.md#manually-executing-pipelines)
- from the [GitLab UI](../pipelines/index.md#manually-executing-pipelines)
- by [API call](../triggers/README.md)
- by [webhook](../triggers/README.md#triggering-a-pipeline-from-a-webhook)
- by [ChatOps](../chatops/README.md)
......
doc/ci/junit_test_reports.md
View file @ 22e7bf19
......@@ -9,7 +9,7 @@ Requires GitLab Runner 11.2 and above.
## Overview
It is very common that a [CI/CD pipeline](pipelines.md) contains a
It is very common that a [CI/CD pipeline](pipelines/index.md) contains a
test job that will verify your code.
If the tests fail, the pipeline fails and users get notified. The person that
works on the merge request will have to check the job logs and see where the
......
doc/ci/merge_request_pipelines/pipelines_for_merged_results/index.md
View file @ 22e7bf19
......@@ -115,7 +115,7 @@ unexpected timing. For example, when a source or target branch is advanced.
In this case, the pipeline fails because of `fatal: reference is not a tree:` error,
which indicates that the checkout-SHA is not found in the merge ref.
This behavior was improved at GitLab 12.4 by introducing [Persistent pipeline refs](../../pipelines.md#persistent-pipeline-refs).
This behavior was improved at GitLab 12.4 by introducing [Persistent pipeline refs](../../pipelines/index.md#persistent-pipeline-refs).
You should be able to create pipelines at any timings without concerning the error.
## Using Merge Trains **(PREMIUM)**
......
doc/ci/multi_project_pipelines.md
View file @ 22e7bf19
......@@ -40,7 +40,7 @@ With Multi-Project Pipelines you can visualize the entire pipeline, including al
> [Introduced](https://gitlab.com/gitlab-org/gitlab/issues/2121) in [GitLab Premium 9.3](https://about.gitlab.com/releases/2017/06/22/gitlab-9-3-released/#multi-project-pipeline-graphs).
When you configure GitLab CI for your project, you can visualize the stages of your
[jobs](pipelines.md#configuring-pipelines) on a [pipeline graph](pipelines.md#visualizing-pipelines).
[jobs](pipelines/index.md#configuring-pipelines) on a [pipeline graph](pipelines/index.md#visualizing-pipelines).
![Multi-project pipeline graph](img/multi_project_pipeline_graph.png)
......
doc/ci/pipelines.md
View file @ 22e7bf19
---
type: reference
redirect_to: 'pipelines/index.md'
---
# Creating and using CI/CD pipelines
> Introduced in GitLab 8.8.
NOTE: **Tip:**
Watch our
["Mastering continuous software development"](https://about.gitlab.com/webcast/mastering-ci-cd/)
webcast to see a comprehensive demo of GitLab CI/CD pipeline.
## Introduction
Pipelines are the top-level component of continuous integration, delivery, and deployment.
Pipelines comprise:
- Jobs that define what to run. For example, code compilation or test runs.
- Stages that define when and how to run. For example, that tests run only after code compilation.
Multiple jobs in the same stage are executed by [Runners](runners/README.md) in parallel, if there are enough concurrent [Runners](runners/README.md).
If all the jobs in a stage:
- Succeed, the pipeline moves on to the next stage.
- Fail, the next stage is not (usually) executed and the pipeline ends early.
NOTE: **Note:**
If you have a [mirrored repository that GitLab pulls from](../user/project/repository/repository_mirroring.md#pulling-from-a-remote-repository-starter),
you may need to enable pipeline triggering in your project's
**Settings > Repository > Pull from a remote repository > Trigger pipelines for mirror updates**.
### Simple pipeline example
As an example, imagine a pipeline consisting of four stages, executed in the following order:
- `build`, with a job called `compile`.
- `test`, with two jobs called `test` and `test2`.
- `staging`, with a job called `deploy-to-stage`.
- `production`, with a job called `deploy-to-prod`.
## Visualizing pipelines
> [Introduced](https://gitlab.com/gitlab-org/gitlab-foss/-/merge_requests/5742) in GitLab 8.11.
Pipelines can be complex structures with many sequential and parallel jobs.
To make it easier to understand the flow of a pipeline, GitLab has pipeline graphs for viewing pipelines
and their statuses.
Pipeline graphs can be displayed in two different ways, depending on the page you
access the graph from.
NOTE: **Note:**
GitLab capitalizes the stages' names when shown in the pipeline graphs (below).
### Regular pipeline graphs
Regular pipeline graphs show the names of the jobs of each stage. Regular pipeline graphs can
be found when you are on a [single pipeline page](#accessing-pipelines). For example:
![Pipelines example](img/pipelines.png)
### Pipeline mini graphs
Pipeline mini graphs take less space and can tell you at a
quick glance if all jobs passed or something failed. The pipeline mini graph can
be found when you navigate to:
- The pipelines index page.
- A single commit page.
- A merge request page.
Pipeline mini graphs allow you to see all related jobs for a single commit and the net result
of each stage of your pipeline. This allows you to quickly see what failed and
fix it.
Stages in pipeline mini graphs are collapsible. Hover your mouse over them and click to expand their jobs.
| Mini graph | Mini graph expanded |
|:-------------------------------------------------------------|:---------------------------------------------------------------|
| ![Pipelines mini graph](img/pipelines_mini_graph_simple.png) | ![Pipelines mini graph extended](img/pipelines_mini_graph.png) |
### Job ordering in pipeline graphs
Job ordering depends on the type of pipeline graph. For [regular pipeline graphs](#regular-pipeline-graphs), jobs are sorted by name.
For [pipeline mini graphs](#pipeline-mini-graphs) ([introduced](https://gitlab.com/gitlab-org/gitlab-foss/-/merge_requests/9760)
in GitLab 9.0), jobs are sorted by severity and then by name.
The order of severity is:
- failed
- warning
- pending
- running
- manual
- scheduled
- canceled
- success
- skipped
- created
For example:
![Pipeline mini graph sorting](img/pipelines_mini_graph_sorting.png)
### Expanding and collapsing job log sections
> [Introduced](https://gitlab.com/gitlab-org/gitlab-foss/issues/14664) in GitLab
> 12.0.
Job logs are divided into sections that can be collapsed or expanded. Each section will display
the duration.
In the following example:
- Two sections are collapsed and can be expanded.
- Three sections are expanded and can be collapsed.
![Collapsible sections](img/collapsible_log_v12_6.png)
#### Custom collapsible sections
You can create collapsible sections in job logs by manually outputting special codes
that GitLab will use to determine what sections to collapse:
- Section start marker: `section_start:UNIX_TIMESTAMP:SECTION_NAME\r\e[0K` + `TEXT_OF_SECTION_HEADER`
- Section end marker: `section_end:UNIX_TIMESTAMP:SECTION_NAME\r\e[0K`
You must add these codes to the script section of the CI configuration. For example,
using `echo`:
```yaml
job1:
script:
- echo -e "section_start:`date +%s`:my_first_section\r\e[0KHeader of the 1st collapsible section"
- echo 'this line should be hidden when collapsed'
- echo -e "section_end:`date +%s`:my_first_section\r\e[0K"
```
In the example above:
- `date +%s`: The Unix timestamp (for example `1560896352`).
- `my_first_section`: The name given to the section.
- `\r\e[0K`: Prevents the section markers from displaying in the rendered (colored)
job log, but they are displayed in the raw job log. To see them, in the top right
of the job log, click **{doc-text}** (**Show complete raw**).
- `\r`: carriage return.
- `\e[0K`: clear line ANSI escape code.
Sample raw job log:
```plaintext
section_start:1560896352:my_first_section\r\e[0KHeader of the 1st collapsible section
this line should be hidden when collapsed
section_end:1560896353:my_first_section\r\e[0K
```
### Pipeline success and duration charts
> - Introduced in GitLab 3.1.1 as Commit Stats, and later renamed to Pipeline Charts.
> - [Renamed](https://gitlab.com/gitlab-org/gitlab/issues/38318) to CI / CD Analytics in GitLab 12.8.
GitLab tracks the history of your pipeline successes and failures, as well as how long each pipeline ran. To view this information, go to **Analytics > CI / CD Analytics**.
View successful pipelines:
![Successful pipelines](img/pipelines_success_chart.png)
View pipeline duration history:
![Pipeline duration](img/pipelines_duration_chart.png)
## Pipeline quotas
Each user has a personal pipeline quota that tracks the usage of shared runners in all personal projects.
Each group has a [usage quota](../subscriptions/index.md#ci-pipeline-minutes) that tracks the usage of shared runners for all projects created within the group.
When a pipeline is triggered, regardless of who triggered it, the pipeline quota for the project owner's [namespace](../user/group/index.md#namespaces) is used. In this case, the namespace can be the user or group that owns the project.
### How pipeline duration is calculated
Total running time for a given pipeline excludes retries and pending
(queued) time.
Each job is represented as a `Period`, which consists of:
- `Period#first` (when the job started).
- `Period#last` (when the job finished).
A simple example is:
- A (1, 3)
- B (2, 4)
- C (6, 7)
In the example:
- A begins at 1 and ends at 3.
- B begins at 2 and ends at 4.
- C begins at 6 and ends at 7.
Visually, it can be viewed as:
```text
0 1 2 3 4 5 6 7
AAAAAAA
BBBBBBB
CCCC
```
The union of A, B, and C is (1, 4) and (6, 7). Therefore, the total running time is:
```text
(4 - 1) + (7 - 6) => 4
```
## Configuring pipelines
Pipelines, and their component jobs and stages, are defined in the [`.gitlab-ci.yml`](yaml/README.md) file for each project.
In particular:
- Jobs are the [basic configuration](yaml/README.md#introduction) component.
- Stages are defined using the [`stages`](yaml/README.md#stages) keyword.
For all available configuration options, see the [GitLab CI/CD Pipeline Configuration Reference](yaml/README.md).
### Settings and schedules
In addition to configuring jobs through `.gitlab-ci.yml`, additional configuration options are available
through the GitLab UI:
- Pipeline settings for each project. For more information, see [Pipeline settings](../user/project/pipelines/settings.md).
- Schedules for pipelines. For more information, see [Pipeline schedules](../user/project/pipelines/schedules.md).
### Grouping jobs
> [Introduced](https://gitlab.com/gitlab-org/gitlab-foss/-/merge_requests/6242) in GitLab 8.12.
If you have many similar jobs, your [pipeline graph](#visualizing-pipelines) becomes long and hard
to read.
For that reason, similar jobs can automatically be grouped together.
If the job names are formatted in certain ways, they will be collapsed into
a single group in regular pipeline graphs (not the mini graphs).
You'll know when a pipeline has grouped jobs if you don't see the retry or
cancel button inside them. Hovering over them will show the number of grouped
jobs. Click to expand them.
![Grouped pipelines](img/pipelines_grouped.png)
#### Configuring grouping
In the pipeline [configuration file](yaml/README.md), job names must include two numbers separated with one of
the following (you can even use them interchangeably):
- A space.
- A slash (`/`).
- A colon (`:`).
NOTE: **Note:**
More specifically, it uses [this](https://gitlab.com/gitlab-org/gitlab/blob/2f3dc314f42dbd79813e6251792853bc231e69dd/app/models/commit_status.rb#L99) regular expression: `\d+[\s:\/\\]+\d+\s*`.
#### How grouping works
The jobs will be ordered by comparing those two numbers from left to right. You
usually want the first to be the index and the second the total.
For example, the following jobs will be grouped under a job named `test`:
- `test 0 3`
- `test 1 3`
- `test 2 3`
The following jobs will be grouped under a job named `test ruby`:
- `test 1:2 ruby`
- `test 2:2 ruby`
The following jobs will be grouped under a job named `test ruby` as well:
- `1/3 test ruby`
- `2/3 test ruby`
- `3/3 test ruby`
### Pipelines for merge requests
GitLab supports configuring pipelines that run only for merge requests. For more information, see
[Pipelines for merge requests](merge_request_pipelines/index.md).
### Badges
Pipeline status and test coverage report badges are available and configurable for each project.
For information on adding pipeline badges to projects, see [Pipeline badges](../user/project/pipelines/settings.md#pipeline-badges).
## Multi-project pipelines
Pipelines for different projects can be combined together into [Multi-project pipelines](multi_project_pipelines.md).
[Multi-project pipeline graphs](multi_project_pipelines.md#multi-project-pipeline-visualization-premium) help
you visualize the entire pipeline, including all cross-project inter-dependencies. **(PREMIUM)**
## Parent-child pipelines
Complex pipelines can be broken down into one parent pipeline that can trigger
multiple child sub-pipelines, which all run in the same project and with the same SHA.
For more information, see [Parent-Child pipelines](parent_child_pipelines.md).
## Working with pipelines
In general, pipelines are executed automatically and require no intervention once created.
However, there are instances where you'll need to interact with pipelines. These are documented below.
### Manually executing pipelines
Pipelines can be manually executed, with predefined or manually-specified [variables](variables/README.md).
You might do this if the results of a pipeline (for example, a code build) is required outside the normal
operation of the pipeline.
To execute a pipeline manually:
1. Navigate to your project's **CI/CD > Pipelines**.
1. Click on the **Run Pipeline** button.
1. On the **Run Pipeline** page:
1. Select the branch to run the pipeline for in the **Create for** field.
1. Enter any [environment variables](variables/README.md) required for the pipeline run.
1. Click the **Create pipeline** button.
The pipeline will execute the jobs as configured.
#### Using a query string
> [Introduced](https://gitlab.com/gitlab-org/gitlab/issues/24146) in GitLab 12.5.
Variables on the **Run Pipeline** page can be pre-populated by passing variable keys and values
in a query string appended to the `pipelines/new` URL. The format is:
```plaintext
.../pipelines/new?ref=<branch>&var[<variable_key>]=<value>&file_var[<file_key>]=<value>
```
The following parameters are supported:
- `ref`: specify the branch to populate the **Run for** field with.
- `var`: specify a `Variable` variable.
- `file_var`: specify a `File` variable.
For each `var` or `file_var`, a key and value are required.
For example, the query string
`.../pipelines/new?ref=my_branch&var[foo]=bar&file_var[file_foo]=file_bar` will pre-populate the
**Run Pipeline** page as follows:
- **Run for** field: `my_branch`.
- **Variables** section:
- Variable:
- Key: `foo`
- Value: `bar`
- File:
- Key: `file_foo`
- Value: `file_bar`
### Accessing pipelines
You can find the current and historical pipeline runs under your project's
**CI/CD > Pipelines** page. You can also access pipelines for a merge request by navigating
to its **Pipelines** tab.
![Pipelines index page](img/pipelines_index.png)
Clicking on a pipeline will bring you to the **Pipeline Details** page and show
the jobs that were run for that pipeline. From here you can cancel a running pipeline,
retry jobs on a failed pipeline, or [delete a pipeline](#deleting-a-single-pipeline).
### Accessing individual jobs
When you access a pipeline, you can see the related jobs for that pipeline.
Clicking on an individual job will show you its job log, and allow you to:
- Cancel the job.
- Retry the job.
- Erase the job log.
### Seeing the failure reason for jobs
> [Introduced](https://gitlab.com/gitlab-org/gitlab-foss/-/merge_requests/17782) in GitLab 10.7.
When a pipeline fails or is allowed to fail, there are several places where you
can quickly check the reason it failed:
- In the pipeline graph, on the pipeline detail view.
- In the pipeline widgets, in the merge requests and commit pages.
- In the job views, in the global and detailed views of a job.
In each place, if you hover over the failed job you can see the reason it failed.
![Pipeline detail](img/job_failure_reason.png)
From [GitLab 10.8](https://gitlab.com/gitlab-org/gitlab-foss/-/merge_requests/17814),
you can also see the reason it failed on the Job detail page.
### Manual actions from pipeline graphs
> [Introduced](https://gitlab.com/gitlab-org/gitlab-foss/-/merge_requests/7931) in GitLab 8.15.
Manual actions, configured using the [`when:manual`](yaml/README.md#whenmanual) parameter,
allow you to require manual interaction before moving forward in the pipeline.
You can do this straight from the pipeline graph. Just click on the play button
to execute that particular job.
For example, your pipeline start automatically, but require manual action to
[deploy to production](environments.md#configuring-manual-deployments). In the example below, the `production`
stage has a job with a manual action.
![Pipelines example](img/pipelines.png)
### Specifying variables when running manual jobs
> [Introduced](https://gitlab.com/gitlab-org/gitlab-foss/-/merge_requests/30485) in GitLab 12.2.
When running manual jobs you can supply additional job specific variables.
You can do this from the job page of the manual job you want to run with
additional variables.
This is useful when you want to alter the execution of a job by using
environment variables.
![Manual job variables](img/manual_job_variables.png)
### Delay a job in a pipeline graph
> [Introduced](https://gitlab.com/gitlab-org/gitlab-foss/-/merge_requests/21767) in GitLab 11.4.
When you do not want to run a job immediately, you can use the [`when:delayed`](yaml/README.md#whendelayed) parameter to
delay a job's execution for a certain period.
This is especially useful for timed incremental rollout where new code is rolled out gradually.
For example, if you start rolling out new code and:
- Users do not experience trouble, GitLab can automatically complete the deployment from 0% to 100%.
- Users experience trouble with the new code, you can stop the timed incremental rollout by canceling the pipeline
and [rolling](environments.md#retrying-and-rolling-back) back to the last stable version.
![Pipelines example](img/pipeline_incremental_rollout.png)
### Using the API
GitLab provides API endpoints to:
- Perform basic functions. For more information, see [Pipelines API](../api/pipelines.md).
- Maintain pipeline schedules. For more information, see [Pipeline schedules API](../api/pipeline_schedules.md).
- Trigger pipeline runs. For more information, see:
- [Triggering pipelines through the API](triggers/README.md).
- [Pipeline triggers API](../api/pipeline_triggers.md).
### Start multiple manual actions in a stage
> [Introduced](https://gitlab.com/gitlab-org/gitlab-foss/-/merge_requests/27188) in GitLab 11.11.
Multiple manual actions in a single stage can be started at the same time using the "Play all manual" button.
Once the user clicks this button, each individual manual action will be triggered and refreshed
to an updated status.
This functionality is only available:
- For users with at least Developer access.
- If the the stage contains [manual actions](#manual-actions-from-pipeline-graphs).
### Deleting a single pipeline
> [Introduced](https://gitlab.com/gitlab-org/gitlab/issues/24851) in GitLab 12.7.
Users with [owner permissions](../user/permissions.md) in a project can delete a pipeline
by clicking on the pipeline in the **CI/CD > Pipelines** to get to the **Pipeline Details**
page, then using the **Delete** button.
![Pipeline Delete Button](img/pipeline-delete.png)
CAUTION: **Warning:**
Deleting a pipeline will expire all pipeline caches, and delete all related objects,
such as builds, logs, artifacts, and triggers. **This action cannot be undone.**
## Most Recent Pipeline
> [Introduced](https://gitlab.com/gitlab-org/gitlab-foss/issues/50499) in GitLab 12.3.
There's a link to the latest pipeline for the last commit of a given branch at `/project/pipelines/[branch]/latest`. Also, `/project/pipelines/latest` will redirect you to the latest pipeline for the last commit on the project's default branch.
## Security on protected branches
A strict security model is enforced when pipelines are executed on
[protected branches](../user/project/protected_branches.md).
The following actions are allowed on protected branches only if the user is
[allowed to merge or push](../user/project/protected_branches.md#using-the-allowed-to-merge-and-allowed-to-push-settings)
on that specific branch:
- Run manual pipelines (using the [Web UI](#manually-executing-pipelines) or pipelines API).
- Run scheduled pipelines.
- Run pipelines using triggers.
- Trigger manual actions on existing pipelines.
- Retry or cancel existing jobs (using the Web UI or pipelines API).
**Variables** marked as **protected** are accessible only to jobs that
run on protected branches, preventing untrusted users getting unintended access to
sensitive information like deployment credentials and tokens.
**Runners** marked as **protected** can run jobs only on protected
branches, avoiding untrusted code to be executed on the protected runner and
preserving deployment keys and other credentials from being unintentionally
accessed. In order to ensure that jobs intended to be executed on protected
runners will not use regular runners, they must be tagged accordingly.
## Persistent pipeline refs
> [Introduced](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/17043) in GitLab 12.4.
Previously, you'd have encountered unexpected pipeline failures when you force-pushed
a branch to its remote repository. To illustrate the problem, suppose you've had the current workflow:
1. A user creates a feature branch named `example` and pushes it to a remote repository.
1. A new pipeline starts running on the `example` branch.
1. A user rebases the `example` branch on the latest `master` branch and force-pushes it to its remote repository.
1. A new pipeline starts running on the `example` branch again, however,
the previous pipeline (2) fails because of `fatal: reference is not a tree:` error.
This is because the previous pipeline cannot find a checkout-SHA (which associated with the pipeline record)
from the `example` branch that the commit history has already been overwritten by the force-push.
Similarly, [Pipelines for merged results](merge_request_pipelines/pipelines_for_merged_results/index.md)
might have failed intermittently due to [the same reason](merge_request_pipelines/pipelines_for_merged_results/index.md#intermittently-pipelines-fail-by-fatal-reference-is-not-a-tree-error).
As of GitLab 12.4, we've improved this behavior by persisting pipeline refs exclusively.
To illustrate its life cycle:
1. A pipeline is created on a feature branch named `example`.
1. A persistent pipeline ref is created at `refs/pipelines/<pipeline-id>`,
which retains the checkout-SHA of the associated pipeline record.
This persistent ref stays intact during the pipeline execution,
even if the commit history of the `example` branch has been overwritten by force-push.
1. GitLab Runner fetches the persistent pipeline ref and gets source code from the checkout-SHA.
1. When the pipeline finished, its persistent ref is cleaned up in a background process.
NOTE: **NOTE**: At this moment, this feature is on by default and can be manually disabled
by disabling `depend_on_persistent_pipeline_ref` feature flag. If you're interested in
manually disabling this behavior, please ask the administrator
to execute the following commands in rails console.
```shell
> sudo gitlab-rails console # Login to Rails console of GitLab instance.
> project = Project.find_by_full_path('namespace/project-name') # Get the project instance.
> Feature.disable(:depend_on_persistent_pipeline_ref, project) # Disable the feature flag for specific project
> Feature.disable(:depend_on_persistent_pipeline_ref) # Disable the feature flag system-wide
```
This document was moved to [another location](pipelines/index.md).
doc/ci/pipelines/index.md 0 → 100644
View file @ 22e7bf19
---
type: reference
---
# Creating and using CI/CD pipelines
> Introduced in GitLab 8.8.
NOTE: **Tip:**
Watch our
["Mastering continuous software development"](https://about.gitlab.com/webcast/mastering-ci-cd/)
webcast to see a comprehensive demo of GitLab CI/CD pipeline.
## Introduction
Pipelines are the top-level component of continuous integration, delivery, and deployment.
Pipelines comprise:
- Jobs that define what to run. For example, code compilation or test runs.
- Stages that define when and how to run. For example, that tests run only after code compilation.
Multiple jobs in the same stage are executed by [Runners](../runners/README.md) in parallel, if there are enough concurrent [Runners](../runners/README.md).
If all the jobs in a stage:
- Succeed, the pipeline moves on to the next stage.
- Fail, the next stage is not (usually) executed and the pipeline ends early.
NOTE: **Note:**
If you have a [mirrored repository that GitLab pulls from](../../user/project/repository/repository_mirroring.md#pulling-from-a-remote-repository-starter),
you may need to enable pipeline triggering in your project's
**Settings > Repository > Pull from a remote repository > Trigger pipelines for mirror updates**.
### Simple pipeline example
As an example, imagine a pipeline consisting of four stages, executed in the following order:
- `build`, with a job called `compile`.
- `test`, with two jobs called `test` and `test2`.
- `staging`, with a job called `deploy-to-stage`.
- `production`, with a job called `deploy-to-prod`.
## Visualizing pipelines
> [Introduced](https://gitlab.com/gitlab-org/gitlab-foss/-/merge_requests/5742) in GitLab 8.11.
Pipelines can be complex structures with many sequential and parallel jobs.
To make it easier to understand the flow of a pipeline, GitLab has pipeline graphs for viewing pipelines
and their statuses.
Pipeline graphs can be displayed in two different ways, depending on the page you
access the graph from.
NOTE: **Note:**
GitLab capitalizes the stages' names when shown in the pipeline graphs (below).
### Regular pipeline graphs
Regular pipeline graphs show the names of the jobs of each stage. Regular pipeline graphs can
be found when you are on a [single pipeline page](#accessing-pipelines). For example:
![Pipelines example](img/pipelines.png)
### Pipeline mini graphs
Pipeline mini graphs take less space and can tell you at a
quick glance if all jobs passed or something failed. The pipeline mini graph can
be found when you navigate to:
- The pipelines index page.
- A single commit page.
- A merge request page.
Pipeline mini graphs allow you to see all related jobs for a single commit and the net result
of each stage of your pipeline. This allows you to quickly see what failed and
fix it.
Stages in pipeline mini graphs are collapsible. Hover your mouse over them and click to expand their jobs.
| Mini graph | Mini graph expanded |
|:-------------------------------------------------------------|:---------------------------------------------------------------|
| ![Pipelines mini graph](img/pipelines_mini_graph_simple.png) | ![Pipelines mini graph extended](img/pipelines_mini_graph.png) |
### Job ordering in pipeline graphs
Job ordering depends on the type of pipeline graph. For [regular pipeline graphs](#regular-pipeline-graphs), jobs are sorted by name.
For [pipeline mini graphs](#pipeline-mini-graphs) ([introduced](https://gitlab.com/gitlab-org/gitlab-foss/-/merge_requests/9760)
in GitLab 9.0), jobs are sorted by severity and then by name.
The order of severity is:
- failed
- warning
- pending
- running
- manual
- scheduled
- canceled
- success
- skipped
- created
For example:
![Pipeline mini graph sorting](img/pipelines_mini_graph_sorting.png)
### Expanding and collapsing job log sections
> [Introduced](https://gitlab.com/gitlab-org/gitlab-foss/issues/14664) in GitLab
> 12.0.
Job logs are divided into sections that can be collapsed or expanded. Each section will display
the duration.
In the following example:
- Two sections are collapsed and can be expanded.
- Three sections are expanded and can be collapsed.
![Collapsible sections](img/collapsible_log_v12_6.png)
#### Custom collapsible sections
You can create collapsible sections in job logs by manually outputting special codes
that GitLab will use to determine what sections to collapse:
- Section start marker: `section_start:UNIX_TIMESTAMP:SECTION_NAME\r\e[0K` + `TEXT_OF_SECTION_HEADER`
- Section end marker: `section_end:UNIX_TIMESTAMP:SECTION_NAME\r\e[0K`
You must add these codes to the script section of the CI configuration. For example,
using `echo`:
```yaml
job1:
script:
- echo -e "section_start:`date +%s`:my_first_section\r\e[0KHeader of the 1st collapsible section"
- echo 'this line should be hidden when collapsed'
- echo -e "section_end:`date +%s`:my_first_section\r\e[0K"
```
In the example above:
- `date +%s`: The Unix timestamp (for example `1560896352`).
- `my_first_section`: The name given to the section.
- `\r\e[0K`: Prevents the section markers from displaying in the rendered (colored)
job log, but they are displayed in the raw job log. To see them, in the top right
of the job log, click **{doc-text}** (**Show complete raw**).
- `\r`: carriage return.
- `\e[0K`: clear line ANSI escape code.
Sample raw job log:
```plaintext
section_start:1560896352:my_first_section\r\e[0KHeader of the 1st collapsible section
this line should be hidden when collapsed
section_end:1560896353:my_first_section\r\e[0K
```
### Pipeline success and duration charts
> - Introduced in GitLab 3.1.1 as Commit Stats, and later renamed to Pipeline Charts.
> - [Renamed](https://gitlab.com/gitlab-org/gitlab/issues/38318) to CI / CD Analytics in GitLab 12.8.
GitLab tracks the history of your pipeline successes and failures, as well as how long each pipeline ran. To view this information, go to **Analytics > CI / CD Analytics**.
View successful pipelines:
![Successful pipelines](img/pipelines_success_chart.png)
View pipeline duration history:
![Pipeline duration](img/pipelines_duration_chart.png)
## Pipeline quotas
Each user has a personal pipeline quota that tracks the usage of shared runners in all personal projects.
Each group has a [usage quota](../../subscriptions/index.md#ci-pipeline-minutes) that tracks the usage of shared runners for all projects created within the group.
When a pipeline is triggered, regardless of who triggered it, the pipeline quota for the project owner's [namespace](../../user/group/index.md#namespaces) is used. In this case, the namespace can be the user or group that owns the project.
### How pipeline duration is calculated
Total running time for a given pipeline excludes retries and pending
(queued) time.
Each job is represented as a `Period`, which consists of:
- `Period#first` (when the job started).
- `Period#last` (when the job finished).
A simple example is:
- A (1, 3)
- B (2, 4)
- C (6, 7)
In the example:
- A begins at 1 and ends at 3.
- B begins at 2 and ends at 4.
- C begins at 6 and ends at 7.
Visually, it can be viewed as:
```text
0 1 2 3 4 5 6 7
AAAAAAA
BBBBBBB
CCCC
```
The union of A, B, and C is (1, 4) and (6, 7). Therefore, the total running time is:
```text
(4 - 1) + (7 - 6) => 4
```
## Configuring pipelines
Pipelines, and their component jobs and stages, are defined in the [`.gitlab-ci.yml`](../yaml/README.md) file for each project.
In particular:
- Jobs are the [basic configuration](../yaml/README.md#introduction) component.
- Stages are defined using the [`stages`](../yaml/README.md#stages) keyword.
For all available configuration options, see the [GitLab CI/CD Pipeline Configuration Reference](../yaml/README.md).
### Settings and schedules
In addition to configuring jobs through `.gitlab-ci.yml`, additional configuration options are available
through the GitLab UI:
- Pipeline settings for each project. For more information, see [Pipeline settings](settings.md).
- Schedules for pipelines. For more information, see [Pipeline schedules](schedules.md).
### Grouping jobs
> [Introduced](https://gitlab.com/gitlab-org/gitlab-foss/-/merge_requests/6242) in GitLab 8.12.
If you have many similar jobs, your [pipeline graph](#visualizing-pipelines) becomes long and hard
to read.
For that reason, similar jobs can automatically be grouped together.
If the job names are formatted in certain ways, they will be collapsed into
a single group in regular pipeline graphs (not the mini graphs).
You'll know when a pipeline has grouped jobs if you don't see the retry or
cancel button inside them. Hovering over them will show the number of grouped
jobs. Click to expand them.
![Grouped pipelines](img/pipelines_grouped.png)
#### Configuring grouping
In the pipeline [configuration file](../yaml/README.md), job names must include two numbers separated with one of
the following (you can even use them interchangeably):
- A space.
- A slash (`/`).
- A colon (`:`).
NOTE: **Note:**
More specifically, it uses [this](https://gitlab.com/gitlab-org/gitlab/blob/2f3dc314f42dbd79813e6251792853bc231e69dd/app/models/commit_status.rb#L99) regular expression: `\d+[\s:\/\\]+\d+\s*`.
#### How grouping works
The jobs will be ordered by comparing those two numbers from left to right. You
usually want the first to be the index and the second the total.
For example, the following jobs will be grouped under a job named `test`:
- `test 0 3`
- `test 1 3`
- `test 2 3`
The following jobs will be grouped under a job named `test ruby`:
- `test 1:2 ruby`
- `test 2:2 ruby`
The following jobs will be grouped under a job named `test ruby` as well:
- `1/3 test ruby`
- `2/3 test ruby`
- `3/3 test ruby`
### Pipelines for merge requests
GitLab supports configuring pipelines that run only for merge requests. For more information, see
[Pipelines for merge requests](../merge_request_pipelines/index.md).
### Badges
Pipeline status and test coverage report badges are available and configurable for each project.
For information on adding pipeline badges to projects, see [Pipeline badges](settings.md#pipeline-badges).
## Multi-project pipelines
Pipelines for different projects can be combined together into [Multi-project pipelines](../multi_project_pipelines.md).
[Multi-project pipeline graphs](../multi_project_pipelines.md#multi-project-pipeline-visualization-premium) help
you visualize the entire pipeline, including all cross-project inter-dependencies. **(PREMIUM)**
## Parent-child pipelines
Complex pipelines can be broken down into one parent pipeline that can trigger
multiple child sub-pipelines, which all run in the same project and with the same SHA.
For more information, see [Parent-Child pipelines](../parent_child_pipelines.md).
## Working with pipelines
In general, pipelines are executed automatically and require no intervention once created.
However, there are instances where you'll need to interact with pipelines. These are documented below.
### Manually executing pipelines
Pipelines can be manually executed, with predefined or manually-specified [variables](../variables/README.md).
You might do this if the results of a pipeline (for example, a code build) is required outside the normal
operation of the pipeline.
To execute a pipeline manually:
1. Navigate to your project's **CI/CD > Pipelines**.
1. Click on the **Run Pipeline** button.
1. On the **Run Pipeline** page:
1. Select the branch to run the pipeline for in the **Create for** field.
1. Enter any [environment variables](../variables/README.md) required for the pipeline run.
1. Click the **Create pipeline** button.
The pipeline will execute the jobs as configured.
#### Using a query string
> [Introduced](https://gitlab.com/gitlab-org/gitlab/issues/24146) in GitLab 12.5.
Variables on the **Run Pipeline** page can be pre-populated by passing variable keys and values
in a query string appended to the `pipelines/new` URL. The format is:
```plaintext
.../pipelines/new?ref=<branch>&var[<variable_key>]=<value>&file_var[<file_key>]=<value>
```
The following parameters are supported:
- `ref`: specify the branch to populate the **Run for** field with.
- `var`: specify a `Variable` variable.
- `file_var`: specify a `File` variable.
For each `var` or `file_var`, a key and value are required.
For example, the query string
`.../pipelines/new?ref=my_branch&var[foo]=bar&file_var[file_foo]=file_bar` will pre-populate the
**Run Pipeline** page as follows:
- **Run for** field: `my_branch`.
- **Variables** section:
- Variable:
- Key: `foo`
- Value: `bar`
- File:
- Key: `file_foo`
- Value: `file_bar`
### Accessing pipelines
You can find the current and historical pipeline runs under your project's
**CI/CD > Pipelines** page. You can also access pipelines for a merge request by navigating
to its **Pipelines** tab.
![Pipelines index page](img/pipelines_index.png)
Clicking on a pipeline will bring you to the **Pipeline Details** page and show
the jobs that were run for that pipeline. From here you can cancel a running pipeline,
retry jobs on a failed pipeline, or [delete a pipeline](#deleting-a-single-pipeline).
### Accessing individual jobs
When you access a pipeline, you can see the related jobs for that pipeline.
Clicking on an individual job will show you its job log, and allow you to:
- Cancel the job.
- Retry the job.
- Erase the job log.
### Seeing the failure reason for jobs
> [Introduced](https://gitlab.com/gitlab-org/gitlab-foss/-/merge_requests/17782) in GitLab 10.7.
When a pipeline fails or is allowed to fail, there are several places where you
can quickly check the reason it failed:
- In the pipeline graph, on the pipeline detail view.
- In the pipeline widgets, in the merge requests and commit pages.
- In the job views, in the global and detailed views of a job.
In each place, if you hover over the failed job you can see the reason it failed.
![Pipeline detail](img/job_failure_reason.png)
From [GitLab 10.8](https://gitlab.com/gitlab-org/gitlab-foss/-/merge_requests/17814),
you can also see the reason it failed on the Job detail page.
### Manual actions from pipeline graphs
> [Introduced](https://gitlab.com/gitlab-org/gitlab-foss/-/merge_requests/7931) in GitLab 8.15.
Manual actions, configured using the [`when:manual`](../yaml/README.md#whenmanual) parameter,
allow you to require manual interaction before moving forward in the pipeline.
You can do this straight from the pipeline graph. Just click on the play button
to execute that particular job.
For example, your pipeline start automatically, but require manual action to
[deploy to production](../environments.md#configuring-manual-deployments). In the example below, the `production`
stage has a job with a manual action.
![Pipelines example](img/pipelines.png)
### Specifying variables when running manual jobs
> [Introduced](https://gitlab.com/gitlab-org/gitlab-foss/-/merge_requests/30485) in GitLab 12.2.
When running manual jobs you can supply additional job specific variables.
You can do this from the job page of the manual job you want to run with
additional variables.
This is useful when you want to alter the execution of a job by using
environment variables.
![Manual job variables](img/manual_job_variables.png)
### Delay a job in a pipeline graph
> [Introduced](https://gitlab.com/gitlab-org/gitlab-foss/-/merge_requests/21767) in GitLab 11.4.
When you do not want to run a job immediately, you can use the [`when:delayed`](../yaml/README.md#whendelayed) parameter to
delay a job's execution for a certain period.
This is especially useful for timed incremental rollout where new code is rolled out gradually.
For example, if you start rolling out new code and:
- Users do not experience trouble, GitLab can automatically complete the deployment from 0% to 100%.
- Users experience trouble with the new code, you can stop the timed incremental rollout by canceling the pipeline
and [rolling](../environments.md#retrying-and-rolling-back) back to the last stable version.
![Pipelines example](img/pipeline_incremental_rollout.png)
### Using the API
GitLab provides API endpoints to:
- Perform basic functions. For more information, see [Pipelines API](../../api/pipelines.md).
- Maintain pipeline schedules. For more information, see [Pipeline schedules API](../../api/pipeline_schedules.md).
- Trigger pipeline runs. For more information, see:
- [Triggering pipelines through the API](../triggers/README.md).
- [Pipeline triggers API](../../api/pipeline_triggers.md).
### Start multiple manual actions in a stage
> [Introduced](https://gitlab.com/gitlab-org/gitlab-foss/-/merge_requests/27188) in GitLab 11.11.
Multiple manual actions in a single stage can be started at the same time using the "Play all manual" button.
Once the user clicks this button, each individual manual action will be triggered and refreshed
to an updated status.
This functionality is only available:
- For users with at least Developer access.
- If the the stage contains [manual actions](#manual-actions-from-pipeline-graphs).
### Deleting a single pipeline
> [Introduced](https://gitlab.com/gitlab-org/gitlab/issues/24851) in GitLab 12.7.
Users with [owner permissions](../../user/permissions.md) in a project can delete a pipeline
by clicking on the pipeline in the **CI/CD > Pipelines** to get to the **Pipeline Details**
page, then using the **Delete** button.
![Pipeline Delete Button](img/pipeline-delete.png)
CAUTION: **Warning:**
Deleting a pipeline will expire all pipeline caches, and delete all related objects,
such as builds, logs, artifacts, and triggers. **This action cannot be undone.**
## Most Recent Pipeline
> [Introduced](https://gitlab.com/gitlab-org/gitlab-foss/issues/50499) in GitLab 12.3.
There's a link to the latest pipeline for the last commit of a given branch at `/project/pipelines/[branch]/latest`. Also, `/project/pipelines/latest` will redirect you to the latest pipeline for the last commit on the project's default branch.
## Security on protected branches
A strict security model is enforced when pipelines are executed on
[protected branches](../../user/project/protected_branches.md).
The following actions are allowed on protected branches only if the user is
[allowed to merge or push](../../user/project/protected_branches.md#using-the-allowed-to-merge-and-allowed-to-push-settings)
on that specific branch:
- Run manual pipelines (using the [Web UI](#manually-executing-pipelines) or pipelines API).
- Run scheduled pipelines.
- Run pipelines using triggers.
- Trigger manual actions on existing pipelines.
- Retry or cancel existing jobs (using the Web UI or pipelines API).
**Variables** marked as **protected** are accessible only to jobs that
run on protected branches, preventing untrusted users getting unintended access to
sensitive information like deployment credentials and tokens.
**Runners** marked as **protected** can run jobs only on protected
branches, avoiding untrusted code to be executed on the protected runner and
preserving deployment keys and other credentials from being unintentionally
accessed. In order to ensure that jobs intended to be executed on protected
runners will not use regular runners, they must be tagged accordingly.
## Persistent pipeline refs
> [Introduced](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/17043) in GitLab 12.4.
Previously, you'd have encountered unexpected pipeline failures when you force-pushed
a branch to its remote repository. To illustrate the problem, suppose you've had the current workflow:
1. A user creates a feature branch named `example` and pushes it to a remote repository.
1. A new pipeline starts running on the `example` branch.
1. A user rebases the `example` branch on the latest `master` branch and force-pushes it to its remote repository.
1. A new pipeline starts running on the `example` branch again, however,
the previous pipeline (2) fails because of `fatal: reference is not a tree:` error.
This is because the previous pipeline cannot find a checkout-SHA (which associated with the pipeline record)
from the `example` branch that the commit history has already been overwritten by the force-push.
Similarly, [Pipelines for merged results](../merge_request_pipelines/pipelines_for_merged_results/index.md)
might have failed intermittently due to [the same reason](../merge_request_pipelines/pipelines_for_merged_results/index.md#intermittently-pipelines-fail-by-fatal-reference-is-not-a-tree-error).
As of GitLab 12.4, we've improved this behavior by persisting pipeline refs exclusively.
To illustrate its life cycle:
1. A pipeline is created on a feature branch named `example`.
1. A persistent pipeline ref is created at `refs/pipelines/<pipeline-id>`,
which retains the checkout-SHA of the associated pipeline record.
This persistent ref stays intact during the pipeline execution,
even if the commit history of the `example` branch has been overwritten by force-push.
1. GitLab Runner fetches the persistent pipeline ref and gets source code from the checkout-SHA.
1. When the pipeline finished, its persistent ref is cleaned up in a background process.
NOTE: **NOTE**: At this moment, this feature is on by default and can be manually disabled
by disabling `depend_on_persistent_pipeline_ref` feature flag. If you're interested in
manually disabling this behavior, please ask the administrator
to execute the following commands in rails console.
```shell
> sudo gitlab-rails console # Login to Rails console of GitLab instance.
> project = Project.find_by_full_path('namespace/project-name') # Get the project instance.
> Feature.disable(:depend_on_persistent_pipeline_ref, project) # Disable the feature flag for specific project
> Feature.disable(:depend_on_persistent_pipeline_ref) # Disable the feature flag system-wide
```
doc/ci/pipelines/schedules.md
View file @ 22e7bf19
......@@ -12,7 +12,7 @@ Cron notation is parsed by [Fugit](https://github.com/floraison/fugit).
Pipelines are normally run based on certain conditions being met. For example, when a branch is pushed to repository.
Pipeline schedules can be used to also run [pipelines](../pipelines.md) at specific intervals. For example:
Pipeline schedules can be used to also run [pipelines](index.md) at specific intervals. For example:
- Every month on the 22nd for a certain branch.
- Once every day.
......
doc/ci/pipelines/settings.md 0 → 100644
View file @ 22e7bf19
---
type: reference, howto
---
# Pipelines settings
To reach the pipelines settings navigate to your project's
**Settings > CI/CD**.
The following settings can be configured per project.
<i class="fa fa-youtube-play youtube" aria-hidden="true"></i>
For an overview, watch the video [GitLab CI Pipeline, Artifacts, and Environments](https://www.youtube.com/watch?v=PCKDICEe10s).
Watch also [GitLab CI pipeline tutorial for beginners](https://www.youtube.com/watch?v=Jav4vbUrqII).
## 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 local working copy is always pristine.
- `git fetch`, which is faster as it re-uses the local working copy (falling
back to clone if it doesn't exist).
The default Git strategy can be overridden by the [GIT_STRATEGY variable](../yaml/README.md#git-strategy)
in `.gitlab-ci.yml`.
## Git shallow clone
> [Introduced](https://gitlab.com/gitlab-org/gitlab-foss/-/merge_requests/28919) in GitLab 12.0.
NOTE: **Note**:
As of GitLab 12.0, newly created projects will automatically 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`](../large_repositories/index.md#shallow-cloning) variable in `.gitlab-ci.yml` file.
## Timeout
Timeout defines the maximum amount of time in minutes that a job is able run.
This is configurable under your project's **Settings > CI/CD > General pipelines settings**.
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.
### Timeout overriding on Runner level
> [Introduced](https://gitlab.com/gitlab-org/gitlab-foss/-/merge_requests/17221) in GitLab 10.7.
Project defined timeout (either specific timeout set by user or the default
60 minutes timeout) may be [overridden on Runner level](../runners/README.md#setting-maximum-job-timeout-for-a-runner).
## Maximum artifacts size **(CORE ONLY)**
For information about setting a maximum artifact size for a project, see
[Maximum artifacts size](../../user/admin_area/settings/continuous_integration.md#maximum-artifacts-size-core-only).
## Custom CI configuration path
> - [Introduced](https://gitlab.com/gitlab-org/gitlab-foss/-/merge_requests/12509) in GitLab 9.4.
> - [Support for external `.gitlab-ci.yml` locations](https://gitlab.com/gitlab-org/gitlab/issues/14376) introduced in GitLab 12.6.
By default we look for the `.gitlab-ci.yml` file in the project's root
directory. If needed, you can specify an alternate path and file name, including locations outside the project.
To customize the path:
1. Go to the project's **Settings > CI / CD**.
1. Expand the **General pipelines** section.
1. Provide a value in the **Custom CI configuration path** field.
1. Click **Save changes**.
If the CI configuration is stored within the repository in a non-default
location, the path must be relative to the root directory. Examples of valid
paths and file names include:
- `.gitlab-ci.yml` (default)
- `.my-custom-file.yml`
- `my/path/.gitlab-ci.yml`
- `my/path/.my-custom-file.yml`
If the CI configuration will be hosted on an external site, the URL link must end with `.yml`:
- `http://example.com/generate/ci/config.yml`
If the CI configuration will be hosted in a different project within GitLab, the path must be relative
to the root directory in the other project, with the group and project name added to the end:
- `.gitlab-ci.yml@mygroup/another-project`
- `my/path/.my-custom-file.yml@mygroup/another-project`
Hosting the configuration file in a separate project allows stricter control of the
configuration file. For example:
- Create a public project to host the configuration file.
- Give write permissions on the project only to users who are allowed to edit the file.
Other users and projects will be able to access the configuration file without being
able to edit it.
## Test coverage parsing
If you use test coverage in your code, GitLab can capture its output in the
job 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 <https://rubular.com> to test your regex.
If the pipeline succeeds, the coverage is shown in the merge request widget and
in the jobs 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.
### Removing color codes
Some test coverage tools output with ANSI color codes that won't be
parsed correctly by the regular expression and will cause coverage
parsing to fail.
If your coverage tool doesn't provide an option to disable color
codes in the output, you can pipe the output of the coverage tool through a
small one line script that will strip the color codes off.
For example:
```shell
lein cloverage | perl -pe 's/\e\[?.*?[\@-~]//g'
```
## Visibility of pipelines
Pipeline visibility is determined by:
- Your current [user access level](../../user/permissions.md).
- The **Public pipelines** project setting under your project's **Settings > CI/CD > General pipelines**.
NOTE: **Note:**
If the project visibility is set to **Private**, the [**Public pipelines** setting will have no effect](../enable_or_disable_ci.md#per-project-user-setting).
This also determines the visibility of these related features:
- Job output logs
- Job artifacts
- The [pipeline security dashboard](../../user/application_security/security_dashboard/index.md#pipeline-security-dashboard) **(ULTIMATE)**
If **Public pipelines** is enabled (default):
- For **public** projects, anyone can view the pipelines and related features.
- For **internal** projects, any logged in user can view the pipelines
and related features.
- For **private** projects, any project member (guest or higher) can view the pipelines
and related features.
If **Public pipelines** is disabled:
- For **public** projects, anyone can view the pipelines, but only members
(reporter or higher) can access the related features.
- For **internal** projects, any logged in user can view the pipelines.
However, only members (reporter or higher) can access the job related features.
- For **private** projects, only project members (reporter or higher)
can view the pipelines or access the related features.
## Auto-cancel pending pipelines
> [Introduced](https://gitlab.com/gitlab-org/gitlab-foss/-/merge_requests/9362) in GitLab 9.1.
If you want all pending non-HEAD pipelines on branches to auto-cancel each time
a new pipeline is created, such as after a Git push or manually from the UI,
you can enable this in the project settings:
1. Go to **{settings}** **Settings > CI / CD**.
1. Expand **General Pipelines**.
1. Check the **Auto-cancel redundant, pending pipelines** checkbox.
1. Click **Save changes**.
## Skip older, pending deployment jobs
> [Introduced](https://gitlab.com/gitlab-org/gitlab/issues/25276) in GitLab 12.9.
Your project may have multiple concurrent deployment jobs that are
scheduled to run within the same time frame.
This can lead to a situation where an older deployment job runs after a
newer one, which may not be what you want.
To avoid this scenario:
1. Go to **{settings}** **Settings > CI / CD**.
1. Expand **General pipelines**.
1. Check the **Skip older, pending deployment jobs** checkbox.
1. Click **Save changes**.
The pending deployment jobs will be skipped.
## Pipeline Badges
In the pipelines settings page you can find pipeline status and test coverage
badges for your project. The latest successful pipeline will be used to read
the pipeline 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)
### Pipeline status badge
Depending on the status of your job, a badge can have the following values:
- pending
- running
- passed
- failed
- skipped
- canceled
- unknown
You can access a pipeline status badge image using the following link:
```text
https://example.gitlab.com/<namespace>/<project>/badges/<branch>/pipeline.svg
```
### Test coverage report badge
GitLab makes it possible to define the regular expression for [coverage report](#test-coverage-parsing),
that each job log will be matched against. This means that each job in the
pipeline can have the test coverage percentage value defined.
The test coverage badge can be accessed using following link:
```text
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-foss/badges/master/coverage.svg?job=coverage)
```
### 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)
```text
https://example.gitlab.com/<namespace>/<project>/badges/<branch>/coverage.svg?style=flat
```
![Badge flat style](https://gitlab.com/gitlab-org/gitlab-foss/badges/master/coverage.svg?job=coverage&style=flat)
#### Flat square
> [Introduced](https://gitlab.com/gitlab-org/gitlab-foss/issues/30120) in GitLab 11.8.
```text
https://example.gitlab.com/<namespace>/<project>/badges/<branch>/coverage.svg?style=flat-square
```
![Badge flat square style](https://gitlab.com/gitlab-org/gitlab-foss/badges/master/coverage.svg?job=coverage&style=flat-square)
## Environment Variables
[Environment variables](../variables/README.md#gitlab-cicd-environment-variables) can be set in an environment to be available to a runner.
## Deploy Keys
With Deploy Keys, GitLab allows you to import SSH public keys. You can then have
read only or read/write access to your project from the machines the keys were generated from.
SSH keys added to your project settings will be used for continuous integration,
staging, or production servers.
<!-- ## Troubleshooting
Include any troubleshooting steps that you can foresee. If you know beforehand what issues
one might have when setting this up, or when something is changed, or on upgrading, it's
important to describe those, too. Think of things that may go wrong and include them here.
This is important to minimize requests for support, and to avoid doc comments with
questions that you know someone might ask.
Each scenario can be a third-level heading, e.g. `### Getting error message X`.
If you have none to add when creating a doc, leave this section in place
but commented out to help encourage others to add to it in the future. -->
doc/ci/quick_start/README.md
View file @ 22e7bf19
......@@ -23,7 +23,7 @@ that you can consider for use in your project. You may want to familiarize
yourself with these prior to getting started.
GitLab offers a [continuous integration](https://about.gitlab.com/stages-devops-lifecycle/continuous-integration/) service. For each commit or push to trigger your CI
[pipeline](../pipelines.md), you must:
[pipeline](../pipelines/index.md), you must:
- Add a [`.gitlab-ci.yml` file](#creating-a-gitlab-ciyml-file) to your repository's root directory.
- Ensure your project is configured to use a [Runner](#configuring-a-runner).
......
doc/ci/runners/README.md
View file @ 22e7bf19
......@@ -422,4 +422,4 @@ You can find the IP address of a Runner for a specific project by:
[register]: https://docs.gitlab.com/runner/register/
[protected branches]: ../../user/project/protected_branches.md
[protected tags]: ../../user/project/protected_tags.md
[project defined timeout]: ../../user/project/pipelines/settings.html#timeout
[project defined timeout]: ../pipelines/settings.md#timeout
doc/ci/ssh_keys/README.md
View file @ 22e7bf19
......@@ -37,7 +37,7 @@ with any type of [executor](https://docs.gitlab.com/runner/executors/)
NOTE: **Note:**
The private key will not be displayed in the job log, unless you enable
[debug logging](../variables/README.md#debug-logging). You might also want to
check the [visibility of your pipelines](../../user/project/pipelines/settings.md#visibility-of-pipelines).
check the [visibility of your pipelines](../pipelines/settings.md#visibility-of-pipelines).
## SSH keys when using the Docker executor
......
doc/ci/variables/README.md
View file @ 22e7bf19
......@@ -169,7 +169,7 @@ You can either set the variable directly in the `.gitlab-ci.yml`
file or through the UI.
NOTE: **Note:**
It is possible to [specify variables when running manual jobs](../pipelines.md#specifying-variables-when-running-manual-jobs).
It is possible to [specify variables when running manual jobs](../pipelines/index.md#specifying-variables-when-running-manual-jobs).
#### Via `.gitlab-ci.yml`
......@@ -460,7 +460,7 @@ limitations with the current Auto DevOps scripting environment.
> [Introduced](https://gitlab.com/gitlab-org/gitlab-foss/issues/44059) in GitLab 10.8.
[Manually triggered pipelines](../pipelines.md#manually-executing-pipelines) allow you to override the value of a current variable.
[Manually triggered pipelines](../pipelines/index.md#manually-executing-pipelines) allow you to override the value of a current variable.
For instance, suppose you added a
[custom variable `$TEST`](#creating-a-custom-environment-variable)
......@@ -616,7 +616,7 @@ variables that were set, etc.
Before enabling this, you should ensure jobs are visible to
[team members only](../../user/permissions.md#project-features). You should
also [erase](../pipelines.md#accessing-individual-jobs) all generated job logs
also [erase](../pipelines/index.md#accessing-individual-jobs) all generated job logs
before making them visible again.
To enable debug logs (traces), set the `CI_DEBUG_TRACE` variable to `true`:
......
doc/ci/yaml/README.md
View file @ 22e7bf19
......@@ -4,7 +4,7 @@ type: reference
# GitLab CI/CD Pipeline Configuration Reference
GitLab CI/CD [pipelines](../pipelines.md) are configured using a YAML file called `.gitlab-ci.yml` within each project.
GitLab CI/CD [pipelines](../pipelines/index.md) are configured using a YAML file called `.gitlab-ci.yml` within each project.
The `.gitlab-ci.yml` file defines the structure and order of the pipelines and determines:
......@@ -2735,7 +2735,7 @@ test:
```
The job-level timeout can exceed the
[project-level timeout](../../user/project/pipelines/settings.md#timeout) but can not
[project-level timeout](../pipelines/settings.md#timeout) but can not
exceed the Runner-specific timeout.
### `parallel`
......@@ -2906,7 +2906,7 @@ starting, at the cost of reduced parallelization.
> [Introduced](https://gitlab.com/gitlab-org/gitlab-foss/-/merge_requests/23464) in GitLab 12.3.
`interruptible` is used to indicate that a job should be canceled if made redundant by a newer pipeline run. Defaults to `false`.
This value will only be used if the [automatic cancellation of redundant pipelines feature](../../user/project/pipelines/settings.md#auto-cancel-pending-pipelines)
This value will only be used if the [automatic cancellation of redundant pipelines feature](../pipelines/settings.md#auto-cancel-pending-pipelines)
is enabled.
When enabled, a pipeline on the same branch will be canceled when:
......
doc/subscriptions/index.md
View file @ 22e7bf19
......@@ -354,7 +354,7 @@ features, and the instance will be read / write again.
## CI pipeline minutes
CI pipeline minutes are the execution time for your [pipelines](../ci/pipelines.md) on GitLab's shared runners. Each [GitLab.com tier](https://about.gitlab.com/pricing/) includes a monthly quota of CI pipeline minutes.
CI pipeline minutes are the execution time for your [pipelines](../ci/pipelines/index.md) on GitLab's shared runners. Each [GitLab.com tier](https://about.gitlab.com/pricing/) includes a monthly quota of CI pipeline minutes.
Quotas apply to:
......
doc/topics/autodevops/index.md
View file @ 22e7bf19
......@@ -1375,7 +1375,7 @@ increasing the rollout up to 100%.
If `INCREMENTAL_ROLLOUT_MODE` is set to `manual` in your project, then instead
of the standard `production` job, 4 different
[manual jobs](../../ci/pipelines.md#manual-actions-from-pipeline-graphs)
[manual jobs](../../ci/pipelines/index.md#manual-actions-from-pipeline-graphs)
will be created:
1. `rollout 10%`
......
doc/user/admin_area/settings/continuous_integration.md
View file @ 22e7bf19
......@@ -53,7 +53,7 @@ To change it at the:
1. Change the value of **maximum artifacts size (in MB)**.
1. Press **Save changes** for the changes to take effect.
- [Project level](../../project/pipelines/settings.md) (this will override the instance and group settings):
- [Project level](../../../ci/pipelines/settings.md) (this will override the instance and group settings):
1. Go to the project's **Settings > CI / CD > General Pipelines**.
1. Change the value of **maximum artifacts size (in MB)**.
......@@ -152,7 +152,7 @@ Area of your GitLab instance (`.gitlab-ci.yml` if not set):
1. Input the new path in the **Default CI configuration path** field.
1. Hit **Save changes** for the changes to take effect.
It is also possible to specify a [custom CI configuration path for a specific project](../../project/pipelines/settings.md#custom-ci-configuration-path).
It is also possible to specify a [custom CI configuration path for a specific project](../../../ci/pipelines/settings.md#custom-ci-configuration-path).
<!-- ## Troubleshooting
......
doc/user/application_security/configuration/index.md
View file @ 22e7bf19
......@@ -13,7 +13,7 @@ features and can be accessed through a project's sidebar nav.
![Screenshot of security configuration page](../img/security_configuration_page_v12_9.png)
The page uses the project's latest default branch [CI pipeline](../../../ci/pipelines.md) to determine the configuration
The page uses the project's latest default branch [CI pipeline](../../../ci/pipelines/index.md) to determine the configuration
state of each feature. If a job with the expected security report artifact exists in the pipeline,
the feature is considered configured.
......
doc/user/permissions.md
View file @ 22e7bf19
......@@ -420,7 +420,7 @@ read through the documentation on the [new CI/CD permissions model](project/new_
The permission to merge or push to protected branches is used to define if a user can
run CI/CD pipelines and execute actions on jobs that are related to those branches.
See [Security on protected branches](../ci/pipelines.md#security-on-protected-branches)
See [Security on protected branches](../ci/pipelines/index.md#security-on-protected-branches)
for details about the pipelines security model.
## LDAP users permissions
......
doc/user/project/badges.md
View file @ 22e7bf19
......@@ -75,5 +75,5 @@ You can also configure badges via the GitLab API. As in the settings, there is
a distinction between endpoints for badges on the
[project level](../../api/project_badges.md) and [group level](../../api/group_badges.md).
[pipeline status]: pipelines/settings.md#pipeline-status-badge
[test coverage]: pipelines/settings.md#test-coverage-report-badge
[pipeline status]: ../../ci/pipelines/settings.md#pipeline-status-badge
[test coverage]: ../../ci/pipelines/settings.md#test-coverage-report-badge
doc/user/project/clusters/index.md
View file @ 22e7bf19
......@@ -20,7 +20,7 @@ NOTE: **Scalable app deployment with GitLab and Google Cloud Platform**
Using the GitLab project Kubernetes integration, you can:
- Use [Review Apps](../../../ci/review_apps/index.md).
- Run [pipelines](../../../ci/pipelines.md).
- Run [pipelines](../../../ci/pipelines/index.md).
- [Deploy](#deploying-to-a-kubernetes-cluster) your applications.
- Detect and [monitor Kubernetes](#kubernetes-monitoring).
- Use it with [Auto DevOps](#auto-devops).
......
doc/user/project/import/gemnasium.md
View file @ 22e7bf19
......@@ -102,5 +102,5 @@ back to both GitLab and GitHub when completed.
NOTE: **Note:**
If you don't commit very often to your project, you may want to use
[scheduled pipelines](../pipelines/schedules.md) to run the job on a regular
[scheduled pipelines](../../../ci/pipelines/schedules.md) to run the job on a regular
basis.
doc/user/project/index.md
View file @ 22e7bf19
......@@ -66,15 +66,15 @@ When you create a project in GitLab, you'll have access to a large number of
- [Auto Deploy](../../topics/autodevops/index.md#auto-deploy): Configure GitLab CI/CD
to automatically set up your app's deployment
- [Enable and disable GitLab CI](../../ci/enable_or_disable_ci.md)
- [Pipelines](../../ci/pipelines.md): Configure and visualize
- [Pipelines](../../ci/pipelines/index.md): Configure and visualize
your GitLab CI/CD pipelines from the UI
- [Scheduled Pipelines](pipelines/schedules.md): Schedule a pipeline
- [Scheduled Pipelines](../../ci/pipelines/schedules.md): Schedule a pipeline
to start at a chosen time
- [Pipeline Graphs](../../ci/pipelines.md#visualizing-pipelines): View your
- [Pipeline Graphs](../../ci/pipelines/index.md#visualizing-pipelines): View your
entire pipeline from the UI
- [Job artifacts](pipelines/job_artifacts.md): Define,
- [Job artifacts](../../ci/pipelines/job_artifacts.md): Define,
browse, and download job artifacts
- [Pipeline settings](pipelines/settings.md): Set up Git strategy (choose the default way your repository is fetched from GitLab in a job),
- [Pipeline settings](../../ci/pipelines/settings.md): Set up Git strategy (choose the default way your repository is fetched from GitLab in a job),
timeout (defines the maximum amount of time in minutes that a job is able run), custom path for `.gitlab-ci.yml`, test coverage parsing, pipeline's visibility, and much more
- [Kubernetes cluster integration](clusters/index.md): Connecting your GitLab project
with a Kubernetes cluster
......
doc/user/project/merge_requests/code_quality.md
View file @ 22e7bf19
......@@ -14,7 +14,7 @@ Code Quality:
- Uses [Code Climate Engines](https://codeclimate.com), which are
free and open source. Code Quality doesn't require a Code Climate
subscription.
- Runs in [pipelines](../../../ci/pipelines.md) using a Docker image built in the
- Runs in [pipelines](../../../ci/pipelines/index.md) using a Docker image built in the
[GitLab Code
Quality](https://gitlab.com/gitlab-org/security-products/codequality) project using [default Code Climate configurations](https://gitlab.com/gitlab-org/security-products/codequality/-/tree/master/codeclimate_defaults).
- Can make use of a [template](#example-configuration).
......
doc/user/project/merge_requests/index.md
View file @ 22e7bf19
......@@ -94,14 +94,14 @@ or link to useful information directly in the merge request page:
| [Accessibility Testing](accessibility_testing.md) | Automatically report A11y violations for changed pages in merge requests |
| [Browser Performance Testing](browser_performance_testing.md) **(PREMIUM)** | Quickly determine the performance impact of pending code changes. |
| [Code Quality](code_quality.md) **(STARTER)** | Analyze your source code quality using the [Code Climate](https://codeclimate.com/) analyzer and show the Code Climate report right in the merge request widget area. |
| [Display arbitrary job artifacts](../../../ci/yaml/README.md#artifactsexpose_as) | Configure CI pipelines with the `artifacts:expose_as` parameter to directly link to selected [artifacts](../pipelines/job_artifacts.md) in merge requests. |
| [Display arbitrary job artifacts](../../../ci/yaml/README.md#artifactsexpose_as) | Configure CI pipelines with the `artifacts:expose_as` parameter to directly link to selected [artifacts](../../../ci/pipelines/job_artifacts.md) in merge requests. |
| [GitLab CI/CD](../../../ci/README.md) | Build, test, and deploy your code in a per-branch basis with built-in CI/CD. |
| [JUnit test reports](../../../ci/junit_test_reports.md) | Configure your CI jobs to use JUnit test reports, and let GitLab display a report on the merge request so that it’s easier and faster to identify the failure without having to check the entire job log. |
| [License Compliance](../../compliance/license_compliance/index.md) **(ULTIMATE)** | Manage the licenses of your dependencies. |
| [Metrics Reports](../../../ci/metrics_reports.md) **(PREMIUM)** | Display the Metrics Report on the merge request so that it's fast and easy to identify changes to important metrics. |
| [Multi-Project pipelines](../../../ci/multi_project_pipelines.md) **(PREMIUM)** | When you set up GitLab CI/CD across multiple projects, you can visualize the entire pipeline, including all cross-project interdependencies. |
| [Pipelines for merge requests](../../../ci/merge_request_pipelines/index.md) | Customize a specific pipeline structure for merge requests in order to speed the cycle up by running only important jobs. |
| [Pipeline Graphs](../../../ci/pipelines.md#visualizing-pipelines) | View the status of pipelines within the merge request, including the deployment process. |
| [Pipeline Graphs](../../../ci/pipelines/index.md#visualizing-pipelines) | View the status of pipelines within the merge request, including the deployment process. |
### Security Reports **(ULTIMATE)**
......
doc/user/project/merge_requests/reviewing_and_managing_merge_requests.md
View file @ 22e7bf19
......@@ -120,7 +120,7 @@ be disabled. If the pipeline fails to deploy, the deployment info will be hidden
![Merge request pipeline](img/merge_request_pipeline.png)
For more information, [read about pipelines](../../../ci/pipelines.md).
For more information, [read about pipelines](../../../ci/pipelines/index.md).
### Merge when pipeline succeeds (MWPS)
......
doc/user/project/pipelines/job_artifacts.md
View file @ 22e7bf19
......@@ -2,4 +2,4 @@
redirect_to: '../../../ci/pipelines/job_artifacts.md'
---
This document was moved to [pipelines/job_artifacts.md](../../../ci/pipelines/job_artifacts.md).
This document was moved to [another location](../../../ci/pipelines/job_artifacts.md).
doc/user/project/pipelines/settings.md
View file @ 22e7bf19
---
type: reference, howto
redirect_to: '../../../ci/pipelines/settings.md'
---
# Pipelines settings
To reach the pipelines settings navigate to your project's
**Settings > CI/CD**.
The following settings can be configured per project.
<i class="fa fa-youtube-play youtube" aria-hidden="true"></i>
For an overview, watch the video [GitLab CI Pipeline, Artifacts, and Environments](https://www.youtube.com/watch?v=PCKDICEe10s).
Watch also [GitLab CI pipeline tutorial for beginners](https://www.youtube.com/watch?v=Jav4vbUrqII).
## 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 local working copy is always pristine.
- `git fetch`, which is faster as it re-uses the local working copy (falling
back to clone if it doesn't exist).
The default Git strategy can be overridden by the [GIT_STRATEGY variable](../../../ci/yaml/README.md#git-strategy)
in `.gitlab-ci.yml`.
## Git shallow clone
> [Introduced](https://gitlab.com/gitlab-org/gitlab-foss/-/merge_requests/28919) in GitLab 12.0.
NOTE: **Note**:
As of GitLab 12.0, newly created projects will automatically 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.
## Timeout
Timeout defines the maximum amount of time in minutes that a job is able run.
This is configurable under your project's **Settings > CI/CD > General pipelines settings**.
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.
### Timeout overriding on Runner level
> [Introduced](https://gitlab.com/gitlab-org/gitlab-foss/-/merge_requests/17221) in GitLab 10.7.
Project defined timeout (either specific timeout set by user or the default
60 minutes timeout) may be [overridden on Runner level](../../../ci/runners/README.md#setting-maximum-job-timeout-for-a-runner).
## Maximum artifacts size **(CORE ONLY)**
For information about setting a maximum artifact size for a project, see
[Maximum artifacts size](../../admin_area/settings/continuous_integration.md#maximum-artifacts-size-core-only).
## Custom CI configuration path
> - [Introduced](https://gitlab.com/gitlab-org/gitlab-foss/-/merge_requests/12509) in GitLab 9.4.
> - [Support for external `.gitlab-ci.yml` locations](https://gitlab.com/gitlab-org/gitlab/issues/14376) introduced in GitLab 12.6.
By default we look for the `.gitlab-ci.yml` file in the project's root
directory. If needed, you can specify an alternate path and file name, including locations outside the project.
To customize the path:
1. Go to the project's **Settings > CI / CD**.
1. Expand the **General pipelines** section.
1. Provide a value in the **Custom CI configuration path** field.
1. Click **Save changes**.
If the CI configuration is stored within the repository in a non-default
location, the path must be relative to the root directory. Examples of valid
paths and file names include:
- `.gitlab-ci.yml` (default)
- `.my-custom-file.yml`
- `my/path/.gitlab-ci.yml`
- `my/path/.my-custom-file.yml`
If the CI configuration will be hosted on an external site, the URL link must end with `.yml`:
- `http://example.com/generate/ci/config.yml`
If the CI configuration will be hosted in a different project within GitLab, the path must be relative
to the root directory in the other project, with the group and project name added to the end:
- `.gitlab-ci.yml@mygroup/another-project`
- `my/path/.my-custom-file.yml@mygroup/another-project`
Hosting the configuration file in a separate project allows stricter control of the
configuration file. For example:
- Create a public project to host the configuration file.
- Give write permissions on the project only to users who are allowed to edit the file.
Other users and projects will be able to access the configuration file without being
able to edit it.
## Test coverage parsing
If you use test coverage in your code, GitLab can capture its output in the
job 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 <https://rubular.com> to test your regex.
If the pipeline succeeds, the coverage is shown in the merge request widget and
in the jobs 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.
### Removing color codes
Some test coverage tools output with ANSI color codes that won't be
parsed correctly by the regular expression and will cause coverage
parsing to fail.
If your coverage tool doesn't provide an option to disable color
codes in the output, you can pipe the output of the coverage tool through a
small one line script that will strip the color codes off.
For example:
```shell
lein cloverage | perl -pe 's/\e\[?.*?[\@-~]//g'
```
## Visibility of pipelines
Pipeline visibility is determined by:
- Your current [user access level](../../permissions.md).
- The **Public pipelines** project setting under your project's **Settings > CI/CD > General pipelines**.
NOTE: **Note:**
If the project visibility is set to **Private**, the [**Public pipelines** setting will have no effect](../../../ci/enable_or_disable_ci.md#per-project-user-setting).
This also determines the visibility of these related features:
- Job output logs
- Job artifacts
- The [pipeline security dashboard](../../application_security/security_dashboard/index.md#pipeline-security-dashboard) **(ULTIMATE)**
If **Public pipelines** is enabled (default):
- For **public** projects, anyone can view the pipelines and related features.
- For **internal** projects, any logged in user can view the pipelines
and related features.
- For **private** projects, any project member (guest or higher) can view the pipelines
and related features.
If **Public pipelines** is disabled:
- For **public** projects, anyone can view the pipelines, but only members
(reporter or higher) can access the related features.
- For **internal** projects, any logged in user can view the pipelines.
However, only members (reporter or higher) can access the job related features.
- For **private** projects, only project members (reporter or higher)
can view the pipelines or access the related features.
## Auto-cancel pending pipelines
> [Introduced](https://gitlab.com/gitlab-org/gitlab-foss/-/merge_requests/9362) in GitLab 9.1.
If you want all pending non-HEAD pipelines on branches to auto-cancel each time
a new pipeline is created, such as after a Git push or manually from the UI,
you can enable this in the project settings:
1. Go to **{settings}** **Settings > CI / CD**.
1. Expand **General Pipelines**.
1. Check the **Auto-cancel redundant, pending pipelines** checkbox.
1. Click **Save changes**.
## Skip older, pending deployment jobs
> [Introduced](https://gitlab.com/gitlab-org/gitlab/issues/25276) in GitLab 12.9.
Your project may have multiple concurrent deployment jobs that are
scheduled to run within the same time frame.
This can lead to a situation where an older deployment job runs after a
newer one, which may not be what you want.
To avoid this scenario:
1. Go to **{settings}** **Settings > CI / CD**.
1. Expand **General pipelines**.
1. Check the **Skip older, pending deployment jobs** checkbox.
1. Click **Save changes**.
The pending deployment jobs will be skipped.
## Pipeline Badges
In the pipelines settings page you can find pipeline status and test coverage
badges for your project. The latest successful pipeline will be used to read
the pipeline 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)
### Pipeline status badge
Depending on the status of your job, a badge can have the following values:
- pending
- running
- passed
- failed
- skipped
- canceled
- unknown
You can access a pipeline status badge image using the following link:
```text
https://example.gitlab.com/<namespace>/<project>/badges/<branch>/pipeline.svg
```
### Test coverage report badge
GitLab makes it possible to define the regular expression for [coverage report](#test-coverage-parsing),
that each job log will be matched against. This means that each job in the
pipeline can have the test coverage percentage value defined.
The test coverage badge can be accessed using following link:
```text
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-foss/badges/master/coverage.svg?job=coverage)
```
### 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)
```text
https://example.gitlab.com/<namespace>/<project>/badges/<branch>/coverage.svg?style=flat
```
![Badge flat style](https://gitlab.com/gitlab-org/gitlab-foss/badges/master/coverage.svg?job=coverage&style=flat)
#### Flat square
> [Introduced](https://gitlab.com/gitlab-org/gitlab-foss/issues/30120) in GitLab 11.8.
```text
https://example.gitlab.com/<namespace>/<project>/badges/<branch>/coverage.svg?style=flat-square
```
![Badge flat square style](https://gitlab.com/gitlab-org/gitlab-foss/badges/master/coverage.svg?job=coverage&style=flat-square)
## Environment Variables
[Environment variables](../../../ci/variables/README.md#gitlab-cicd-environment-variables) can be set in an environment to be available to a runner.
## Deploy Keys
With Deploy Keys, GitLab allows you to import SSH public keys. You can then have
read only or read/write access to your project from the machines the keys were generated from.
SSH keys added to your project settings will be used for continuous integration,
staging, or production servers.
<!-- ## Troubleshooting
Include any troubleshooting steps that you can foresee. If you know beforehand what issues
one might have when setting this up, or when something is changed, or on upgrading, it's
important to describe those, too. Think of things that may go wrong and include them here.
This is important to minimize requests for support, and to avoid doc comments with
questions that you know someone might ask.
Each scenario can be a third-level heading, e.g. `### Getting error message X`.
If you have none to add when creating a doc, leave this section in place
but commented out to help encourage others to add to it in the future. -->
This document was moved to [another location](../../../ci/pipelines/settings.md).
doc/user/project/protected_branches.md
View file @ 22e7bf19
......@@ -187,7 +187,7 @@ Additionally, direct pushes to the protected branch are denied if a rule is matc
The permission to merge or push to protected branches is used to define if a user can
run CI/CD pipelines and execute actions on jobs that are related to those branches.
See [Security on protected branches](../../ci/pipelines.md#security-on-protected-branches)
See [Security on protected branches](../../ci/pipelines/index.md#security-on-protected-branches)
for details about the pipelines security model.
## Changelog
......
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
GitLab Nexedi Edition | About GitLab | About Nexedi | 沪ICP备2021021310号-2 | 沪ICP备2021021310号-7