diff options
Diffstat (limited to 'doc/ci/pipelines')
-rw-r--r-- | doc/ci/pipelines/cicd_minutes.md | 12 | ||||
-rw-r--r-- | doc/ci/pipelines/downstream_pipelines.md | 5 | ||||
-rw-r--r-- | doc/ci/pipelines/img/pipelines_settings_badges.png | bin | 21137 -> 0 bytes | |||
-rw-r--r-- | doc/ci/pipelines/index.md | 28 | ||||
-rw-r--r-- | doc/ci/pipelines/job_artifacts.md | 6 | ||||
-rw-r--r-- | doc/ci/pipelines/pipeline_architectures.md | 2 | ||||
-rw-r--r-- | doc/ci/pipelines/pipeline_efficiency.md | 4 | ||||
-rw-r--r-- | doc/ci/pipelines/settings.md | 145 |
8 files changed, 34 insertions, 168 deletions
diff --git a/doc/ci/pipelines/cicd_minutes.md b/doc/ci/pipelines/cicd_minutes.md index e69c510291d..4cbaa77b029 100644 --- a/doc/ci/pipelines/cicd_minutes.md +++ b/doc/ci/pipelines/cicd_minutes.md @@ -33,7 +33,7 @@ On self-managed GitLab instances: - Administrators can [assign more CI/CD minutes](#set-the-quota-of-cicd-minutes-for-a-specific-namespace) if a namespace uses all the CI/CD minutes in its monthly quota. -[Specific runners](../runners/runners_scope.md#specific-runners) are not subject to a quota of CI/CD minutes. +[Project runners](../runners/runners_scope.md#project-runners) are not subject to a quota of CI/CD minutes. ## Set the quota of CI/CD minutes for all namespaces @@ -111,7 +111,7 @@ subgroups, sorted in descending order of CI/CD minute usage. 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. +1. On the top bar, in the upper-right corner, select your avatar. 1. Select **Edit profile**. 1. On the left sidebar, select **Usage Quotas**. @@ -161,7 +161,7 @@ namespace. To purchase additional minutes for your personal namespace: -1. On the top bar, in the top right corner, select your avatar. +1. On the top bar, in the upper-right corner, select your avatar. 1. Select **Edit profile**. 1. On the left sidebar, select **Usage Quotas**. 1. Select **Buy additional minutes**. GitLab redirects you to the Customers Portal. @@ -216,9 +216,9 @@ The cost factors on self-managed instances are: #### Cost factor for community contributions to GitLab projects -Community contributors can use up to 300,000 minutes on shared runners when contributing to open source projects +Community contributors can use up to 300,000 minutes on shared runners when contributing to open source projects maintained by GitLab. The maximum of 300,000 minutes would only be possible if contributing exclusively to projects [part of the GitLab product](https://about.gitlab.com/handbook/engineering/metrics/#projects-that-are-part-of-the-product). The total number of minutes available on shared runners -is reduced by the CI/CD minutes used by pipelines from other projects. +is reduced by the CI/CD minutes used by pipelines from other projects. The 300,000 minutes applies to all SaaS tiers, and the cost factor calculation is: - `Monthly minute quota / 300,000 job duration minutes = Cost factor` @@ -288,7 +288,7 @@ processing new jobs. The grace period for running jobs is `1,000` CI/CD minutes. -Jobs on specific runners are not affected by the quota of CI/CD minutes. +Jobs on project runners are not affected by the quota of CI/CD minutes. ### GitLab SaaS usage notifications diff --git a/doc/ci/pipelines/downstream_pipelines.md b/doc/ci/pipelines/downstream_pipelines.md index 1ada4c4fac1..e4560cd882d 100644 --- a/doc/ci/pipelines/downstream_pipelines.md +++ b/doc/ci/pipelines/downstream_pipelines.md @@ -68,8 +68,8 @@ Multi-project pipelines: - Are visible in the downstream project's pipeline list. - Are independent, so there are no nesting limits. -Learn more in the "Cross-project Pipeline Triggering and Visualization" demo at -[GitLab@learn](https://about.gitlab.com/learn/), in the Continuous Integration section. +For more information, see the **Cross-project Pipeline Triggering and Visualization** demo at +[GitLab@learn](https://about.gitlab.com/learn/) in the **Continuous Integration** section. If you use a public project to trigger downstream pipelines in a private project, make sure there are no confidentiality problems. The upstream project's pipelines page @@ -473,6 +473,7 @@ a few different methods, based on where the variable is created or defined. ### Pass YAML-defined CI/CD variables You can use the `variables` keyword to pass CI/CD variables to a downstream pipeline. +These variables are "trigger variables" for [variable precedence](../variables/index.md#cicd-variable-precedence). For example: diff --git a/doc/ci/pipelines/img/pipelines_settings_badges.png b/doc/ci/pipelines/img/pipelines_settings_badges.png Binary files differdeleted file mode 100644 index 3bdc6374c15..00000000000 --- a/doc/ci/pipelines/img/pipelines_settings_badges.png +++ /dev/null diff --git a/doc/ci/pipelines/index.md b/doc/ci/pipelines/index.md index 324a2fa3ef9..fa04cb6cb92 100644 --- a/doc/ci/pipelines/index.md +++ b/doc/ci/pipelines/index.md @@ -136,7 +136,7 @@ and [view your pipeline status](https://marketplace.visualstudio.com/items?itemN Pipelines can be manually executed, with predefined or manually-specified [variables](../variables/index.md). -You might do this if the results of a pipeline (for example, a code build) are required outside the normal +You might do this if the results of a pipeline (for example, a code build) are required outside the standard operation of the pipeline. To execute a pipeline manually: @@ -145,7 +145,7 @@ To execute a pipeline manually: 1. On the left sidebar, select **CI/CD > Pipelines**. 1. Select **Run pipeline**. 1. In the **Run for branch name or tag** field, select the branch or tag to run the pipeline for. -1. Enter any [environment variables](../variables/index.md) required for the pipeline to run. +1. Enter any [CI/CD variables](../variables/index.md) required for the pipeline to run. You can set specific variables to have their [values prefilled in the form](#prefill-variables-in-manual-pipelines). 1. Select **Run pipeline**. @@ -163,32 +163,34 @@ information such as what the variable is used for, and what the acceptable value Job-level variables cannot be pre-filled. In manually-triggered pipelines, the **Run pipeline** page displays all pipeline-level variables -with a `description` defined in the `.gitlab-ci.yml` file. The description displays +that have a `description` defined in the `.gitlab-ci.yml` file. The description displays below the variable. -You can change the prefilled value, which overrides the value for that single pipeline run. -If you do not define a `value` for the variable in the configuration file, the variable still displays, +You can change the prefilled value, which [overrides the value](../variables/index.md#override-a-defined-cicd-variable) for that single pipeline run. +Any variables overridden by using this process are [expanded](../variables/index.md#prevent-cicd-variable-expansion) +and not [masked](../variables/index.md#mask-a-cicd-variable). +If you do not define a `value` for the variable in the configuration file, the variable name is still listed, but the value field is blank. For example: ```yaml variables: - TEST_SUITE: - description: "The test suite that will run. Valid options are: 'default', 'short', 'full'." - value: "default" + DEPLOY_CREDENTIALS: + description: "The deployment credentials." DEPLOY_ENVIRONMENT: description: "Select the deployment target. Valid options are: 'canary', 'staging', 'production', or a stable branch of your choice." + value: "canary" ``` In this example: -- `TEST_SUITE` is pre-filled in the **Run pipeline** page with `default`, - and the message explains the other options. -- `DEPLOY_ENVIRONMENT` is listed in the **Run pipeline** page, but with no value set. +- `DEPLOY_CREDENTIALS` is listed in the **Run pipeline** page, but with no value set. The user is expected to define the value each time the pipeline is run manually. +- `DEPLOY_ENVIRONMENT` is pre-filled in the **Run pipeline** page with `canary` as the default value, + and the message explains the other options. -##### Configure a list of selectable values for a prefilled variable +#### Configure a list of selectable prefilled variable values > - [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. @@ -425,7 +427,7 @@ You can group the jobs by: 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 normal. To see the jobs: +pipeline graph. The remaining jobs still run as usual. To see the jobs: - Select the pipeline, and the jobs are listed on the right side of the pipeline details page. - On the left sidebar, select **CI/CD > Jobs**. diff --git a/doc/ci/pipelines/job_artifacts.md b/doc/ci/pipelines/job_artifacts.md index bd788cfd3eb..75c9852d3d0 100644 --- a/doc/ci/pipelines/job_artifacts.md +++ b/doc/ci/pipelines/job_artifacts.md @@ -264,7 +264,7 @@ artifacts and log. You must be: To delete a job: 1. Go to a job's detail page. -1. On the top right of the job's log, select **Erase job log** (**{remove}**). +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 @@ -385,6 +385,10 @@ a project, you can disable this behavior to save space: 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 diff --git a/doc/ci/pipelines/pipeline_architectures.md b/doc/ci/pipelines/pipeline_architectures.md index 1e4d32fc331..e4a3416f60b 100644 --- a/doc/ci/pipelines/pipeline_architectures.md +++ b/doc/ci/pipelines/pipeline_architectures.md @@ -13,7 +13,7 @@ some of the important concepts related to them. You can structure your pipelines with different methods, each with their own advantages. These methods can be mixed and matched if needed: -- [Basic](#basic-pipelines): Good for straightforward projects where all the configuration is in one easy to find place. +- [Basic](#basic-pipelines): Good for straightforward projects where all the configuration is in one easy-to-find place. - [Directed Acyclic Graph](#directed-acyclic-graph-pipelines): Good for large, complex projects that need efficient execution. - [Parent-child pipelines](#parent-child-pipelines): Good for monorepos and projects with lots of independently defined components. diff --git a/doc/ci/pipelines/pipeline_efficiency.md b/doc/ci/pipelines/pipeline_efficiency.md index 0952fdf1f8f..0795005aa8e 100644 --- a/doc/ci/pipelines/pipeline_efficiency.md +++ b/doc/ci/pipelines/pipeline_efficiency.md @@ -101,7 +101,7 @@ representation of pipeline health. Instance administrators have access to additional [performance metrics and self-monitoring](../../administration/monitoring/index.md). -You can fetch specific pipeline health metrics from the [API](../../api/index.md). +You can fetch specific pipeline health metrics from the [API](../../api/rest/index.md). External monitoring tools can poll the API and verify pipeline health or collect metrics for long term SLA analytics. @@ -254,7 +254,7 @@ Document CI/CD pipeline problems and incidents in issues, including research don and solutions found. This helps onboarding new team members, and also helps identify recurring problems with CI pipeline efficiency. -### Learn More +### Related topics - [CI Monitoring Webcast Slides](https://docs.google.com/presentation/d/1ONwIIzRB7GWX-WOSziIIv8fz1ngqv77HO1yVfRooOHM/edit?usp=sharing) - [GitLab.com Monitoring Handbook](https://about.gitlab.com/handbook/engineering/monitoring/) diff --git a/doc/ci/pipelines/settings.md b/doc/ci/pipelines/settings.md index cd696d816d7..3633863915c 100644 --- a/doc/ci/pipelines/settings.md +++ b/doc/ci/pipelines/settings.md @@ -311,149 +311,8 @@ lein cloverage | perl -pe 's/\e\[?.*?[\@-~]//g' ## Pipeline badges -Pipeline badges indicate the pipeline status and a test coverage value -for your project. These badges are determined by the latest successful pipeline. - -## Latest release badge - -> [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/33368) in GitLab 14.8. - -A latest release badge indicates the latest release tag name for your project. -By default, the badge fetches the release sorted using the [`released_at`](../../api/releases/index.md#create-a-release) time. -Support for [`semver`](https://semver.org/) sorting is tracked [in this issue](https://gitlab.com/gitlab-org/gitlab/-/issues/352945). - -### View the code for the pipeline status, coverage reports, and latest release badges - -You can view the exact link for your badges. Then you can embed the badge in your HTML -or Markdown pages. - -1. On the top bar, select **Main menu > Projects** and find your project. -1. On the left sidebar, select **Settings > CI/CD**. -1. Expand **General pipelines**. -1. In the **Pipeline status**, **Coverage report**, or **Latest release** sections, view the URLs for the images. - -![Pipelines badges](img/pipelines_settings_badges.png) - -### Pipeline status badge - -Depending on the status of your pipeline, a badge can have the following values: - -- `pending` -- `running` -- `passed` -- `failed` -- `skipped` -- `manual` -- `canceled` -- `unknown` - -You can access a pipeline status badge image by using the following link: - -```plaintext -https://gitlab.example.com/<namespace>/<project>/badges/<branch>/pipeline.svg -``` - -#### Display only non-skipped status - -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 -``` - -### Test coverage report badge - -You can define the regular expression for the [coverage report](#merge-request-test-coverage-results) that each job log -is matched against. This means that each job in the pipeline can have the test coverage percentage value defined. - -To access the test coverage badge, use the following link: - -```plaintext -https://gitlab.example.com/<namespace>/<project>/badges/<branch>/coverage.svg -``` - -To get the coverage report from a specific job, add -the `job=coverage_job_name` parameter to the URL. For example, you can use code -similar to the following to add the test coverage report badge of the `coverage` job -to a Markdown file: - -```markdown -![coverage](https://gitlab.example.com/<namespace>/<project>/badges/<branch>/coverage.svg?job=coverage) -``` - -#### Test coverage report badge colors and limits - -The default colors and limits for the badge are as follows: - -- 95 up to and including 100% - good (`#4c1`) -- 90 up to 95% - acceptable (`#a3c51c`) -- 75 up to 90% - medium (`#dfb317`) -- 0 up to 75% - low (`#e05d44`) -- no coverage - unknown (`#9f9f9f`) - -NOTE: -*Up to* means up to, but not including, the upper bound. - -You can overwrite the limits by using the following additional parameters ([Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/28317) in GitLab 14.4): - -- `min_good` (default 95, can use any value between 3 and 100) -- `min_acceptable` (default 90, can use any value between 2 and min_good-1) -- `min_medium` (default 75, can use any value between 1 and min_acceptable-1) - -If an invalid boundary is set, GitLab automatically adjusts it to be valid. For example, -if `min_good` is set `80`, and `min_acceptable` is set to `85` (too high), GitLab automatically -sets `min_acceptable` to `79` (`min_good` - `1`). - -### Latest release badge - -When a release exists in your project, it shows the latest release tag name. If there is no release, -it shows `none`. - -You can access a latest release badge image by using the following link: - -```plaintext -https://gitlab.example.com/<namespace>/<project>/-/badges/release.svg -``` - -#### Sorting preferences - -By default, the latest release badge fetches the release using `release_at` time. The use of the query parameter `?order_by=release_at` is optional, and support for `?order_by=semver` is tracked [in this issue](https://gitlab.com/gitlab-org/gitlab/-/issues/352945): - -```plaintext -https://gitlab.example.com/<namespace>/<project>/-/badges/release.svg?order_by=release_at -``` - -### Badge styles - -Pipeline badges can be rendered in different styles by adding the `style=style_name` parameter to the URL. Two styles are available: - -- Flat (default): - - ```plaintext - https://gitlab.example.com/<namespace>/<project>/badges/<branch>/coverage.svg?style=flat - ``` - - ![Badge flat style](https://gitlab.com/gitlab-org/gitlab/badges/main/coverage.svg?job=coverage&style=flat) - -- Flat square ([Introduced](https://gitlab.com/gitlab-org/gitlab-foss/-/issues/30120) in GitLab 11.8): - - ```plaintext - https://gitlab.example.com/<namespace>/<project>/badges/<branch>/coverage.svg?style=flat-square - ``` - - ![Badge flat square style](https://gitlab.com/gitlab-org/gitlab/badges/main/coverage.svg?job=coverage&style=flat-square) - -### Custom badge text - -> [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/17555) in GitLab 13.1. - -The text for a badge can be customized to differentiate between multiple coverage jobs that run in the same pipeline. Customize the badge text and width by adding the `key_text=custom_text` and `key_width=custom_key_width` parameters to the URL: - -```plaintext -https://gitlab.com/gitlab-org/gitlab/badges/main/coverage.svg?job=karma&key_text=Frontend+Coverage&key_width=130 -``` - -![Badge with custom text and width](https://gitlab.com/gitlab-org/gitlab/badges/main/coverage.svg?job=karma&key_text=Frontend+Coverage&key_width=130) +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 |