diff options
Diffstat (limited to 'doc/ci/pipelines')
| -rw-r--r-- | doc/ci/pipelines/cicd_minutes.md | 36 | ||||
| -rw-r--r-- | doc/ci/pipelines/img/downstream_pipeline_actions.png | bin | 0 -> 13406 bytes | |||
| -rw-r--r-- | doc/ci/pipelines/img/multi_pipeline_mini_graph.gif | bin | 11466 -> 0 bytes | |||
| -rw-r--r-- | doc/ci/pipelines/index.md | 16 | ||||
| -rw-r--r-- | doc/ci/pipelines/merge_request_pipelines.md | 22 | ||||
| -rw-r--r-- | doc/ci/pipelines/merge_trains.md | 6 | ||||
| -rw-r--r-- | doc/ci/pipelines/merged_results_pipelines.md | 5 | ||||
| -rw-r--r-- | doc/ci/pipelines/multi_project_pipelines.md | 9 | ||||
| -rw-r--r-- | doc/ci/pipelines/parent_child_pipelines.md | 7 | ||||
| -rw-r--r-- | doc/ci/pipelines/pipeline_artifacts.md | 2 | ||||
| -rw-r--r-- | doc/ci/pipelines/settings.md | 56 |
11 files changed, 116 insertions, 43 deletions
diff --git a/doc/ci/pipelines/cicd_minutes.md b/doc/ci/pipelines/cicd_minutes.md index f9d9a4f738b..2b18b1d353b 100644 --- a/doc/ci/pipelines/cicd_minutes.md +++ b/doc/ci/pipelines/cicd_minutes.md @@ -90,6 +90,8 @@ To view CI/CD minutes being used for your group: ## View CI/CD minutes used by a personal namespace +> Displaying shared runners duration [introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/345795) in GitLab 15.0. + You can view the number of CI/CD minutes being used by a personal namespace: 1. On the top bar, in the top right corner, select your avatar. @@ -103,7 +105,7 @@ These additional CI/CD minutes: - Are used only after the monthly quota included in your subscription runs out. - Are carried over to the next month, if any remain at the end of the month. -- Don't expire. +- Are valid for 12 months from date of purchase or until all minutes are consumed, whichever comes first. Expiry of minutes is not currently enforced. If you use more CI/CD minutes than your monthly quota, when you purchase more, those CI/CD minutes are deducted from your quota. For example, with a GitLab SaaS @@ -191,17 +193,41 @@ The cost factor for a job running on a shared runner is: ### Additional costs on GitLab SaaS -On GitLab SaaS, shared runners can have different cost factors depending on the cost involved -in executing the runner. For example, a high spec shared runner could be set to have a cost factor of `2`. -Conversely, a shared runner that executes jobs for public projects could have a low cost factor, like `0.008`. +GitLab SaaS shared runners have different cost factors, depending on the runner type (Linux, Windows, macOS) and the virtual machine configuration. + +| GitLab SaaS runner type | Virtual machine configuration | CI/CD minutes cost factor | +| :--------- | :------------------- | :--------- | +| Linux OS + Docker executor| 1 vCPU, 3.75 GB RAM |1| +| macOS + shell executor | 4 vCPU, 10 GB RAM| 6 | ### Monthly reset of CI/CD minutes On the first day of each calendar month, the accumulated usage of CI/CD minutes is reset to `0` -for all namespaces that use shared runners. +for all namespaces that use shared runners. This means your full quota is available, and +calculations start again from `0`. + +For example, if you have a monthly quota of `10,000` CI/CD minutes: + +- On **1st April**, you have `10,000` minutes. +- During April, you use only `6,000` of the `10,000` minutes. +- On **1st May**, the accumulated usage of minutes resets to `0`, and you have `10,000` minutes to use again + during May. Usage data for the previous month is kept to show historical view of the consumption over time. +### Monthly rollover of purchased CI/CD minutes + +If you purchase additional CI/CD minutes and don't use the full amount, the remaining amount rolls over to +the next month. + +For example: + +- On **1st April**, you purchase `5,000` CI/CD minutes. +- During April, you use only `3,000` of the `5,000` minutes. +- On **1st May**, the remaining `2,000` minutes roll over and are added to your monthly quota. + +Additional CI/CD minutes are a one-time purchase and do not renew or refresh each month. + ## What happens when you exceed the quota When the quota of CI/CD minutes is used for the current month, GitLab stops diff --git a/doc/ci/pipelines/img/downstream_pipeline_actions.png b/doc/ci/pipelines/img/downstream_pipeline_actions.png Binary files differnew file mode 100644 index 00000000000..4c4384bab57 --- /dev/null +++ b/doc/ci/pipelines/img/downstream_pipeline_actions.png diff --git a/doc/ci/pipelines/img/multi_pipeline_mini_graph.gif b/doc/ci/pipelines/img/multi_pipeline_mini_graph.gif Binary files differdeleted file mode 100644 index de49ba5aa12..00000000000 --- a/doc/ci/pipelines/img/multi_pipeline_mini_graph.gif +++ /dev/null diff --git a/doc/ci/pipelines/index.md b/doc/ci/pipelines/index.md index 4d1af735b13..c6142ebefc5 100644 --- a/doc/ci/pipelines/index.md +++ b/doc/ci/pipelines/index.md @@ -449,6 +449,22 @@ Pipeline analytics are available on the [**CI/CD Analytics** page](../../user/an 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). +### Downstream pipelines + +> Cancel or retry downstream pipelines from the graph view [introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/354974) in GitLab 15.0 [with a flag](../../administration/feature_flags.md) named `downstream_retry_action`. Disabled by default. + +In the pipeline graph view, downstream pipelines ([Multi-project pipelines](multi_project_pipelines.md) +and [Parent-child pipelines](parent_child_pipelines.md)) display as a list of cards +on the right of the graph. + +To cancel a downstream pipeline that is still running, select **Cancel** (**{cancel}**) +on the pipeline's card. + +To retry a failed downstream pipeline, select **Retry** (**{retry}**) +on the pipeline's card. + + + ## Pipelines API GitLab provides API endpoints to: diff --git a/doc/ci/pipelines/merge_request_pipelines.md b/doc/ci/pipelines/merge_request_pipelines.md index 75408de2721..89839de718b 100644 --- a/doc/ci/pipelines/merge_request_pipelines.md +++ b/doc/ci/pipelines/merge_request_pipelines.md @@ -20,7 +20,7 @@ Branch pipelines: - Run when you push a new commit to a branch. - Are the default type of pipeline. - Have access to [some predefined variables](../variables/predefined_variables.md). -- Have access to [protected variables](../variables/index.md#protect-a-cicd-variable) and [protected runners](../runners/configure_runners.md#prevent-runners-from-revealing-sensitive-information). +- Have access to [protected variables](../variables/index.md#protected-cicd-variables) and [protected runners](../runners/configure_runners.md#prevent-runners-from-revealing-sensitive-information). Merge request pipelines: @@ -33,7 +33,7 @@ Merge request pipelines: - Do not run by default. The jobs in the CI/CD configuration file [must be configured](#prerequisites) to run in merge request pipelines. - Have access to [more predefined variables](#available-predefined-variables). -- Do not have access to [protected variables](../variables/index.md#protect-a-cicd-variable) or [protected runners](../runners/configure_runners.md#prevent-runners-from-revealing-sensitive-information). +- Do not have access to [protected variables](../variables/index.md#protected-cicd-variables) or [protected runners](../runners/configure_runners.md#prevent-runners-from-revealing-sensitive-information). Both of these types of pipelines can appear on the **Pipelines** tab of a merge request. @@ -127,12 +127,12 @@ Pipelines for forks display with the **fork** badge in the parent project: ### Run pipelines in the parent project **(PREMIUM)** -Project members in the parent project can choose to run a merge request pipeline +Project members in the parent project can trigger a merge request pipeline for a merge request submitted from a fork project. This pipeline: - Is created and runs in the parent (target) project, not the fork (source) project. -- Uses the CI/CD configuration present in the fork project's branch -- Uses the parent project's CI/CD configuration, resources, and project CI/CD variables. +- Uses the CI/CD configuration present in the fork project's branch. +- Uses the parent project's CI/CD settings, resources, and project CI/CD variables. - Uses the permissions of the parent project member that triggers the pipeline. Run pipelines in fork project MRs to ensure that the post-merge pipeline passes in @@ -142,8 +142,12 @@ running the pipeline in the parent project uses the parent project's trusted run WARNING: Fork merge requests can contain malicious code that tries to steal secrets in the parent project when the pipeline runs, even before merge. As a reviewer, carefully -check the changes in the merge request before triggering the pipeline. GitLab shows -a warning that you must accept before you can trigger the pipeline. +check the changes in the merge request before triggering the pipeline. If you trigger +the pipeline by selecting **Run pipeline** or applying a suggestion, GitLab shows +a warning that you must accept before the pipeline runs. If you trigger the pipeline +by using any other method, including the API, [`/rebase` quick action](../../user/project/quick_actions.md#issues-merge-requests-and-epics), +or [**Rebase** option](../../user/project/merge_requests/methods/index.md#rebasing-in-semi-linear-merge-methods), +**no warning displays**. Prerequisites: @@ -152,10 +156,10 @@ Prerequisites: user running the pipeline. Otherwise, the **Pipelines** tab does not display in the merge request. -To run a pipeline in the parent project for a merge request from a fork project: +To use the UI to run a pipeline in the parent project for a merge request from a fork project: 1. In the merge request, go to the **Pipelines** tab. -1. Select **Run pipeline**. You must accept the warning, or the pipeline does not run. +1. Select **Run pipeline**. You must read and accept the warning, or the pipeline does not run. ## Available predefined variables diff --git a/doc/ci/pipelines/merge_trains.md b/doc/ci/pipelines/merge_trains.md index 12ea3a70536..d200dde143c 100644 --- a/doc/ci/pipelines/merge_trains.md +++ b/doc/ci/pipelines/merge_trains.md @@ -24,7 +24,7 @@ requests, each waiting to be merged into the target branch. Many merge requests can be added to the train. Each merge request runs its own merged results pipeline, which includes the changes from all of the other merge requests in *front* of it on the train. -All the pipelines run in parallel, to save time. +All the pipelines run in parallel, to save time. The author of the internal merged result commit is always the user that initiated the merge. If the pipeline for a merge request fails, the breaking changes are not merged, and the target branch is unaffected. The merge request is removed from the train, and all pipelines behind it restart. @@ -73,6 +73,9 @@ To enable merge trains: - Your repository must be a GitLab repository, not an [external repository](../ci_cd_for_external_repos/index.md). +Merge trains do not work with [Semi-linear history merge requests](../../user/project/merge_requests/methods/index.md#merge-commit-with-semi-linear-history) +or [fast-forward merge requests](../../user/project/merge_requests/methods/index.md#fast-forward-merge). + ## Enable merge trains To enable merge trains for your project: @@ -84,7 +87,6 @@ To enable merge trains for 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. Select **Save changes**. diff --git a/doc/ci/pipelines/merged_results_pipelines.md b/doc/ci/pipelines/merged_results_pipelines.md index 7df9ea3f72f..9661d2f5263 100644 --- a/doc/ci/pipelines/merged_results_pipelines.md +++ b/doc/ci/pipelines/merged_results_pipelines.md @@ -12,7 +12,8 @@ A *merged results pipeline* is a type of [merge request pipeline](merge_request_ GitLab creates an internal commit with the merged results, so the pipeline can run against it. This commit does not exist in either branch, -but you can view it in the pipeline details. +but you can view it in the pipeline details. The author of the internal commit is +always the user that created the merge request. The pipeline runs against the target branch as it exists at the moment you run the pipeline. Over time, while you're working in the source branch, the target branch might change. @@ -35,7 +36,7 @@ To use merged results pipelines: - Your repository must be a GitLab repository, not an [external repository](../ci_cd_for_external_repos/index.md). - You must not be using [fast forward merges](../../user/project/merge_requests/fast_forward_merge.md). - [An issue exits](https://gitlab.com/gitlab-org/gitlab/-/issues/26996) to change this behavior. + [An issue exists](https://gitlab.com/gitlab-org/gitlab/-/issues/26996) to change this behavior. ## Enable merged results pipelines diff --git a/doc/ci/pipelines/multi_project_pipelines.md b/doc/ci/pipelines/multi_project_pipelines.md index e6af9292fe1..20184635e4a 100644 --- a/doc/ci/pipelines/multi_project_pipelines.md +++ b/doc/ci/pipelines/multi_project_pipelines.md @@ -308,7 +308,10 @@ When you configure GitLab CI/CD for your project, you can visualize the stages o  -In the merge request, on the **Pipelines** tab, multi-project pipeline mini-graphs are displayed. -They expand and are shown adjacent to each other when hovering (or tapping on touchscreen devices). +## Retry or cancel multi-project pipelines - +If you have permission to trigger pipelines in the downstream project, you can +retry or cancel multi-project pipelines: + +- [In the main graph view](index.md#downstream-pipelines). +- From the downstream pipeline's details page. diff --git a/doc/ci/pipelines/parent_child_pipelines.md b/doc/ci/pipelines/parent_child_pipelines.md index a3ded24e8c9..3206345d757 100644 --- a/doc/ci/pipelines/parent_child_pipelines.md +++ b/doc/ci/pipelines/parent_child_pipelines.md @@ -216,3 +216,10 @@ multi-project pipelines: - [By using the `variable` keyword](multi_project_pipelines.md#pass-cicd-variables-to-a-downstream-pipeline-by-using-the-variables-keyword). - [By using variable inheritance](multi_project_pipelines.md#pass-cicd-variables-to-a-downstream-pipeline-by-using-variable-inheritance). + +## Retry or cancel child pipelines + +You can retry or cancel child pipelines: + +- [In the main graph view](index.md#downstream-pipelines). +- In the child pipeline's details page. diff --git a/doc/ci/pipelines/pipeline_artifacts.md b/doc/ci/pipelines/pipeline_artifacts.md index e9dd1b2a942..3a1367f4a8c 100644 --- a/doc/ci/pipelines/pipeline_artifacts.md +++ b/doc/ci/pipelines/pipeline_artifacts.md @@ -11,7 +11,7 @@ different to [job artifacts](job_artifacts.md) because they are not explicitly m `.gitlab-ci.yml` definitions. Pipeline artifacts are used by the [test coverage visualization feature](../../user/project/merge_requests/test_coverage_visualization.md) -to collect coverage information. It uses the [`artifacts: reports`](../yaml/index.md#artifactsreports) CI/CD keyword. +to collect coverage information. ## Storage diff --git a/doc/ci/pipelines/settings.md b/doc/ci/pipelines/settings.md index b6ea16ae224..2a95a4e1421 100644 --- a/doc/ci/pipelines/settings.md +++ b/doc/ci/pipelines/settings.md @@ -222,36 +222,49 @@ averaged. To add test coverage results to a merge request using the project's `.gitlab-ci.yml` file, provide a regular expression using the [`coverage`](../yaml/index.md#coverage) keyword. -Setting the regular expression this way takes precedence over project settings. +<!-- start_remove The following content will be removed on remove_date: '2023-08-22' --> -### Add test coverage results using project settings (DEPRECATED) +### Add test coverage results using project settings (removed) -> [Deprecated](https://gitlab.com/gitlab-org/gitlab/-/issues/17633) in GitLab 14.9. Replaced by [`coverage` keyword](../yaml/index.md#coverage). +> [Deprecated](https://gitlab.com/gitlab-org/gitlab/-/issues/17633) in GitLab 14.8. Replaced by [`coverage` keyword](../yaml/index.md#coverage). +> [Removed](https://gitlab.com/gitlab-org/gitlab/-/issues/17633) in GitLab 15.0. -WARNING: -This feature is in its end-of-life process. It is [deprecated](https://gitlab.com/gitlab-org/gitlab/-/issues/17633) -in GitLab 14.9, and is planned for [removal](https://gitlab.com/gitlab-org/gitlab/-/issues/17633) in GitLab 15.0. +This feature is in its end-of-life process. It was [deprecated](https://gitlab.com/gitlab-org/gitlab/-/issues/17633) +in GitLab 14.8. The feature is [removed](https://gitlab.com/gitlab-org/gitlab/-/issues/17633) in GitLab 15.0. -You can add test coverage results to merge requests using the Project's CI/CD settings: +To migrate from a project setting to the `coverage` keyword, add the [former project setting](#locate-former-project-setting) +to a CI/CD job. For example: -- Set using the GitLab UI: +- A Go test coverage project setting: `coverage: \d+.\d+% of statements`. +- A CI/CD job with `coverage` keyword setting: - 1. On the top bar, select **Menu > Projects** and find your project. - 1. On the left sidebar, select **Settings > CI/CD**. - 1. Expand **General pipelines**. - 1. In the **Test coverage parsing** field, enter a regular expression. Leave blank to disable this feature. + ```yaml + unit-test: + stage: test + coverage: '/coverage: \d+.\d+% of statements/' + script: + - go test -cover + ``` -- Set when [editing a project](../../api/projects.md#edit-project) or [creating a project](../../api/projects.md#create-project) - using the GitLab API with the `build_coverage_regex` attribute: +The `.gitlab-ci.yml` job [`coverage`](../yaml/index.md#coverage) keyword must be: - ```shell - curl --request PUT --header "PRIVATE-TOKEN: <your-token>" \ - --url 'https://gitlab.com/api/v4/projects/<your-project-ID>' \ - --data "build_coverage_regex=<your-regular-expression>" - ``` +- A regular expression starts and ends with the `/` character. +- Defined as single-quoted string. + +You can verify correct syntax using the [pipeline editor](../pipeline_editor/index.md). + +#### Locate former project setting + +To migrate from the project coverage setting to the `coverage` keyword, use the +regular expression displayed in the settings. Available in GitLab 14.10 and earlier: + +1. On the top bar, select **Menu > Projects** and find your project. +1. On the left sidebar, select **Settings > CI/CD**. +1. Expand **General pipelines**. + +The regular expression you need is in the **Test coverage parsing** field. -You can use <https://rubular.com> to test your regular expression. The regular expression returns the **last** -match found in the output. +<!-- end_remove --> ### Test coverage examples @@ -266,6 +279,7 @@ Use this regex for commonly used test tools. - gcovr (C/C++). Example: `^TOTAL.*\s+(\d+\%)$`. - `tap --coverage-report=text-summary` (NodeJS). Example: `^Statements\s*:\s*([^%]+)`. - `nyc npm test` (NodeJS). Example: `All files[^|]*\|[^|]*\s+([\d\.]+)`. +- `jest --ci --coverage` (NodeJS). Example: `All files[^|]*\|[^|]*\s+([\d\.]+)`. - excoveralls (Elixir). Example: `\[TOTAL\]\s+(\d+\.\d+)%`. - `mix test --cover` (Elixir). Example: `\d+.\d+\%\s+\|\s+Total`. - JaCoCo (Java/Kotlin). Example: `Total.*?([0-9]{1,3})%`. |
