diff options
Diffstat (limited to 'doc/ci/pipelines/settings.md')
| -rw-r--r-- | doc/ci/pipelines/settings.md | 351 |
1 files changed, 190 insertions, 161 deletions
diff --git a/doc/ci/pipelines/settings.md b/doc/ci/pipelines/settings.md index 2e842856e55..db6fa7f4d23 100644 --- a/doc/ci/pipelines/settings.md +++ b/doc/ci/pipelines/settings.md @@ -6,125 +6,199 @@ disqus_identifier: 'https://docs.gitlab.com/ee/user/project/pipelines/settings.h type: reference, howto --- -# Pipeline settings **(FREE)** +# Customize pipeline configuration **(FREE)** -To reach the pipelines settings navigate to your project's -**Settings > CI/CD**. - -The following settings can be configured per project. +You can customize how pipelines run for your project. <i class="fa fa-youtube-play youtube" aria-hidden="true"></i> -For an overview, watch the video [GitLab CI Pipeline, Artifacts, and Environments](https://www.youtube.com/watch?v=PCKDICEe10s). +For an overview of pipelines, watch the video [GitLab CI Pipeline, Artifacts, and Environments](https://www.youtube.com/watch?v=PCKDICEe10s). Watch also [GitLab CI pipeline tutorial for beginners](https://www.youtube.com/watch?v=Jav4vbUrqII). -You can use the pipeline status to determine if a merge request can be merged: +## Change which users can view your pipelines -- [Merge when pipeline succeeds](../../user/project/merge_requests/merge_when_pipeline_succeeds.md). -- [Only allow merge requests to be merged if the pipeline succeeds](../../user/project/merge_requests/merge_when_pipeline_succeeds.md#only-allow-merge-requests-to-be-merged-if-the-pipeline-succeeds). +For public and internal projects, you can change who can see your: -## Git strategy +- Pipelines +- Job output logs +- Job artifacts +- [Pipeline security dashboard](../../user/application_security/security_dashboard/index.md#pipeline-security) -With Git strategy, you can choose the default way your repository is fetched -from GitLab in a job. +However: -There are two options. Using: +- Job output logs and artifacts are [never visible for Guest users and non-project members](https://gitlab.com/gitlab-org/gitlab/-/issues/25649). -- `git clone`, which is slower because it clones the repository from scratch - for every job, ensuring that the local working copy is always pristine. -- `git fetch`, which is default in GitLab and faster as it re-uses the local working copy (falling - back to clone if it doesn't exist). - This is recommended, especially for [large repositories](../large_repositories/index.md#git-strategy). +To change the visibility of your pipelines and related features: -The configured Git strategy can be overridden by the [`GIT_STRATEGY` variable](../runners/configure_runners.md#git-strategy) -in `.gitlab-ci.yml`. +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. Select or clear the **Public pipelines** checkbox. + When it is selected, pipelines and related features are visible: -## Git shallow clone + - For **public** projects, to everyone. + - For **internal** projects, to all logged-in users except [external users](../../user/permissions.md#external-users). + - For **private** projects, to all project members (Guest or higher). -> [Introduced](https://gitlab.com/gitlab-org/gitlab-foss/-/merge_requests/28919) in GitLab 12.0. + When it is cleared: -It is possible to limit the number of changes that GitLab CI/CD fetches when cloning -a repository. Setting a limit to `git depth` can speed up Pipelines execution. + - For **public** projects, pipelines are visible to everyone. Related features are visible + only to project members (Reporter or higher). + - For **internal** projects, pipelines are visible to all logged in users except [external users](../../user/permissions.md#external-users). + Related features are visible only to project members (Reporter or higher). + - For **private** projects, pipelines and related features are visible to project members (Reporter or higher) only. -In GitLab 12.0 and later, newly created projects automatically have a default -`git depth` value of `50`. The maximum allowed value is `1000`. +## 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: + +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. Select the **Auto-cancel redundant pipelines** checkbox. +1. Select **Save changes**. + +Use the [`interruptible`](../yaml/index.md#interruptible) keyword to indicate if a +running job can be cancelled before it completes. -To disable shallow clone and make GitLab CI/CD fetch all branches and tags each time, -keep the value empty or set to `0`. +## Skip outdated deployment jobs + +> [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/25276) in GitLab 12.9. + +Your project may have multiple concurrent deployment jobs that are +scheduled to run in the same time frame. + +This can lead to a situation where an older deployment job runs after a +newer one, which may not be what you want. -This value can also be [overridden by `GIT_DEPTH`](../large_repositories/index.md#shallow-cloning) variable in `.gitlab-ci.yml` file. +To avoid this scenario: -## Timeout +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. Select the **Skip outdated deployment jobs** checkbox. +1. Select **Save changes**. -Timeout defines the maximum amount of time in minutes that a job is able run. -This is configurable under your project's **Settings > CI/CD > General pipelines settings**. -The default value is 60 minutes. Decrease the time limit if you want to impose -a hard limit on your jobs' running time or increase it otherwise. In any case, -if the job surpasses the threshold, it is marked as failed. +Older deployment job are skipped when a new deployment starts. -### Timeout overriding for runners +For more information, see [Deployment safety](../environments/deployment_safety.md). -> [Introduced](https://gitlab.com/gitlab-org/gitlab-foss/-/merge_requests/17221) in GitLab 10.7. +## Retry outdated jobs -Project defined timeout (either specific timeout set by user or the default -60 minutes timeout) may be [overridden for runners](../runners/configure_runners.md#set-maximum-job-timeout-for-a-runner). +> [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/211339) in GitLab 13.6. -## Maximum artifacts size **(FREE SELF)** +A deployment job can fail because a newer one has run. If you retry the failed deployment job, the +environment could be overwritten with older source code. If you click **Retry**, a modal warns you +about this and asks for confirmation. -For information about setting a maximum artifact size for a project, see -[Maximum artifacts size](../../user/admin_area/settings/continuous_integration.md#maximum-artifacts-size). +For more information, see [Deployment safety](../environments/deployment_safety.md). -## Custom CI/CD configuration file +## Specify a custom CI/CD configuration file > [Support for external `.gitlab-ci.yml` locations](https://gitlab.com/gitlab-org/gitlab/-/issues/14376) introduced in GitLab 12.6. -By default we look for the `.gitlab-ci.yml` file in the project's root -directory. If needed, you can specify an alternate path and filename, including locations outside the project. +GitLab expects to find the CI/CD configuration file (`.gitlab-ci.yml`) in the project's root +directory. However, you can specify an alternate filename path, including locations outside the project. To customize the path: -1. Go to the project's **Settings > CI/CD**. -1. Expand the **General pipelines** section. -1. Provide a value in the **CI/CD configuration file** field. -1. Click **Save changes**. +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 **CI/CD configuration file** field, enter the filename. If the file: + - Is not in the root directory, include the path. + - Is in a different project, include the group and project name. + - Is on an external site, enter the full URL. +1. Select **Save changes**. + +### Custom CI/CD configuration file examples -If the CI/CD configuration file is stored in the repository in a non-default -location, the path must be relative to the root directory. Examples of valid -paths and file names include: +If the CI/CD configuration file is not in the root directory, the path must be relative to it. +For example: -- `.gitlab-ci.yml` (default) -- `.my-custom-file.yml` - `my/path/.gitlab-ci.yml` - `my/path/.my-custom-file.yml` -If hosting the CI/CD configuration file on an external site, the URL link must end with `.yml`: +If the CI/CD configuration file is on an external site, the URL must end with `.yml`: - `http://example.com/generate/ci/config.yml` -If hosting the CI/CD configuration file in a different project in GitLab, the path must be relative +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: - `.gitlab-ci.yml@mygroup/another-project` - `my/path/.my-custom-file.yml@mygroup/another-project` -Hosting the configuration file in a separate project allows stricter control of the -configuration file. For example: +If the configuration file is in a separate project, you can more set more granular permissions. For example: - Create a public project to host the configuration file. - Give write permissions on the project only to users who are allowed to edit the file. -Other users and projects can access the configuration file without being +Then other users and projects can access the configuration file without being able to edit it. -## Test coverage parsing +## Choose the default Git strategy + +You can choose how your repository is fetched from GitLab when a job runs. + +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. Under **Git strategy**, select an option: + - `git clone` is slower because it clones the repository from scratch + for every job. However, the local working copy is always pristine. + - `git fetch` is faster because it re-uses the local working copy (and falls + back to clone if it doesn't exist). This is recommended, especially for + [large repositories](../large_repositories/index.md#git-strategy). + +The configured Git strategy can be overridden by the [`GIT_STRATEGY` variable](../runners/configure_runners.md#git-strategy) +in the `.gitlab-ci.yml` file. + +## Limit the number of changes fetched during clone + +> [Introduced](https://gitlab.com/gitlab-org/gitlab-foss/-/merge_requests/28919) in GitLab 12.0. + +You can limit the number of changes that GitLab CI/CD fetches when it clones +a repository. + +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. Under **Git strategy**, under **Git shallow clone**, enter a value. + The maximum value is `1000`. To disable shallow clone and make GitLab CI/CD + fetch all branches and tags each time, keep the value empty or set to `0`. + +In GitLab 12.0 and later, newly created projects automatically have a default +`git depth` value of `50`. + +This value can be overridden by the [`GIT_DEPTH` variable](../large_repositories/index.md#shallow-cloning) +in the `.gitlab-ci.yml` file. + +## Set a limit for how long jobs can run + +You can define how long a job can run before it times out. + +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 **Timeout** field, enter the number of minutes, or a human-readable value like `2 hours`. + +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). + +## Add test coverage results to a merge request -If you use test coverage in your code, GitLab can capture its output in the -job log using a regular expression. +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. -In your project, go to **Settings > CI/CD** and expand the **General pipelines** -section. Enter the regular expression in the **Test coverage parsing** field. +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. -Leave blank if you want to disable it or enter a Ruby regular expression. You -can use <https://rubular.com> to test your regex. The regex returns the **last** +You can use <https://rubular.com> to test your regex. The regex returns the **last** match found in the output. If the pipeline succeeds, the coverage is shown in the merge request widget and @@ -135,6 +209,10 @@ averaged.  +### Test coverage examples + +Use this regex for commonly used test tools. + <!-- vale gitlab.Spelling = NO --> - Simplecov (Ruby). Example: `\(\d+.\d+\%\) covered`. @@ -148,27 +226,51 @@ averaged. - `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+)?)`. +- .NET (OpenCover). Example: `(Visited Points).*\((.*)\)`. +- .NET (`dotnet test` line coverage). Example: `Total\s*\|\s*(\d+(?:\.\d+)?)`. <!-- vale gitlab.Spelling = YES --> -### Code Coverage history +### 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. From your project: +you can view a graph or download a CSV file with this data. + +1. On the top bar, select **Menu > Projects** and find your project. +1. On the left sidebar, select **Analytics > Repository**. -1. Go to **Project Analytics > Repository** to see the historic data for each job listed in the dropdown above the graph. -1. If you want a CSV file of that data, click **Download raw data (`.csv`)** +The historic data for each job is listed in the dropdown 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). -### Removing color codes +### 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. Go to your project and select **Settings > General**. +1. Expand **Merge request approvals**. +1. 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 @@ -184,93 +286,20 @@ For example: lein cloverage | perl -pe 's/\e\[?.*?[\@-~]//g' ``` -## Visibility of pipelines - -Pipeline visibility is determined by: - -- Your current [user access level](../../user/permissions.md). -- The **Public pipelines** project setting under your project's **Settings > CI/CD > General pipelines**. - -NOTE: -If the project visibility is set to **Private**, the [**Public pipelines** setting has no effect](../enable_or_disable_ci.md#per-project-user-setting). - -This also determines the visibility of these related features: - -- Job output logs -- Job artifacts -- The [pipeline security dashboard](../../user/application_security/security_dashboard/index.md#pipeline-security) **(ULTIMATE)** - -Job logs and artifacts are [not visible for guest users and non-project members](https://gitlab.com/gitlab-org/gitlab/-/issues/25649). - -If **Public pipelines** is enabled (default): - -- For **public** projects, anyone can view the pipelines and related features. -- For **internal** projects, any logged in user except [external users](../../user/permissions.md#external-users) can view the pipelines - and related features. -- For **private** projects, any project member (guest or higher) can view the pipelines - and related features. - -If **Public pipelines** is disabled: - -- For **public** projects, anyone can view the pipelines, but only members - (reporter or higher) can access the related features. -- For **internal** projects, any logged in user except [external users](../../user/permissions.md#external-users) can view the pipelines. - However, only members (reporter or higher) can access the job related features. -- For **private** projects, only project members (reporter or higher) - can view the pipelines or access the related features. - -## Auto-cancel 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: - -1. Go to **Settings > CI/CD**. -1. Expand **General Pipelines**. -1. Check the **Auto-cancel redundant pipelines** checkbox. -1. Click **Save changes**. - -Use the [`interruptible`](../yaml/README.md#interruptible) keyword to indicate if a -running job can be cancelled before it completes. - -## Skip outdated deployment jobs - -> [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/25276) in GitLab 12.9. +## Pipeline badges -Your project may have multiple concurrent deployment jobs that are -scheduled to run in the same time frame. +Pipeline badges indicate the pipeline status and a test coverage value +for your project. These badges are determined by the latest successful pipeline. -This can lead to a situation where an older deployment job runs after a -newer one, which may not be what you want. +### View the code for the pipeline status and coverage reports badges -To avoid this scenario: +You can view the exact link for your badges. Then you can embed the badge in your HTML +or Markdown pages. -1. Go to **Settings > CI/CD**. +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. Check the **Skip outdated deployment jobs** checkbox. -1. Click **Save changes**. - -When enabled, any older deployments job are skipped when a new deployment starts. - -For more information, see [Deployment safety](../environments/deployment_safety.md). - -## Retry outdated jobs - -> [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/211339) in GitLab 13.6. - -A deployment job can fail because a newer one has run. If you retry the failed deployment job, the -environment could be overwritten with older source code. If you click **Retry**, a modal warns you -about this and asks for confirmation. - -For more information, see [Deployment safety](../environments/deployment_safety.md). - -## Pipeline Badges - -In the pipelines settings page you can find pipeline status and test coverage -badges for your project. The latest successful pipeline is used to read -the pipeline status and test coverage values. - -Visit the pipelines settings page in your project to see the exact link to -your badges. You can also see ways to embed the badge image in your HTML or Markdown -pages. +1. In the **Pipeline status** or **Coverage report** sections, view the URLs for the images.  @@ -286,7 +315,7 @@ Depending on the status of your pipeline, a badge can have the following values: - `canceled` - `unknown` -You can access a pipeline status badge image using the following link: +You can access a pipeline status badge image by using the following link: ```plaintext https://gitlab.example.com/<namespace>/<project>/badges/<branch>/pipeline.svg @@ -294,7 +323,7 @@ https://gitlab.example.com/<namespace>/<project>/badges/<branch>/pipeline.svg #### Display only non-skipped status -If you want the pipeline status badge to only display the last non-skipped status, you can use the `?ignore_skipped=true` query parameter: +To make the pipeline status badge display only the last non-skipped status, use the `?ignore_skipped=true` query parameter: ```plaintext https://gitlab.example.com/<namespace>/<project>/badges/<branch>/pipeline.svg?ignore_skipped=true @@ -302,20 +331,20 @@ https://gitlab.example.com/<namespace>/<project>/badges/<branch>/pipeline.svg?ig ### Test coverage report badge -GitLab makes it possible to define the regular expression for the [coverage report](#test-coverage-parsing), +You can define the regular expression for the [coverage report](#add-test-coverage-results-to-a-merge-request) that each job log is matched against. This means that each job in the pipeline can have the test coverage percentage value defined. -The test coverage badge can be accessed using following link: +To access the test coverage badge, use the following link: ```plaintext https://gitlab.example.com/<namespace>/<project>/badges/<branch>/coverage.svg ``` -If you would like to get the coverage report from a specific job, you can add +To get the coverage report from a specific job, add the `job=coverage_job_name` parameter to the URL. For example, the following Markdown code embeds the test coverage report badge of the `coverage` job -into your `README.md`: +in your `README.md`: ```markdown  |