diff options
Diffstat (limited to 'doc/ci/pipelines')
24 files changed, 150 insertions, 698 deletions
diff --git a/doc/ci/pipelines/cicd_minutes.md b/doc/ci/pipelines/cicd_minutes.md index 4cbaa77b029..ee3f0d8c539 100644 --- a/doc/ci/pipelines/cicd_minutes.md +++ b/doc/ci/pipelines/cicd_minutes.md @@ -7,6 +7,9 @@ type: reference # CI/CD minutes quota **(PREMIUM)** +NOTE: +The term `CI/CD minutes` is being renamed to `units of compute`. During this transition, you might see references in the UI and documentation to `CI/CD minutes`, `CI minutes`, `pipeline minutes`, `CI pipeline minutes`, `pipeline minutes quota`, and `units of compute`. For more information, see [epic 2150](https://gitlab.com/groups/gitlab-com/-/epics/2150). + Administrators can limit the amount of time that projects can use to run jobs on [shared runners](../runners/runners_scope.md#shared-runners) each month. This limit is tracked with a quota of CI/CD minutes. @@ -19,7 +22,7 @@ end-to-end duration of a pipeline. On GitLab.com: -- CI/CD minutes quotas are enabled for both public and private projects, but public +- CI/CD minutes quotas are enabled for all projects, but certain projects [consume CI/CD minutes at a slower rate](#cost-factor). - The base monthly CI/CD minutes quota for a GitLab.com [namespace](../../user/namespace/index.md) is determined by its [license tier](https://about.gitlab.com/pricing/). @@ -83,11 +86,16 @@ NOTE: You can set a quota of CI/CD minutes for only top-level groups or user namespaces. If you set a quota for a subgroup, it is not used. -## View CI/CD minutes used by a group +## View CI/CD minutes -> Displaying shared runners duration per project [introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/355666) in GitLab 15.0. +Prerequisite: -You can view the number of CI/CD minutes being used by a group. +- You must have access to the build to view the total usage and quota summary for a namespace associated with a build. +- Access to **Usage Quotas** page is based on your role in the associated namespace or group. + +### View Usage Quota Reports for a group + +> Displaying shared runners duration per project [introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/355666) in GitLab 15.0. Prerequisite: @@ -105,10 +113,14 @@ The projects list shows projects with CI/CD minute usage or shared runners usage in the current month only. The list includes all projects in the namespace and its subgroups, sorted in descending order of CI/CD minute usage. -## View CI/CD minutes used by a personal namespace +### View Usage Quota reports for a personal namespace > Displaying shared runners duration [introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/345795) in GitLab 15.0. +Prerequisite: + +- The namespace must be your personal namespace. + You can view the number of CI/CD minutes being used by a personal namespace: 1. On the top bar, in the upper-right corner, select your avatar. @@ -144,6 +156,10 @@ You can find pricing for additional CI/CD minutes on the ### Purchase CI/CD minutes for a group **(FREE SAAS)** +Prerequisite: + +- You must have the Owner role for the group. + You can purchase additional CI/CD minutes for your group. You cannot transfer purchased CI/CD minutes from one group to another, so be sure to select the correct group. @@ -159,6 +175,10 @@ namespace. ### Purchase CI/CD minutes for a personal namespace **(FREE SAAS)** +Prerequisite: + +- The namespace must be your personal namespace. + To purchase additional minutes for your personal namespace: 1. On the top bar, in the upper-right corner, select your avatar. @@ -201,13 +221,12 @@ can be higher than the end-to-end duration of a pipeline. The cost factors for jobs running on shared runners on GitLab.com are: -- `1` for internal and private projects. -- `0.5` for public projects in the [GitLab for Open Source program](../../subscriptions/index.md#gitlab-for-open-source). -- `0.008` for public forks of public projects in the [GitLab for Open Source program](../../subscriptions/index.md#gitlab-for-open-source). For every 125 minutes of job execution time, +- `1` for internal, public, and private projects. +- Exceptions for public projects: + - `0.5` for projects in the [GitLab for Open Source program](../../subscriptions/community_programs.md#gitlab-for-open-source). + - `0.008` for forks of projects in the [GitLab for Open Source program](../../subscriptions/community_programs.md#gitlab-for-open-source). For every 125 minutes of job execution time, you use 1 CI/CD minute. -- `1` for other public projects, after October 1, 2022 (previously `0.04`). - For every 1 minute of job execution time, you use 1 CI/CD minute. -- Calculated differently for [community contributions to GitLab projects](#cost-factor-for-community-contributions-to-gitlab-projects). +- Discounted dynamically for [community contributions to GitLab projects](#cost-factor-for-community-contributions-to-gitlab-projects). The cost factors on self-managed instances are: @@ -244,9 +263,10 @@ GitLab SaaS runners have different cost factors, depending on the runner type (L | GitLab SaaS runner type | Machine Type | CI/CD minutes cost factor | | :--------- | :------------------- | :--------- | -| Linux OS + Docker executor| Small |1| -| Linux OS + Docker executor| Medium |2| -| Linux OS + Docker executor| Large |3| +| Linux OS | Small |1| +| Linux OS | Medium |2| +| Linux OS | Large |3| +| Linux OS + GPU-enabled | Medium, GPU Standard |7| ### Monthly reset of CI/CD minutes @@ -298,6 +318,13 @@ On GitLab SaaS an email notification is sent to the namespace owners when: - The available CI/CD minutes are below 5% of the quota. - All CI/CD minutes have been used. +### Special quota limits + +In some cases, the quota limit is replaced by one of the following labels: + +- **Unlimited minutes**: For namespaces with unlimited CI/CD minutes +- **Not supported minutes**: For namespaces where active shared runners are not enabled + ## Reduce consumption of CI/CD minutes If your project consumes too many CI/CD minutes, there are some strategies you can @@ -319,3 +346,19 @@ If you manage an open source project, these improvements can also reduce CI/CD m consumption for contributor fork projects, enabling more contributions. See our [pipeline efficiency guide](pipeline_efficiency.md) for more details. + +## Reset CI/CD minutes used **(PREMIUM SELF)** + +An administrator can reset the number of minutes used by a namespace for the current month. + +### Reset minutes for a personal namespace + +1. Find the [user in the admin area](../../user/admin_area/index.md#administering-users). +1. Select **Edit**. +1. In **Limits**, select **Reset pipeline minutes**. + +### Reset minutes for a group namespace + +1. Find the [group in the admin area](../../user/admin_area/index.md#administering-groups). +1. Select **Edit**. +1. In **Permissions and group features**, select **Reset pipeline minutes**. diff --git a/doc/ci/pipelines/downstream_pipelines.md b/doc/ci/pipelines/downstream_pipelines.md index e4560cd882d..ffcfee98f05 100644 --- a/doc/ci/pipelines/downstream_pipelines.md +++ b/doc/ci/pipelines/downstream_pipelines.md @@ -231,37 +231,43 @@ configuration for jobs that use the Windows runner, like scripts, use <code>\ ### Run child pipelines with merge request pipelines -To trigger a child pipeline as a [merge request pipeline](merge_request_pipelines.md): +Pipelines, including child pipelines, run as branch pipelines by default when not using +[`rules`](../yaml/index.md#rules) or [`workflow:rules`](../yaml/index.md#workflowrules). +To configure child pipelines to run when triggered from a [merge request (parent) pipeline](merge_request_pipelines.md), use `rules` or `workflow:rules`. +For example, using `rules`: -1. Set the trigger job to run on merge requests in the parent pipeline's configuration file: +1. Set the parent pipeline's trigger job to run on merge requests: ```yaml - microservice_a: + trigger-child-pipeline-job: trigger: - include: path/to/microservice_a.yml + include: path/to/child-pipeline-configuration.yml rules: - if: $CI_PIPELINE_SOURCE == "merge_request_event" ``` -1. Configure the child pipeline jobs to run in merge request pipelines with [`rules`](../yaml/index.md#rules) - or [`workflow:rules`](../yaml/index.md#workflowrules). - For example, with `rules` in a child pipeline's configuration file: +1. Use `rules` to configure the child pipeline jobs to run when triggered by the parent pipeline: ```yaml job1: - script: echo "Child pipeline job 1" + script: echo "This child pipeline job runs any time the parent pipeline triggers it." rules: - - if: $CI_MERGE_REQUEST_ID + - if: $CI_PIPELINE_SOURCE == "parent_pipeline" job2: - script: echo "Child pipeline job 2" + script: echo "This child pipeline job runs only when the parent pipeline is a merge request pipeline" rules: - if: $CI_MERGE_REQUEST_ID ``` - In child pipelines, `$CI_PIPELINE_SOURCE` always has a value of `parent_pipeline` - and cannot be used to identify merge request pipelines. Use `$CI_MERGE_REQUEST_ID` - instead, which is always present in merge request pipelines. +In child pipelines, `$CI_PIPELINE_SOURCE` always has a value of `parent_pipeline`, so: + +- You can use `if: $CI_PIPELINE_SOURCE == "parent_pipeline"` to ensure child pipeline jobs always run. +- You _can't_ use `if: $CI_PIPELINE_SOURCE == "merge_request_event"` to configure child pipeline + jobs to run for merge request pipelines. Instead, use `if: $CI_MERGE_REQUEST_ID` + to set child pipeline jobs to run only when the parent pipeline is a merge request pipeline. The parent pipeline's + [`CI_MERGE_REQUEST_*` predefined variables](../variables/predefined_variables.md#predefined-variables-for-merge-request-pipelines) + are passed to the child pipeline jobs. ### Specify a branch for multi-project pipelines @@ -281,7 +287,7 @@ Use: - The `project` keyword to specify the full path to the downstream project. In [GitLab 15.3 and later](https://gitlab.com/gitlab-org/gitlab/-/issues/367660), you can use [variable expansion](../variables/where_variables_can_be_used.md#gitlab-ciyml-file). -- The `branch` keyword to specify the name of a branch or [tag](../../topics/git/tags.md) +- The `branch` keyword to specify the name of a branch or [tag](../../user/project/repository/tags/index.md) in the project specified by `project`. You can use variable expansion. ## Trigger a multi-project pipeline by using the API @@ -309,18 +315,33 @@ trigger_pipeline: > Hover behavior for pipeline cards [introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/197140/) in GitLab 13.2. In the [pipeline graph view](index.md#view-full-pipeline-graph), downstream pipelines display -as a list of cards on the right of the graph. Hover over the pipeline's card to view -which job triggered the downstream pipeline. +as a list of cards on the right of the graph. From this view, you can: -### Retry a downstream pipeline +- Select a trigger job to see the triggered downstream pipeline's jobs. +- Select **Expand jobs** **{chevron-lg-right}** on a pipeline card to expand the view + with the downstream pipeline's jobs. You can view one downstream pipeline at a time. +- Hover over a pipeline card to have the job that triggered the downstream pipeline highlighted. + +### Retry failed and canceled jobs in a downstream pipeline > - Retry from 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. > - Retry from graph view [generally available and feature flag removed](https://gitlab.com/gitlab-org/gitlab/-/issues/357406) in GitLab 15.1. -To retry a completed downstream pipeline, select **Retry** (**{retry}**): +To retry failed and canceled jobs, select **Retry** (**{retry}**): - From the downstream pipeline's details page. -- On the pipeline's card in the [pipeline graph view](index.md#view-full-pipeline-graph). +- On the pipeline's card in the pipeline graph view. + +### Recreate a downstream pipeline + +> - Retry trigger job from graph view [introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/367547) in GitLab 15.10 [with a flag](../../administration/feature_flags.md) named `ci_recreate_downstream_pipeline`. Disabled by default. +> - [Generally available](https://gitlab.com/groups/gitlab-org/-/epics/6947) in GitLab 15.11. Feature flag `ci_recreate_downstream_pipeline` removed. + +You can recreate a downstream pipeline by retrying its corresponding trigger job. The newly created downstream pipeline replaces the current downstream pipeline in the pipeline graph. + +To recreate a downstream pipeline: + +- Select **Run again** (**{retry}**) on the trigger job's card in the pipeline graph view. ### Cancel a downstream pipeline @@ -330,7 +351,7 @@ To retry a completed downstream pipeline, select **Retry** (**{retry}**): To cancel a downstream pipeline that is still running, select **Cancel** (**{cancel}**): - From the downstream pipeline's details page. -- On the pipeline's card in the [pipeline graph view](index.md#view-full-pipeline-graph). +- On the pipeline's card in the pipeline graph view. ### Mirror the status of a downstream pipeline in the trigger job @@ -365,13 +386,9 @@ trigger_job: After you trigger a multi-project pipeline, the downstream pipeline displays to the right of the [pipeline graph](index.md#visualize-pipelines). - - In [pipeline mini graphs](index.md#pipeline-mini-graphs), the downstream pipeline displays to the right of the mini graph. - - ## Fetch artifacts from an upstream pipeline Use [`needs:project`](../yaml/index.md#needsproject) to fetch artifacts from an @@ -604,8 +621,9 @@ the ones defined in the upstream project take precedence. ### Pass dotenv variables created in a job **(PREMIUM)** -You can pass variables to a downstream pipeline with [`dotenv` variable inheritance](../variables/index.md#pass-an-environment-variable-to-another-job) -and [`needs:project`](../yaml/index.md#needsproject). +You can pass variables to a downstream job with [`dotenv` variable inheritance](../variables/index.md#pass-an-environment-variable-to-another-job) +and [`needs:project`](../yaml/index.md#needsproject). These variables are only available in +the script of the job and can't be used to configure it, for example with `rules` or `artifact:paths`. For example, in a [multi-project pipeline](#multi-project-pipelines): @@ -656,6 +674,16 @@ With multi-project pipelines, the trigger job fails and does not create the down to run pipelines against the protected branch. See [pipeline security for protected branches](index.md#pipeline-security-on-protected-branches) for more information. +### Job in child pipeline is not created when the pipeline runs + +If the parent pipeline is a [merge request pipeline](merge_request_pipelines.md), +the child pipeline must [use `workflow:rules` or `rules` to ensure the jobs run](#run-child-pipelines-with-merge-request-pipelines). + +If no jobs in the child pipeline can run due to missing or incorrect `rules` configuration: + +- The child pipeline fails to start. +- The parent pipeline's trigger job fails with: `downstream pipeline can not be created, Pipeline will not run for the selected trigger. The rules configuration prevented any jobs from being added to the pipeline.` + ### `Ref is ambiguous` You cannot trigger a multi-project pipeline with a tag when a branch exists with the same diff --git a/doc/ci/pipelines/img/code_coverage_graph_v13_1.png b/doc/ci/pipelines/img/code_coverage_graph_v13_1.png Binary files differdeleted file mode 100644 index da92a1b4a86..00000000000 --- a/doc/ci/pipelines/img/code_coverage_graph_v13_1.png +++ /dev/null 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 differdeleted file mode 100644 index 8c1d005e074..00000000000 --- a/doc/ci/pipelines/img/coverage_check_approval_rule_14_1.png +++ /dev/null diff --git a/doc/ci/pipelines/img/job_artifacts_browser_button_v13_11.png b/doc/ci/pipelines/img/job_artifacts_browser_button_v13_11.png Binary files differdeleted file mode 100644 index 710a82075ce..00000000000 --- a/doc/ci/pipelines/img/job_artifacts_browser_button_v13_11.png +++ /dev/null diff --git a/doc/ci/pipelines/img/job_artifacts_browser_v13_11.png b/doc/ci/pipelines/img/job_artifacts_browser_v13_11.png Binary files differdeleted file mode 100644 index 6a8ea49b833..00000000000 --- a/doc/ci/pipelines/img/job_artifacts_browser_v13_11.png +++ /dev/null diff --git a/doc/ci/pipelines/img/job_artifacts_jobs_page_v13_11.png b/doc/ci/pipelines/img/job_artifacts_jobs_page_v13_11.png Binary files differdeleted file mode 100644 index 9f09e36b927..00000000000 --- a/doc/ci/pipelines/img/job_artifacts_jobs_page_v13_11.png +++ /dev/null diff --git a/doc/ci/pipelines/img/job_artifacts_merge_request_v13_11.png b/doc/ci/pipelines/img/job_artifacts_merge_request_v13_11.png Binary files differdeleted file mode 100644 index f4b875de471..00000000000 --- a/doc/ci/pipelines/img/job_artifacts_merge_request_v13_11.png +++ /dev/null diff --git a/doc/ci/pipelines/img/job_artifacts_pipelines_page_v13_11.png b/doc/ci/pipelines/img/job_artifacts_pipelines_page_v13_11.png Binary files differdeleted file mode 100644 index c7b0b91d488..00000000000 --- a/doc/ci/pipelines/img/job_artifacts_pipelines_page_v13_11.png +++ /dev/null diff --git a/doc/ci/pipelines/img/job_latest_artifacts_browser.png b/doc/ci/pipelines/img/job_latest_artifacts_browser.png Binary files differdeleted file mode 100644 index c6d8856078b..00000000000 --- a/doc/ci/pipelines/img/job_latest_artifacts_browser.png +++ /dev/null diff --git a/doc/ci/pipelines/img/multi_project_pipeline_graph_v14_3.png b/doc/ci/pipelines/img/multi_project_pipeline_graph_v14_3.png Binary files differdeleted file mode 100644 index aadf8bb0979..00000000000 --- a/doc/ci/pipelines/img/multi_project_pipeline_graph_v14_3.png +++ /dev/null diff --git a/doc/ci/pipelines/img/pipeline_mini_graph_v15_0.png b/doc/ci/pipelines/img/pipeline_mini_graph_v15_0.png Binary files differdeleted file mode 100644 index 48a0ca9d84f..00000000000 --- a/doc/ci/pipelines/img/pipeline_mini_graph_v15_0.png +++ /dev/null diff --git a/doc/ci/pipelines/img/pipelines_test_coverage_build.png b/doc/ci/pipelines/img/pipelines_test_coverage_build.png Binary files differdeleted file mode 100644 index 7eaba1a256f..00000000000 --- a/doc/ci/pipelines/img/pipelines_test_coverage_build.png +++ /dev/null diff --git a/doc/ci/pipelines/img/pipelines_test_coverage_mr_widget.png b/doc/ci/pipelines/img/pipelines_test_coverage_mr_widget.png Binary files differdeleted file mode 100644 index fbcd612f3f2..00000000000 --- a/doc/ci/pipelines/img/pipelines_test_coverage_mr_widget.png +++ /dev/null diff --git a/doc/ci/pipelines/index.md b/doc/ci/pipelines/index.md index fa04cb6cb92..b0c5f3a6a69 100644 --- a/doc/ci/pipelines/index.md +++ b/doc/ci/pipelines/index.md @@ -2,7 +2,6 @@ stage: Verify group: Pipeline Authoring info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/product/ux/technical-writing/#assignments -disqus_identifier: 'https://docs.gitlab.com/ee/ci/pipelines.html' type: reference --- @@ -94,7 +93,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#stop-an-environment), +deleted. It's therefore useful in some features such as [automatically stopping an environment](../environments/index.md#stopping-an-environment), and [merge trains](../pipelines/merge_trains.md) that might run pipelines after branch deletion. @@ -195,6 +194,7 @@ In this example: > - [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/363660) in GitLab 15.5 [with a flag](../../administration/feature_flags.md) named `run_pipeline_graphql`. Disabled by default. > - The `options` keyword was [introduced](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/105502) in GitLab 15.7. > - [Generally available](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/106038) in GitLab 15.7. Feature flag `run_pipeline_graphql` removed. +> - The variables list sometimes did not populate correctly due to [a bug](https://gitlab.com/gitlab-org/gitlab/-/issues/386245), which was resolved in GitLab 15.9. You can define an array of CI/CD variable values the user can select from when running a pipeline manually. These values are in a dropdown list in the **Run pipeline** page. Add the list of @@ -423,8 +423,7 @@ You can group the jobs by: - [Job dependencies](#view-job-dependencies-in-the-pipeline-graph), which arranges jobs based on their [`needs`](../yaml/index.md#needs) dependencies. -[Multi-project pipeline graphs](downstream_pipelines.md#view-multi-project-pipelines-in-pipeline-graphs) help -you visualize the entire pipeline, including all cross-project inter-dependencies. +Multi-project pipeline graphs help you visualize the entire pipeline, including all cross-project inter-dependencies. If a stage contains more than 100 jobs, only the first 100 jobs are listed in the pipeline graph. The remaining jobs still run as usual. To see the jobs: diff --git a/doc/ci/pipelines/job_artifacts.md b/doc/ci/pipelines/job_artifacts.md index 75c9852d3d0..c2630d6810d 100644 --- a/doc/ci/pipelines/job_artifacts.md +++ b/doc/ci/pipelines/job_artifacts.md @@ -1,523 +1,11 @@ --- -stage: Verify -group: Pipeline Insights -info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/product/ux/technical-writing/#assignments -disqus_identifier: 'https://docs.gitlab.com/ee/user/project/pipelines/job_artifacts.html' +redirect_to: '../jobs/job_artifacts.md' +remove_date: '2023-07-04' --- -# Job artifacts **(FREE)** +This document was moved to [another location](../jobs/job_artifacts.md). -> [Introduced](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/16675) in GitLab 12.4, artifacts in internal and private projects can be previewed when [GitLab Pages access control](../../administration/pages/index.md#access-control) is enabled. - -Jobs can output an archive of files and directories. This output is known as a job artifact. - -You can download job artifacts by using the GitLab UI or the [API](../../api/job_artifacts.md#get-job-artifacts). - -<i class="fa fa-youtube-play youtube" aria-hidden="true"></i> -For an overview of job artifacts, watch the video [GitLab CI pipelines, artifacts, and environments](https://www.youtube.com/watch?v=PCKDICEe10s). -Or, for an introduction, watch [GitLab CI pipeline tutorial for beginners](https://www.youtube.com/watch?v=Jav4vbUrqII). - -For administrator information about job artifact storage, see [administering job artifacts](../../administration/job_artifacts.md). - -## Create job artifacts - -To create job artifacts, use the `artifacts` keyword in your `.gitlab-ci.yml` file: - -```yaml -pdf: - script: xelatex mycv.tex - artifacts: - paths: - - mycv.pdf - expire_in: 1 week -``` - -In this example, a job named `pdf` calls the `xelatex` command to build a PDF file from the -LaTeX source file, `mycv.tex`. - -The `paths` keyword determines which files to add to the job artifacts. -All paths to files and directories are relative to the repository where the job was created. - -The `expire_in` keyword determines how long GitLab keeps the job artifacts. -You can also [use the UI to keep job artifacts from expiring](#download-job-artifacts). -If `expire_in` is not defined, the -[instance-wide setting](../../user/admin_area/settings/continuous_integration.md#default-artifacts-expiration) -is used. - -If you run two types of pipelines (like branch and scheduled) for the same ref, -the pipeline that finishes later creates the job artifact. - -To disable artifact passing, define the job with empty [dependencies](../yaml/index.md#dependencies): - -```yaml -job: - stage: build - script: make build - dependencies: [] -``` - -You may want to create artifacts only for tagged releases to avoid filling the -build server storage with temporary build artifacts. For example, use [`rules`](../yaml/index.md#rules) -to create artifacts only for tags: - -```yaml -default-job: - script: - - mvn test -U - rules: - - if: $CI_COMMIT_BRANCH - -release-job: - script: - - mvn package -U - artifacts: - paths: - - target/*.war - rules: - - if: $CI_COMMIT_TAG -``` - -You can use wildcards for directories too. For example, if you want to get all the -files inside the directories that end with `xyz`: - -```yaml -job: - artifacts: - paths: - - path/*xyz/* -``` - -### Use CI/CD variables to define the artifacts name - -You can use [CI/CD variables](../variables/index.md) to dynamically define the -artifacts file's name. - -For example, to create an archive with a name of the current job: - -```yaml -job: - artifacts: - name: "$CI_JOB_NAME" - paths: - - binaries/ -``` - -To create an archive with a name of the current branch or tag including only -the binaries directory: - -```yaml -job: - artifacts: - name: "$CI_COMMIT_REF_NAME" - paths: - - binaries/ -``` - -If your branch-name contains forward slashes -(for example `feature/my-feature`) it's advised to use `$CI_COMMIT_REF_SLUG` -instead of `$CI_COMMIT_REF_NAME` for proper naming of the artifact. - -To create an archive with a name of the current job and the current branch or -tag including only the binaries directory: - -```yaml -job: - artifacts: - name: "$CI_JOB_NAME-$CI_COMMIT_REF_NAME" - paths: - - binaries/ -``` - -To create an archive with a name of the current [stage](../yaml/index.md#stages) and branch name: - -```yaml -job: - artifacts: - name: "$CI_JOB_STAGE-$CI_COMMIT_REF_NAME" - paths: - - binaries/ -``` - -If you use **Windows Batch** to run your shell scripts you must replace -`$` with `%`: - -```yaml -job: - artifacts: - name: "%CI_JOB_STAGE%-%CI_COMMIT_REF_NAME%" - paths: - - binaries/ -``` - -If you use **Windows PowerShell** to run your shell scripts you must replace -`$` with `$env:`: - -```yaml -job: - artifacts: - name: "$env:CI_JOB_STAGE-$env:CI_COMMIT_REF_NAME" - paths: - - binaries/ -``` - -### Exclude files from job artifacts - -Use [`artifacts:exclude`](../yaml/index.md#artifactsexclude) to prevent files from -being added to an artifacts archive. - -For example, to store all files in `binaries/`, but not `*.o` files located in -subdirectories of `binaries/`. - -```yaml -artifacts: - paths: - - binaries/ - exclude: - - binaries/**/*.o -``` - -Unlike [`artifacts:paths`](../yaml/index.md#artifactspaths), `exclude` paths are not recursive. -To exclude all of the contents of a directory, match them explicitly rather -than matching the directory itself. - -For example, to store all files in `binaries/` but nothing located in the `temp/` subdirectory: - -```yaml -artifacts: - paths: - - binaries/ - exclude: - - binaries/temp/**/* -``` - -### Add untracked files to artifacts - -Use [`artifacts:untracked`](../yaml/index.md#artifactsuntracked) to add all Git untracked -files as artifacts (along with the paths defined in [`artifacts:paths`](../yaml/index.md#artifactspaths)). Untracked -files are those that haven't been added to the repository but exist in the repository checkout. - -Save all Git untracked files and files in `binaries`: - -```yaml -artifacts: - untracked: true - paths: - - binaries/ -``` - -Save all untracked files but [exclude](../yaml/index.md#artifactsexclude) `*.txt`: - -```yaml -artifacts: - untracked: true - exclude: - - "*.txt" -``` - -## Download job artifacts - -You can download job artifacts or view the job archive: - -- On the **Pipelines** page, to the right of the pipeline: - -  - -- On the **Jobs** page, to the right of the job: - -  - -- On a job's detail page. The **Keep** button indicates an `expire_in` value was set: - -  - -- On a merge request, by the pipeline details: - -  - -- When browsing an archive: - -  - - If [GitLab Pages](../../administration/pages/index.md) is enabled in the project, you can preview - HTML files in the artifacts directly in your browser. If the project is internal or private, you must - enable [GitLab Pages access control](../../administration/pages/index.md#access-control) to preview - HTML files. - -## View failed job artifacts - -If the latest job has failed to upload the artifacts, you can see that -information in the UI. - - - -## Delete job artifacts - -WARNING: -This is a destructive action that leads to data loss. Use with caution. - -You can delete a single job, which also removes the job's -artifacts and log. You must be: - -- The owner of the job. -- A user with at least the Maintainer role for the project. - -To delete a job: - -1. Go to a job's detail page. -1. In the upper right of the job's log, select **Erase job log** (**{remove}**). -1. On the confirmation dialog, select **OK**. - -## Expose job artifacts in the merge request UI - -Use the [`artifacts:expose_as`](../yaml/index.md#artifactsexpose_as) keyword to expose -[job artifacts](../pipelines/job_artifacts.md) in the [merge request](../../user/project/merge_requests/index.md) UI. - -For example, to match a single file: - -```yaml -test: - script: ["echo 'test' > file.txt"] - artifacts: - expose_as: 'artifact 1' - paths: ['file.txt'] -``` - -With this configuration, GitLab adds a link **artifact 1** to the relevant merge request -that points to `file.txt`. To access the link, select **View exposed artifact** -below the pipeline graph in the merge request overview. - -An example that matches an entire directory: - -```yaml -test: - script: ["mkdir test && echo 'test' > test/file.txt"] - artifacts: - expose_as: 'artifact 1' - paths: ['test/'] -``` - -## Retrieve job artifacts for other projects - -To retrieve a job artifact from a different project, you might need to use a -private token to [authenticate and download](../../api/job_artifacts.md#get-job-artifacts) -the artifact. - -## How searching for job artifacts works - -In [GitLab 13.5 and later](https://gitlab.com/gitlab-org/gitlab/-/issues/201784), artifacts -for [parent and child pipelines](downstream_pipelines.md#parent-child-pipelines) are searched in hierarchical -order from parent to child. For example, if both parent and child pipelines have a -job with the same name, the job artifact from the parent pipeline is returned. - -## Access the latest job artifacts - -You can download job artifacts from the latest successful pipeline by using [the job artifacts API](../../api/job_artifacts.md). -You cannot download [artifact reports](../yaml/artifacts_reports.md) with the job artifacts API, -unless the report is added as a regular artifact with `artifacts:paths`. - -### Download the whole artifacts archive for a specific job - -You can download the artifacts archive for a specific job with [the job artifacts API](../../api/job_artifacts.md#download-the-artifacts-archive). - -For example, to download the latest artifacts of a job named `build` in the `main` branch of a project on GitLab.com: - -```plaintext -https://gitlab.com/api/v4/projects/<project-id>/jobs/artifacts/main/download?job=build -``` - -Replace `<project-id>` with a valid project ID, found at the top of the project details page. - -### Download a single file from the artifacts - -You can download a specific file from the artifacts archive for a specific job with [the job artifacts API](../../api/job_artifacts.md#download-a-single-artifact-file-by-job-id). - -For example, to download the file `review/index.html` from the latest job named `build` in the `main` branch of the `gitlab` project in the `gitlab-org` namespace: - -```plaintext -https://gitlab.com/api/v4/projects/27456355/jobs/artifacts/main/raw/review/index.html?job=build -``` - -### Browse job artifacts - -To browse the job artifacts of the latest successful pipeline for a specific job you can use the following URL: - -```plaintext -https://example.com/<namespace>/<project>/-/jobs/artifacts/<ref>/browse?job=<job_name> -``` - -For example, to browse the latest artifacts of a job named `build` in the `main` branch of a project on GitLab.com: - -```plaintext -https://gitlab.com/<full-project-path>/-/jobs/artifacts/main/browse?job=build -``` - -Replace `<full-project-path>` with a valid project path, you can find it in the URL for your project. - -## When job artifacts are deleted - -See the [`expire_in`](../yaml/index.md#artifactsexpire_in) documentation for information on when -job artifacts are deleted. - -### Keep artifacts from most recent successful jobs - -> - [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/16267) in GitLab 13.0. -> - [Feature flag removed](https://gitlab.com/gitlab-org/gitlab/-/issues/229936) in GitLab 13.4. -> - [Made optional with a CI/CD setting](https://gitlab.com/gitlab-org/gitlab/-/issues/241026) in GitLab 13.8. - -By default artifacts are always kept for successful pipelines for the most recent commit on -each ref. This means that the latest artifacts do not immediately expire according -to the `expire_in` specification. - -If a pipeline for a new commit on the same ref completes successfully, the previous pipeline's -artifacts are deleted according to the `expire_in` configuration. The artifacts -of the new pipeline are kept automatically. If multiple pipelines run for the most -recent commit on the ref, all artifacts are kept. - -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. On the top bar, select **Main 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 -[instance's CI/CD settings](../../user/admin_area/settings/continuous_integration.md#keep-the-latest-artifacts-for-all-jobs-in-the-latest-successful-pipelines). - -When **Keep artifacts from most recent successful jobs** is enabled, artifacts are always kept for [blocked](../jobs/job_control.md#types-of-manual-jobs) -pipelines. These artifacts expire only after the blocking job is triggered and the pipeline completes. -For more information, see [issue 387087](https://gitlab.com/gitlab-org/gitlab/-/issues/387087). - -## Troubleshooting - -### Job does not retrieve certain artifacts - -By default, jobs fetch all artifacts from previous stages, but jobs using `dependencies` -or `needs` do not fetch artifacts from all jobs by default. - -If you use these keywords, artifacts are fetched from only a subset of jobs. Review -the keyword reference for information on how to fetch artifacts with these keywords: - -- [`dependencies`](../yaml/index.md#dependencies) -- [`needs`](../yaml/index.md#needs) -- [`needs:artifacts`](../yaml/index.md#needsartifacts) - -### Job artifacts using too much disk space - -There are a number of potential causes for this. -[Read more in the job artifacts administration documentation](../../administration/job_artifacts.md#job-artifacts-using-too-much-disk-space). - -### Error message `No files to upload` - -This message is often preceded by other errors or warnings that specify the filename and why it wasn't -generated. Check the job log for these messages. - -If you find no helpful messages, retry the failed job after activating -[CI/CD debug logging](../variables/index.md#enable-debug-logging). -This logging should provide information to help you investigate further. - -### Error message `Missing /usr/bin/gitlab-runner-helper. Uploading artifacts is disabled.` - -There is a [known issue](https://gitlab.com/gitlab-org/gitlab-runner/-/issues/3068) where setting a CI/CD variable named `DEBUG` can cause artifact uploads to fail. - -To work around this, either use a different variable name or set it inline with `script`: - -```yaml -# This job might fail due to issue gitlab-org/gitlab-runner#3068 -failing_test_job: - variables: - DEBUG: true - script: bin/mycommand - artifacts: - paths: - - bin/results - -# This job does not define a CI/CD variable named `DEBUG` and is not affected by the issue -successful_test_job: - script: DEBUG=true bin/mycommand - artifacts: - paths: - - bin/results -``` - -### Error message `FATAL: invalid argument` when uploading a dotenv artifact on a windows runner - -The PowerShell `echo` command writes files with UCS-2 LE BOM (Byte Order Mark) encoding, -but only UTF-8 is supported. If you try create the dotenv artifact with `echo`, it causes a -`FATAL: invalid argument` error. - -Use PowerShell `Add-Content` instead, which uses UTF-8: - -```yaml -test-job: - stage: test - tags: - - windows - script: - - echo "test job" - - Add-Content -Path build.env -Value "MY_ENV_VAR=true" - artifacts: - reports: - dotenv: build.env -``` - -### Job artifacts are not expired - -If some job artifacts are not expiring as expected, check if the -[**Keep artifacts from most recent successful jobs**](#keep-artifacts-from-most-recent-successful-jobs) -setting is enabled. - -When this setting is enabled, job artifacts from the latest successful pipeline -of each ref do not expire and are not deleted. - -### Error message `This job could not start because it could not retrieve the needed artifacts.` - -A job configured with [`needs:artifacts`](../yaml/index.md#needsartifacts) keyword -fails to start and returns this error message if: - -- The job's dependencies cannot be found. -- The job cannot access the relevant resources due to insufficient permissions. - -The troubleshooting steps to follow are determined by the syntax used in the job configuration. - -#### Job configured with `needs:project` - -The `could not retrieve the needed artifacts.` error can happen for a job using -[`needs:project`](../yaml/index.md#needsproject), with a configuration similar to: - -```yaml -rspec: - needs: - - project: org/another-project - job: dependency-job - ref: master - artifacts: true -``` - -To troubleshoot this job, verify that: - -- Project `org/another-project` is in a group with a Premium subscription plan. -- The user running the job has permissions to access resources in `org/another-project`. -- The `project`, `job`, and `ref` combination exists and results in the desired dependency. -- Any variables in use evaluate to the correct values. - -#### Job configured with `needs:pipeline:job` - -The `could not retrieve the needed artifacts.` error can happen for a job using -[`needs:pipeline:job`](../yaml/index.md#needspipelinejob), with a configuration similar to: - -```yaml -rspec: - needs: - - pipeline: $UPSTREAM_PIPELINE_ID - job: dependency-job - artifacts: true -``` - -To troubleshoot this job, verify that: - -- The `$UPSTREAM_PIPELINE_ID` CI/CD variable is available in the current pipeline's - parent-child pipeline hierarchy. -- The `pipeline` and `job` combination exists and resolves to an existing pipeline. -- `dependency-job` has run and finished successfully. +<!-- This redirect file can be deleted after <2023-07-04>. --> +<!-- Redirects that point to other docs in the same project expire in three months. --> +<!-- Redirects that point to docs in a different project or site (for example, link is not relative and starts with `https:`) expire in one year. --> +<!-- Before deletion, see: https://docs.gitlab.com/ee/development/documentation/redirects.html --> diff --git a/doc/ci/pipelines/merge_request_pipelines.md b/doc/ci/pipelines/merge_request_pipelines.md index 7e18c11f234..d42f35627a2 100644 --- a/doc/ci/pipelines/merge_request_pipelines.md +++ b/doc/ci/pipelines/merge_request_pipelines.md @@ -140,14 +140,7 @@ the parent project. Additionally, if you do not trust the fork project's runner, running the pipeline in the parent project uses the parent project's trusted runners. 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. 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**. +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. Unless you trigger the pipeline through the API or the [`/rebase` quick action](../../user/project/quick_actions.md#issues-merge-requests-and-epics), GitLab shows a warning that you must accept before the pipeline runs. Otherwise, **no warning displays**. Prerequisites: @@ -209,16 +202,20 @@ It's possible to have both branch pipelines and merge request pipelines in the **Pipelines** tab of a single merge request. This might be [by configuration](../yaml/workflow.md#switch-between-branch-pipelines-and-merge-request-pipelines), or [by accident](#two-pipelines-when-pushing-to-a-branch). -If both types of pipelines are in one merge request, the merge request's pipeline -is not considered successful if: - -- The branch pipeline succeeds. -- The merge request pipeline fails. - When using the [merge when pipeline succeeds](../../user/project/merge_requests/merge_when_pipeline_succeeds.md) feature and both pipelines types are present, the merge request pipelines are checked, not the branch pipelines. +Therefore, the MR pipeline result is marked as unsuccessful if the +**merge request pipeline** fails, independently of the **branch pipeline** result. + +However: + +- These conditions are not enforced. +- A race condition determines which pipeline's result is used to either block or pass merge requests. + +This bug is tracked on [issue 384927](https://gitlab.com/gitlab-org/gitlab/-/issues/384927). + ### `An error occurred while trying to run a new pipeline for this merge request.` This error can happen when you select **Run pipeline** in a merge request, but the diff --git a/doc/ci/pipelines/merge_trains.md b/doc/ci/pipelines/merge_trains.md index 370d81dacc4..af29c8105ee 100644 --- a/doc/ci/pipelines/merge_trains.md +++ b/doc/ci/pipelines/merge_trains.md @@ -6,6 +6,10 @@ info: To determine the technical writer assigned to the Stage/Group associated w # Merge trains **(PREMIUM)** +FLAG: +In GitLab 15.11 and later, the **Start merge train** button is **Set to auto-merge** and the **Add to merge train** button is **Merge**. On self-managed GitLab, by default these changes are not available. To make them available, +ask an administrator to [enable the feature flag](../../administration/feature_flags.md) named `auto_merge_labels_mr_widget`. On GitLab.com, this feature is not available. + Use merge trains to queue merge requests and verify their changes work together before they are merged to the target branch. diff --git a/doc/ci/pipelines/merged_results_pipelines.md b/doc/ci/pipelines/merged_results_pipelines.md index 097f6bad87c..316d7819f55 100644 --- a/doc/ci/pipelines/merged_results_pipelines.md +++ b/doc/ci/pipelines/merged_results_pipelines.md @@ -74,3 +74,10 @@ is not found in the merge ref. This behavior was improved in GitLab 12.4 by introducing [persistent pipeline refs](../troubleshooting.md#fatal-reference-is-not-a-tree-error). Upgrade to GitLab 12.4 or later to resolve the problem. + +### Successful merged results pipeline overrides a failed branch pipeline + +A failed branch pipeline is sometimes ignored when the +[**Pipelines must succeed** setting](../../user/project/merge_requests/merge_when_pipeline_succeeds.md#require-a-successful-pipeline-for-merge) +is activated. +[Issue 385841](https://gitlab.com/gitlab-org/gitlab/-/issues/385841) is open to track this. diff --git a/doc/ci/pipelines/pipeline_architectures.md b/doc/ci/pipelines/pipeline_architectures.md index e4a3416f60b..dadf631e2bb 100644 --- a/doc/ci/pipelines/pipeline_architectures.md +++ b/doc/ci/pipelines/pipeline_architectures.md @@ -1,6 +1,6 @@ --- stage: Verify -group: Pipeline Execution +group: Pipeline Authoring info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/product/ux/technical-writing/#assignments type: reference --- diff --git a/doc/ci/pipelines/pipeline_artifacts.md b/doc/ci/pipelines/pipeline_artifacts.md index aacaa110041..d8db79a54dc 100644 --- a/doc/ci/pipelines/pipeline_artifacts.md +++ b/doc/ci/pipelines/pipeline_artifacts.md @@ -1,13 +1,13 @@ --- stage: Verify -group: Pipeline Insights +group: Pipeline Security info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/product/ux/technical-writing/#assignments --- # Pipeline artifacts **(FREE)** Pipeline artifacts are files created by GitLab after a pipeline finishes. Pipeline artifacts are -different to [job artifacts](job_artifacts.md) because they are not explicitly managed by +different to [job artifacts](../jobs/job_artifacts.md) because they are not explicitly managed by `.gitlab-ci.yml` definitions. Pipeline artifacts are used by the [test coverage visualization feature](../testing/test_coverage_visualization.md) diff --git a/doc/ci/pipelines/pipeline_efficiency.md b/doc/ci/pipelines/pipeline_efficiency.md index 0795005aa8e..c0c8d60b9d6 100644 --- a/doc/ci/pipelines/pipeline_efficiency.md +++ b/doc/ci/pipelines/pipeline_efficiency.md @@ -147,7 +147,7 @@ with embedded metric charts and all valuable details to analyze the problem. Review the storage use of the following to help analyze costs and efficiency: -- [Job artifacts](job_artifacts.md) and their [`expire_in`](../yaml/index.md#artifactsexpire_in) +- [Job artifacts](../jobs/job_artifacts.md) and their [`expire_in`](../yaml/index.md#artifactsexpire_in) configuration. If kept for too long, storage usage grows and could slow pipelines down. - [Container registry](../../user/packages/container_registry/index.md) usage. - [Package registry](../../user/packages/package_registry/index.md) usage. diff --git a/doc/ci/pipelines/schedules.md b/doc/ci/pipelines/schedules.md index 02728d5e1e0..3ff748644cf 100644 --- a/doc/ci/pipelines/schedules.md +++ b/doc/ci/pipelines/schedules.md @@ -2,7 +2,6 @@ stage: Verify group: Pipeline Execution info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/product/ux/technical-writing/#assignments -disqus_identifier: 'https://docs.gitlab.com/ee/user/project/pipelines/schedules.html' type: reference, howto --- @@ -84,8 +83,8 @@ To take ownership of a pipeline created by a different user: ## Related topics -- Pipeline schedules can be maintained by using the [Pipeline schedules API](../../api/pipeline_schedules.md). -- You can [control which jobs are added to scheduled pipelines](../jobs/job_control.md#run-jobs-for-scheduled-pipelines). +- [Pipeline schedules API](../../api/pipeline_schedules.md) +- [Adding jobs to scheduled pipelines](../jobs/job_control.md#run-jobs-for-scheduled-pipelines) <!-- ## Troubleshooting diff --git a/doc/ci/pipelines/settings.md b/doc/ci/pipelines/settings.md index 3633863915c..3e9e6c50f64 100644 --- a/doc/ci/pipelines/settings.md +++ b/doc/ci/pipelines/settings.md @@ -2,7 +2,6 @@ stage: Verify group: Pipeline Execution info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/product/ux/technical-writing/#assignments -disqus_identifier: 'https://docs.gitlab.com/ee/user/project/pipelines/settings.html' type: reference, howto --- @@ -71,7 +70,7 @@ is selected. ## Auto-cancel redundant pipelines -You can set pending or running pipelines to cancel automatically when a new pipeline runs on the same branch. You can enable this in the project settings: +You can set pending or running pipelines to cancel automatically when a pipeline for new changes runs on the same branch. You can enable this in the project settings: 1. On the top bar, select **Main menu > Projects** and find your project. 1. On the left sidebar, select **Settings > CI/CD**. @@ -209,119 +208,7 @@ Jobs that exceed the timeout are marked as failed. You can override this value [for individual runners](../runners/configure_runners.md#set-maximum-job-timeout-for-a-runner). -## Merge request test coverage results - -If you use test coverage in your code, you can use a regular expression to -find coverage results in the job log. You can then include these results -in the merge request in GitLab. - -If the pipeline succeeds, the coverage is shown in the merge request widget and -in the jobs table. If multiple jobs in the pipeline have coverage reports, they are -averaged. - - - - - -### Add test coverage results using `coverage` keyword - -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. - -### Test coverage examples - -Use this regex for commonly used test tools. - -<!-- vale gitlab.Spelling = NO --> - -- Simplecov (Ruby). Example: `/\(\d+.\d+\%\) covered/`. -- pytest-cov (Python). Example: `/(?i)total.*? (100(?:\.0+)?\%|[1-9]?\d(?:\.\d+)?\%)$/`. -- Scoverage (Scala). Example: `/Statement coverage[A-Za-z\.*]\s*:\s*([^%]+)/`. -- `pest --coverage --colors=never` (PHP). Example: `/^\s*Cov:\s*\d+\.\d+?%$/`. -- `phpunit --coverage-text --colors=never` (PHP). Example: `/^\s*Lines:\s*\d+.\d+\%/`. -- 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})%/`. -- `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/`. -- Pester (PowerShell). Example: `/Covered (\d+\.\d+%)/`. - -<!-- vale gitlab.Spelling = YES --> - -### View code coverage history - -> - [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/209121) the ability to download a `.csv` in GitLab 12.10. -> - Graph [introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/33743) in GitLab 13.1. - -To see the evolution of your project code coverage over time, -you can view a graph or download a CSV file with this data. - -1. On the top bar, select **Main menu > Projects** and find your project. -1. On the left sidebar, select **Analytics > Repository**. - -The historic data for each job is listed in the dropdown list above the graph. - -To view a CSV file of the data, select **Download raw data (`.csv`)**. - - - -Code coverage data is also [available at the group level](../../user/group/repositories_analytics/index.md). - -### Coverage check approval rule **(PREMIUM)** - -> - [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/15765) in GitLab 14.0. -> - [Made configurable in Project Settings](https://gitlab.com/gitlab-org/gitlab/-/issues/331001) in GitLab 14.1. - -You can implement merge request approvals to require approval by selected users or a group -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 > Merge requests**. -1. Under **Merge request approvals**, select **Enable** next to the `Coverage-Check` approval rule. -1. Select the **Target branch**. -1. Set the number of **Approvals required** to greater than zero. -1. Select the users or groups to provide approval. -1. Select **Add approval rule**. - - - -### Remove color codes from code coverage - -Some test coverage tools output with ANSI color codes that aren't -parsed correctly by the regular expression. This causes coverage -parsing to fail. - -Some coverage tools don't provide an option to disable color -codes in the output. If so, pipe the output of the coverage tool through a -small one line script that strips the color codes off. - -For example: - -```shell -lein cloverage | perl -pe 's/\e\[?.*?[\@-~]//g' -``` - ## Pipeline badges You can use [pipeline badges](../../user/project/badges.md) to indicate the pipeline status and test coverage of your projects. These badges are determined by the latest successful pipeline. - -<!-- ## 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, for example `### 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. --> |
