diff options
Diffstat (limited to 'doc/ci/pipelines')
-rw-r--r-- | doc/ci/pipelines/img/coverage_check_approval_rule_14_1.png | bin | 116394 -> 34393 bytes | |||
-rw-r--r-- | doc/ci/pipelines/img/pipelines_graph_dependency_view_hover_v13_12.png | bin | 83953 -> 32488 bytes | |||
-rw-r--r-- | doc/ci/pipelines/img/pipelines_graph_dependency_view_links_v13_12.png | bin | 81552 -> 30970 bytes | |||
-rw-r--r-- | doc/ci/pipelines/img/pipelines_graph_dependency_view_v13_12.png | bin | 77811 -> 29871 bytes | |||
-rw-r--r-- | doc/ci/pipelines/img/pipelines_graph_stage_view_v13_12.png | bin | 63697 -> 25204 bytes | |||
-rw-r--r-- | doc/ci/pipelines/index.md | 52 | ||||
-rw-r--r-- | doc/ci/pipelines/job_artifacts.md | 8 | ||||
-rw-r--r-- | doc/ci/pipelines/merge_request_pipelines.md | 4 | ||||
-rw-r--r-- | doc/ci/pipelines/merge_trains.md | 55 | ||||
-rw-r--r-- | doc/ci/pipelines/multi_project_pipelines.md | 4 | ||||
-rw-r--r-- | doc/ci/pipelines/parent_child_pipelines.md | 6 | ||||
-rw-r--r-- | doc/ci/pipelines/pipelines_for_merged_results.md | 2 | ||||
-rw-r--r-- | doc/ci/pipelines/settings.md | 11 |
13 files changed, 72 insertions, 70 deletions
diff --git a/doc/ci/pipelines/img/coverage_check_approval_rule_14_1.png b/doc/ci/pipelines/img/coverage_check_approval_rule_14_1.png Binary files differindex 00eb5c84ca9..8c1d005e074 100644 --- a/doc/ci/pipelines/img/coverage_check_approval_rule_14_1.png +++ b/doc/ci/pipelines/img/coverage_check_approval_rule_14_1.png diff --git a/doc/ci/pipelines/img/pipelines_graph_dependency_view_hover_v13_12.png b/doc/ci/pipelines/img/pipelines_graph_dependency_view_hover_v13_12.png Binary files differindex ff6b3af0a28..8c4b9d73cdc 100644 --- a/doc/ci/pipelines/img/pipelines_graph_dependency_view_hover_v13_12.png +++ b/doc/ci/pipelines/img/pipelines_graph_dependency_view_hover_v13_12.png diff --git a/doc/ci/pipelines/img/pipelines_graph_dependency_view_links_v13_12.png b/doc/ci/pipelines/img/pipelines_graph_dependency_view_links_v13_12.png Binary files differindex b0923ab96d9..4ad68849e2a 100644 --- a/doc/ci/pipelines/img/pipelines_graph_dependency_view_links_v13_12.png +++ b/doc/ci/pipelines/img/pipelines_graph_dependency_view_links_v13_12.png diff --git a/doc/ci/pipelines/img/pipelines_graph_dependency_view_v13_12.png b/doc/ci/pipelines/img/pipelines_graph_dependency_view_v13_12.png Binary files differindex ae7cdc5b43e..2bb399f61f9 100644 --- a/doc/ci/pipelines/img/pipelines_graph_dependency_view_v13_12.png +++ b/doc/ci/pipelines/img/pipelines_graph_dependency_view_v13_12.png diff --git a/doc/ci/pipelines/img/pipelines_graph_stage_view_v13_12.png b/doc/ci/pipelines/img/pipelines_graph_stage_view_v13_12.png Binary files differindex b3b98313350..f2f38979e18 100644 --- a/doc/ci/pipelines/img/pipelines_graph_stage_view_v13_12.png +++ b/doc/ci/pipelines/img/pipelines_graph_stage_view_v13_12.png diff --git a/doc/ci/pipelines/index.md b/doc/ci/pipelines/index.md index 4f818d658b7..22f18235f99 100644 --- a/doc/ci/pipelines/index.md +++ b/doc/ci/pipelines/index.md @@ -53,7 +53,7 @@ Pipelines can be configured in many different ways: - [Multi-project pipelines](multi_project_pipelines.md) combine pipelines for different projects together. - [Parent-Child pipelines](parent_child_pipelines.md) break down complex pipelines into one parent pipeline that can trigger multiple child sub-pipelines, which all - run in the same project and with the same SHA. + run in the same project and with the same SHA. This pipeline architecture is commonly used for mono-repos. - [Pipelines for Merge Requests](../pipelines/merge_request_pipelines.md) run for merge requests only (rather than for every commit). - [Pipelines for Merged Results](../pipelines/pipelines_for_merged_results.md) @@ -94,7 +94,7 @@ This table lists the refspecs injected for each pipeline type: The refs `refs/heads/<name>` and `refs/tags/<name>` exist in your project repository. GitLab generates the special ref `refs/pipelines/<id>` during a running pipeline job. This ref can be created even after the associated branch or tag has been -deleted. It's therefore useful in some features such as [automatically stopping an environment](../environments/index.md#stopping-an-environment), +deleted. It's therefore useful in some features such as [automatically stopping an environment](../environments/index.md#stop-an-environment), and [merge trains](../pipelines/merge_trains.md) that might run pipelines after branch deletion. @@ -123,6 +123,9 @@ you can filter the pipeline list by: - Status ([GitLab 13.1 and later](https://gitlab.com/gitlab-org/gitlab/-/issues/217617)) - Tag ([GitLab 13.1 and later](https://gitlab.com/gitlab-org/gitlab/-/issues/217617)) +[Starting in GitLab 14.2](https://gitlab.com/gitlab-org/gitlab/-/issues/26621), you can change the +pipeline column to display the pipeline ID or the pipeline IID. + ### Run a pipeline manually Pipelines can be manually executed, with predefined or manually-specified [variables](../variables/index.md). @@ -132,13 +135,13 @@ operation of the pipeline. To execute a pipeline manually: -1. Navigate to your project's **CI/CD > Pipelines**. -1. Select the **Run pipeline** button. -1. On the **Run pipeline** page: - 1. Select the branch or tag to run the pipeline for in the **Run for branch name or tag** field. - 1. Enter any [environment variables](../variables/index.md) required for the pipeline run. - You can set specific variables to have their [values prefilled in the form](#prefill-variables-in-manual-pipelines). - 1. Click the **Run pipeline** button. +1. On the top bar, select **Menu > Projects** and find your project. +1. On the left sidebar, select **CI/CD > Pipelines**. +1. Select **Run pipeline**. +1. In the **Run for branch name or tag** field, select the branch or tag to run the pipeline for. +1. Enter any [environment variables](../variables/index.md) required for the pipeline to run. + You can set specific variables to have their [values prefilled in the form](#prefill-variables-in-manual-pipelines). +1. Select **Run pipeline**. The pipeline now executes the jobs as configured. @@ -167,6 +170,9 @@ variables: You cannot set job-level variables to be pre-filled when you run a pipeline manually. +Pre-filled variables do not show up when the CI/CD configuration is [external to the project](settings.md#specify-a-custom-cicd-configuration-file). +See the [related issue](https://gitlab.com/gitlab-org/gitlab/-/issues/336184) for more details. + ### Run a pipeline by using a URL query string > [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/24146) in GitLab 12.5. @@ -200,7 +206,7 @@ For each `var` or `file_var`, a key and value are required. ### Add manual interaction to your pipeline -Manual actions, configured using the [`when:manual`](../yaml/index.md#whenmanual) keyword, +[Manual jobs](../jobs/job_control.md#create-a-job-that-must-be-run-manually), allow you to require manual interaction before moving forward in the pipeline. You can do this straight from the pipeline graph. Just click the play button @@ -357,12 +363,10 @@ you visualize the entire pipeline, including all cross-project inter-dependencie > - [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/298973) in GitLab 13.12. > - [Deployed behind a feature flag](../../user/feature_flags.md), disabled by default. > - [Enabled by default](https://gitlab.com/gitlab-org/gitlab/-/issues/328538) in GitLab 13.12. -> - Enabled on GitLab.com. -> - Recommended for production use. -> - To disable in GitLab self-managed instances, ask a GitLab administrator to [disable it](#enable-or-disable-job-dependency-view). **(FREE SELF)** +> - [Feature flag removed](https://gitlab.com/gitlab-org/gitlab/-/issues/328538) in GitLab 14.2. This in-development feature might not be available for your use. There can be -[risks when enabling features still in development](../../user/feature_flags.md#risks-when-enabling-features-still-in-development). +[risks when enabling features still in development](../../administration/feature_flags.md#risks-when-enabling-features-still-in-development). Refer to this feature's version history for more details. You can arrange jobs in the pipeline graph based on their [`needs`](../yaml/index.md#needs) @@ -385,29 +389,11 @@ To see the full `needs` dependency tree for a job, hover over it: ![single job dependency tree highlighted](img/pipelines_graph_dependency_view_hover_v13_12.png) -#### Enable or disable job dependency view **(FREE SELF)** - -The job dependency view is deployed behind a feature flag that is **enabled by default**. -[GitLab administrators with access to the GitLab Rails console](../../administration/feature_flags.md) -can disable it. - -To enable it: - -```ruby -Feature.enable(:pipeline_graph_layers_view) -``` - -To disable it: - -```ruby -Feature.disable(:pipeline_graph_layers_view) -``` - ### 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: +be found when you go to: - The pipelines index page. - A single commit page. diff --git a/doc/ci/pipelines/job_artifacts.md b/doc/ci/pipelines/job_artifacts.md index b9a42c76293..c6b6f61ef11 100644 --- a/doc/ci/pipelines/job_artifacts.md +++ b/doc/ci/pipelines/job_artifacts.md @@ -100,8 +100,8 @@ artifacts and log. You must be: To delete a job: 1. Go to a job's detail page. -1. At the top right of the job's log, select the trash icon. -1. Confirm the deletion. +1. On the top right of the job's log, select **Erase job log** (**{remove}**). +1. On the confirmation dialog, select **OK**. ## Retrieve job artifacts for other projects @@ -186,7 +186,9 @@ Keeping the latest artifacts can use a large amount of storage space in projects with a lot of jobs or large artifacts. If the latest artifacts are not needed in a project, you can disable this behavior to save space: -1. Go to the project's **Settings > CI/CD > Artifacts**. +1. On the top bar, select **Menu > Projects** and find your project. +1. On the left sidebar, select **Settings > CI/CD**. +1. Expand **Artifacts**. 1. Clear the **Keep artifacts from most recent successful jobs** checkbox. You can disable this behavior for all projects on a self-managed instance in the diff --git a/doc/ci/pipelines/merge_request_pipelines.md b/doc/ci/pipelines/merge_request_pipelines.md index 29c12551f12..b3dfe8753c7 100644 --- a/doc/ci/pipelines/merge_request_pipelines.md +++ b/doc/ci/pipelines/merge_request_pipelines.md @@ -16,8 +16,8 @@ changes are pushed to a branch. If you want the pipeline to run jobs **only** on commits associated with a merge request, you can use *pipelines for merge requests*. -In the UI, these pipelines are labeled as `detached`. Otherwise, these pipelines are the same -as other pipelines. +These pipelines are labeled as `detached` in the UI, and they do not have access to [protected variables](../variables/index.md#protect-a-cicd-variable). +Otherwise, these pipelines are the same as other pipelines. Pipelines for merge requests can run when you: diff --git a/doc/ci/pipelines/merge_trains.md b/doc/ci/pipelines/merge_trains.md index 3e6ad071d7e..06c1a6fef44 100644 --- a/doc/ci/pipelines/merge_trains.md +++ b/doc/ci/pipelines/merge_trains.md @@ -6,12 +6,12 @@ type: reference last_update: 2019-07-03 --- -# Merge Trains **(PREMIUM)** +# Merge trains **(PREMIUM)** > - [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/9186) in [GitLab Premium](https://about.gitlab.com/pricing/) 12.0. > - [Squash and merge](../../user/project/merge_requests/squash_and_merge.md) support [introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/13001) in [GitLab Premium](https://about.gitlab.com/pricing/) 12.6. -For more information about why you might want to use Merge Trains, read [How merge trains keep your master green](https://about.gitlab.com/blog/2020/01/30/all-aboard-merge-trains/). +For more information about why you might want to use merge trains, read [How merge trains keep your master green](https://about.gitlab.com/blog/2020/01/30/all-aboard-merge-trains/). When [pipelines for merged results](pipelines_for_merged_results.md) are enabled, the pipeline jobs run as if the changes from your source branch have already @@ -63,7 +63,7 @@ Read more about [how merge trains keep your master green](https://about.gitlab.c <i class="fa fa-youtube-play youtube" aria-hidden="true"></i> Watch this video for a demonstration on [how parallel execution -of Merge Trains can prevent commits from breaking the default +of merge trains can prevent commits from breaking the default branch](https://www.youtube.com/watch?v=D4qCqXgZkHQ). ## Prerequisites @@ -83,11 +83,13 @@ To enable merge trains for your project: 1. If you are on a self-managed GitLab instance, ensure the [feature flag](#merge-trains-feature-flag) is set correctly. 1. [Configure your CI/CD configuration file](merge_request_pipelines.md#configure-pipelines-for-merge-requests) so that the pipeline or individual jobs run for merge requests. -1. Visit your project's **Settings > General** and expand **Merge requests**. +1. On the top bar, select **Menu > Projects** and find your project. +1. On the left sidebar, select **Settings > General**. +1. Expand **Merge requests**. 1. In the **Merge method** section, verify that **Merge commit** is selected. You cannot use **Merge commit with semi-linear history** or **Fast-forward merge** with merge trains. -1. In the **Merge options** section, select **Enable merged results pipelines.** (if not already selected) and **Enable merge trains.** -1. Click **Save changes** +1. In the **Merge options** section, select **Enable merged results pipelines** (if not already selected) and **Enable merge trains**. +1. Select **Save changes**. In GitLab 13.5 and earlier, there is only one checkbox, named **Enable merge trains and pipelines for merged results**. @@ -102,7 +104,7 @@ unresolved state or your pipelines may be dropped. To start a merge train: 1. Visit a merge request. -1. Click the **Start merge train** button. +1. Select **Start merge train**. ![Start merge train](img/merge_train_start_v12_0.png) @@ -113,7 +115,7 @@ Other merge requests can now be added to the train. To add a merge request to a merge train: 1. Visit a merge request. -1. Click the **Add to merge train** button. +1. Select **Add to merge train**. If pipelines are already running for the merge request, you cannot add the merge request to the train. Instead, you can schedule to add the merge request to a merge train **when the latest @@ -124,7 +126,7 @@ pipeline succeeds**. ## Remove a merge request from a merge train 1. Visit a merge request. -1. Click the **Remove from merge train** button. +1. Select **Remove from merge train**. ![Cancel merge train](img/merge_train_cancel_v12_0.png) @@ -153,31 +155,32 @@ is recreated and all pipelines restart. ### Merge request dropped from the merge train immediately -If a merge request is not mergeable (for example, it's a draft merge request, there is a merge -conflict, etc.), your merge request is dropped from the merge train automatically. +If a merge request is not mergeable (for example, it's a draft merge request or it has a merge +conflict), the merge train drops your merge request automatically. In these cases, the reason for dropping the merge request is in the **system notes**. To check the reason: 1. Open the merge request that was dropped from the merge train. -1. Open the **Discussion** tab. +1. Select the **Discussion** tab. 1. Find a system note that includes either: - - The text **... removed this merge request from the merge train because ...** + - **... removed this merge request from the merge train because ...** - **... aborted this merge request from the merge train because ...** - The reason is given in the text after the **because ...** phrase. -![Merge Train Failure](img/merge_train_failure.png) +The reason is given in the text after the **because ...** phrase. + +![Merge train failure](img/merge_train_failure.png) ### Merge When Pipeline Succeeds cannot be chosen [Merge When Pipeline Succeeds](../../user/project/merge_requests/merge_when_pipeline_succeeds.md) -is currently unavailable when Merge Trains are enabled. +is currently unavailable when merge trains are enabled. See [the related issue](https://gitlab.com/gitlab-org/gitlab/-/issues/12267) for more information. -### Merge Train Pipeline cannot be retried +### Merge train pipeline cannot be retried When a pipeline for merge trains fails the merge request is dropped from the train and the pipeline can't be retried. Pipelines for merge trains run on the merged result of the changes in the merge request and @@ -189,7 +192,7 @@ again, which triggers a new pipeline. ### Unable to add to merge train with message "The pipeline for this merge request failed." -Sometimes the **Start/Add to Merge Train** button is not available and the merge request says, +Sometimes the **Start/Add to merge train** button is not available and the merge request says, "The pipeline for this merge request failed. Please retry the job or push a new commit to fix the failure." This issue occurs when [**Pipelines must succeed**](../../user/project/merge_requests/merge_when_pipeline_succeeds.md#only-allow-merge-requests-to-be-merged-if-the-pipeline-succeeds) @@ -197,19 +200,19 @@ is enabled in **Settings > General > Merge requests**. This option requires that run a new successful pipeline before you can re-add a merge request to a merge train. Merge trains ensure that each pipeline has succeeded before a merge happens, so -you can clear the **Pipelines must succeed** check box and keep -**Enable merge trains and pipelines for merged results** (merge trains) enabled. +you can clear the **Pipelines must succeed** checkbox and keep +**Enable merge trains and pipelines for merged results** (merge trains) selected. -If you want to keep the **Pipelines must succeed** option enabled along with Merge -Trains, create a new pipeline for merged results when this error occurs: +If you want to keep the **Pipelines must succeed** option selected along with merge +trains, create a new pipeline for merged results when this error occurs: -1. Go to the **Pipelines** tab and click **Run pipeline**. -1. Click **Start/Add to merge train when pipeline succeeds**. +1. On the **Pipelines** tab, select **Run pipeline**. +1. Select **Start/Add to merge train when pipeline succeeds**. See [the related issue](https://gitlab.com/gitlab-org/gitlab/-/issues/35135) for more information. -### Merge Trains feature flag **(PREMIUM SELF)** +### Merge trains feature flag **(PREMIUM SELF)** In [GitLab 13.6 and later](https://gitlab.com/gitlab-org/gitlab/-/issues/244831), you can [enable or disable merge trains in the project settings](#enable-merge-trains). @@ -227,7 +230,7 @@ Feature.enable(:disable_merge_trains) ``` After you enable this feature flag, all existing merge trains are cancelled and -the **Start/Add to Merge Train** button no longer appears in merge requests. +the **Start/Add to merge train** button no longer appears in merge requests. To disable the feature flag, and enable merge trains again: diff --git a/doc/ci/pipelines/multi_project_pipelines.md b/doc/ci/pipelines/multi_project_pipelines.md index e3fe0fd20f5..3007d91d1b4 100644 --- a/doc/ci/pipelines/multi_project_pipelines.md +++ b/doc/ci/pipelines/multi_project_pipelines.md @@ -304,8 +304,8 @@ Prerequisites: To trigger the pipeline when the upstream project is rebuilt: 1. On the top bar, select **Menu > Projects** and find your project. -1. On the left sidebar, select **Settings > CI/CD** page. -1. Expand the **Pipeline subscriptions** section. +1. On the left sidebar, select **Settings > CI/CD**. +1. Expand **Pipeline subscriptions**. 1. Enter the project you want to subscribe to, in the format `<namespace>/<project>`. For example, if the project is `https://gitlab.com/gitlab-org/gitlab`, use `gitlab-org/gitlab`. 1. Select **Subscribe**. diff --git a/doc/ci/pipelines/parent_child_pipelines.md b/doc/ci/pipelines/parent_child_pipelines.md index 2e29f4fe812..b266a721d11 100644 --- a/doc/ci/pipelines/parent_child_pipelines.md +++ b/doc/ci/pipelines/parent_child_pipelines.md @@ -157,9 +157,13 @@ build a matrix of targets and architectures. For an overview, see [Create child pipelines using dynamically generated configurations](https://youtu.be/nMdfus2JWHM). <!-- vale gitlab.Spelling = NO --> + We also have an example project using [Dynamic Child Pipelines with Jsonnet](https://gitlab.com/gitlab-org/project-templates/jsonnet) -which shows how to use a data templating language to generate your `.gitlab-ci.yml` at runtime. You could use a similar process for other templating languages like [Dhall](https://dhall-lang.org/) or [`ytt`](https://get-ytt.io/). +which shows how to use a data templating language to generate your `.gitlab-ci.yml` at runtime. +You could use a similar process for other templating languages like +[Dhall](https://dhall-lang.org/) or [`ytt`](https://get-ytt.io/). + <!-- vale gitlab.Spelling = NO --> The artifact path is parsed by GitLab, not the runner, so the path must match the diff --git a/doc/ci/pipelines/pipelines_for_merged_results.md b/doc/ci/pipelines/pipelines_for_merged_results.md index efa6a373ef3..08d7d119787 100644 --- a/doc/ci/pipelines/pipelines_for_merged_results.md +++ b/doc/ci/pipelines/pipelines_for_merged_results.md @@ -64,7 +64,7 @@ To enable pipelines for merged results for your project: 1. Click **Save changes**. WARNING: -If you select the check box but don't configure your CI/CD to use +If you select the checkbox but don't configure your CI/CD to use pipelines for merge requests, your merge requests may become stuck in an unresolved state or your pipelines may be dropped. diff --git a/doc/ci/pipelines/settings.md b/doc/ci/pipelines/settings.md index db6fa7f4d23..b48c62dccc5 100644 --- a/doc/ci/pipelines/settings.md +++ b/doc/ci/pipelines/settings.md @@ -122,8 +122,13 @@ If the CI/CD configuration file is on an external site, the URL must end with `. - `http://example.com/generate/ci/config.yml` -If the CI/CD configuration file is in a different project, the path must be relative -to the root directory in the other project. Include the group and project name at the end: +If the CI/CD configuration file is in a different project: + +- The file must exist on its default branch. +- The path must be relative to the root directory in the other project. +- The path must include the group and project name at the end. + +For example: - `.gitlab-ci.yml@mygroup/another-project` - `my/path/.my-custom-file.yml@mygroup/another-project` @@ -228,6 +233,7 @@ Use this regex for commonly used test tools. - `go test -cover` (Go). Example: `coverage: \d+.\d+% of statements`. - .NET (OpenCover). Example: `(Visited Points).*\((.*)\)`. - .NET (`dotnet test` line coverage). Example: `Total\s*\|\s*(\d+(?:\.\d+)?)`. +- tarpaulin (Rust). Example: `^\d+.\d+% coverage`. <!-- vale gitlab.Spelling = YES --> @@ -260,6 +266,7 @@ when merging a merge request would cause the project's test coverage to decline. Follow these steps to enable the `Coverage-Check` MR approval rule: +1. Set up a [`coverage:`](../yaml/index.md#coverage) regular expression for all jobs you want to include in the overall coverage value. 1. Go to your project and select **Settings > General**. 1. Expand **Merge request approvals**. 1. Select **Enable** next to the `Coverage-Check` approval rule. |