diff options
| author | GitLab Bot <gitlab-bot@gitlab.com> | 2021-05-19 15:44:42 +0000 |
|---|---|---|
| committer | GitLab Bot <gitlab-bot@gitlab.com> | 2021-05-19 15:44:42 +0000 |
| commit | 4555e1b21c365ed8303ffb7a3325d773c9b8bf31 (patch) | |
| tree | 5423a1c7516cffe36384133ade12572cf709398d /doc/ci | |
| parent | e570267f2f6b326480d284e0164a6464ba4081bc (diff) | |
| download | gitlab-ce-4555e1b21c365ed8303ffb7a3325d773c9b8bf31.tar.gz | |
Add latest changes from gitlab-org/gitlab@13-12-stable-eev13.12.0-rc42
Diffstat (limited to 'doc/ci')
38 files changed, 729 insertions, 660 deletions
diff --git a/doc/ci/README.md b/doc/ci/README.md index b0ebbf920f9..30a6668dbfd 100644 --- a/doc/ci/README.md +++ b/doc/ci/README.md @@ -21,8 +21,6 @@ Out-of-the-box management systems can decrease hours spent on maintaining toolch Watch our ["Mastering continuous software development"](https://about.gitlab.com/webcast/mastering-ci-cd/) webcast to learn about continuous methods and how the GitLab built-in CI can help you simplify and scale software development. -## Overview - Continuous Integration works by pushing small code chunks to your application's codebase hosted in a Git repository, and to every push, run a pipeline of scripts to build, test, and validate the @@ -50,42 +48,6 @@ read the [Introduction to CI/CD with GitLab](introduction/index.md). <iframe src="https://www.youtube.com/embed/1iXFbchozdY" frameborder="0" allowfullscreen="true"> </iframe> </figure> -## Getting started - -GitLab CI/CD is configured by a file called `.gitlab-ci.yml` placed -at the repository's root. This file creates a [pipeline](pipelines/index.md), which runs for changes to the code in the repository. Pipelines consist of one or more stages that run in order and can each contain one or more jobs that run in parallel. These jobs (or scripts) get executed by the [GitLab Runner](https://docs.gitlab.com/runner/) agent. - -To get started with GitLab CI/CD, we recommend you read through -the following documents: - -- [Get started with GitLab CI/CD](quick_start/index.md). -- [Fundamental pipeline architectures](pipelines/pipeline_architectures.md). -- [GitLab CI/CD basic workflow](introduction/index.md#gitlab-cicd-workflow). -- [Step-by-step guide for writing `.gitlab-ci.yml` for the first time](../user/project/pages/getting_started/pages_from_scratch.md). - -If you're migrating from another CI/CD tool, check out our handy references: - -- [Migrating from CircleCI](migration/circleci.md) -- [Migrating from Jenkins](migration/jenkins.md) - -You can also get started by using one of the -[`.gitlab-ci.yml` templates](https://gitlab.com/gitlab-org/gitlab-foss/tree/master/lib/gitlab/ci/templates) -available through the UI. You can use them by creating a new file, -choosing a template that suits your application, and adjusting it -to your needs: - - - -While building your `.gitlab-ci.yml`, you can use the [CI/CD configuration visualization](pipeline_editor/index.md#visualize-ci-configuration) to facilitate your writing experience. - -For a broader overview, see the [CI/CD getting started](quick_start/index.md) guide. - -After you're familiar with how GitLab CI/CD works, see the -[`.gitlab-ci.yml` full reference](yaml/README.md) -for all the attributes you can set and use. - -GitLab CI/CD and [shared runners](runners/README.md#shared-runners) are enabled on GitLab.com and available for all users, limited only by the [pipeline quota](../user/gitlab_com/index.md#shared-runners). - ## Concepts GitLab CI/CD uses a number of concepts to describe and run your build and deploy. diff --git a/doc/ci/cloud_deployment/ecs/quick_start_guide.md b/doc/ci/cloud_deployment/ecs/quick_start_guide.md index b9ed38c2c03..a801be549df 100644 --- a/doc/ci/cloud_deployment/ecs/quick_start_guide.md +++ b/doc/ci/cloud_deployment/ecs/quick_start_guide.md @@ -65,7 +65,7 @@ GitLab [Auto Build](../../../topics/autodevops/stages.md#auto-build) and [Container Registry](../../../user/packages/container_registry/index.md). 1. Go to **ecs-demo** project on GitLab. -1. Click **Setup up CI/CD**. It brings you to a [`.gitlab-ci.yml`](../../README.md#getting-started) +1. Click **Setup up CI/CD**. It brings you to a `.gitlab-ci.yml` creation form. 1. Copy and paste the following content into the empty `.gitlab-ci.yml`. This defines [a pipeline for continuous deployment to ECS](../index.md#deploy-your-application-to-the-aws-elastic-container-service-ecs). @@ -77,9 +77,9 @@ and [Container Registry](../../../user/packages/container_registry/index.md). 1. Click **Commit Changes**. It automatically triggers a new pipeline. In this pipeline, the `build` job containerizes the application and pushes the image to [GitLab Container Registry](../../../user/packages/container_registry/index.md). - +  - + 1. Visit **Packages & Registries > Container Registry**. Make sure the application image has been pushed. @@ -232,7 +232,7 @@ These variables are injected into the pipeline jobs and can access the ECS API. Change a file in the project and see if it's reflected in the demo application on ECS: 1. Go to **ecs-demo** project on GitLab. -1. Open the file at **app > views > welcome > index.html.erb**. +1. Open the file at **app > views > welcome > `index.html.erb`**. 1. Click **Edit**. 1. Change the text to `You're on ECS!`. 1. Click **Commit Changes**. This automatically triggers a new pipeline. Wait until it finishes. diff --git a/doc/ci/directed_acyclic_graph/index.md b/doc/ci/directed_acyclic_graph/index.md index 5089aa6c9a5..dab9d8b78ae 100644 --- a/doc/ci/directed_acyclic_graph/index.md +++ b/doc/ci/directed_acyclic_graph/index.md @@ -94,3 +94,5 @@ To see the needs visualization, click on the **Needs** tab when viewing a pipeli Clicking a node highlights all the job paths it depends on.  + +You can also see `needs` relationships in [full pipeline graphs](../pipelines/index.md#view-full-pipeline-graph). diff --git a/doc/ci/environments/deployment_safety.md b/doc/ci/environments/deployment_safety.md index e38d9031ffd..6fda6bb0d8b 100644 --- a/doc/ci/environments/deployment_safety.md +++ b/doc/ci/environments/deployment_safety.md @@ -154,7 +154,7 @@ If you have multiple jobs for the same environment (including non-deployment job build:service-a: environment: name: production - + build:service-b: environment: name: production diff --git a/doc/ci/environments/index.md b/doc/ci/environments/index.md index 55d83887423..06618a820db 100644 --- a/doc/ci/environments/index.md +++ b/doc/ci/environments/index.md @@ -400,8 +400,8 @@ stop_review: when: manual ``` -Both jobs must have the same [`rules`](../yaml/README.md#onlyexcept-basic) -or [`only/except`](../yaml/README.md#onlyexcept-basic) configuration. Otherwise, +Both jobs must have the same [`rules`](../yaml/README.md#only--except) +or [`only/except`](../yaml/README.md#only--except) configuration. Otherwise, the `stop_review` job might not be included in all pipelines that include the `deploy_review` job, and you cannot trigger `action: stop` to stop the environment automatically. @@ -676,6 +676,7 @@ fetch = +refs/environments/*:refs/remotes/origin/environments/* > - [Introduced](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/2112) in [GitLab Premium](https://about.gitlab.com/pricing/) 9.4. > - [Environment scoping for CI/CD variables was moved to all tiers](https://gitlab.com/gitlab-org/gitlab-foss/-/merge_requests/30779) in GitLab 12.2. +> - [Environment scoping for Group CI/CD variables](https://gitlab.com/gitlab-org/gitlab/-/issues/2874) added to GitLab Premium in 13.11. You can limit the environment scope of a CI/CD variable by defining which environments it can be available for. diff --git a/doc/ci/examples/artifactory_and_gitlab/index.md b/doc/ci/examples/artifactory_and_gitlab/index.md deleted file mode 100644 index a1a7de26cf2..00000000000 --- a/doc/ci/examples/artifactory_and_gitlab/index.md +++ /dev/null @@ -1,8 +0,0 @@ ---- -redirect_to: '../README.md#contributed-examples' ---- - -This document was moved to [another location](../README.md#contributed-examples). - -<!-- This redirect file can be deleted after 2021-04-18. --> -<!-- Before deletion, see: https://docs.gitlab.com/ee/development/documentation/#move-or-rename-a-page --> diff --git a/doc/ci/examples/deploy_spring_boot_to_cloud_foundry/index.md b/doc/ci/examples/deploy_spring_boot_to_cloud_foundry/index.md deleted file mode 100644 index a1a7de26cf2..00000000000 --- a/doc/ci/examples/deploy_spring_boot_to_cloud_foundry/index.md +++ /dev/null @@ -1,8 +0,0 @@ ---- -redirect_to: '../README.md#contributed-examples' ---- - -This document was moved to [another location](../README.md#contributed-examples). - -<!-- This redirect file can be deleted after 2021-04-18. --> -<!-- Before deletion, see: https://docs.gitlab.com/ee/development/documentation/#move-or-rename-a-page --> diff --git a/doc/ci/examples/devops_and_game_dev_with_gitlab_ci_cd/index.md b/doc/ci/examples/devops_and_game_dev_with_gitlab_ci_cd/index.md deleted file mode 100644 index 9408c26f06f..00000000000 --- a/doc/ci/examples/devops_and_game_dev_with_gitlab_ci_cd/index.md +++ /dev/null @@ -1,8 +0,0 @@ ---- -redirect_to: '../README.md#contributed-examples' ---- - -This document was moved to [another location](../README.md#contributed-examples). - -<!-- This redirect file can be deleted after 2021-04-19. --> -<!-- Before deletion, see: https://docs.gitlab.com/ee/development/documentation/#move-or-rename-a-page --> diff --git a/doc/ci/examples/test-scala-application.md b/doc/ci/examples/test-scala-application.md deleted file mode 100644 index 057b950289d..00000000000 --- a/doc/ci/examples/test-scala-application.md +++ /dev/null @@ -1,8 +0,0 @@ ---- -redirect_to: 'README.md#contributed-examples' ---- - -This document was moved to [another location](README.md#contributed-examples). - -<!-- This redirect file can be deleted after 2021-04-18. --> -<!-- Before deletion, see: https://docs.gitlab.com/ee/development/documentation/#move-or-rename-a-page --> diff --git a/doc/ci/examples/test_phoenix_app_with_gitlab_ci_cd/index.md b/doc/ci/examples/test_phoenix_app_with_gitlab_ci_cd/index.md deleted file mode 100644 index 057b6ec126f..00000000000 --- a/doc/ci/examples/test_phoenix_app_with_gitlab_ci_cd/index.md +++ /dev/null @@ -1,8 +0,0 @@ ---- -redirect_to: '../README.md' ---- - -This example is no longer available. [View other examples](../README.md). - -<!-- This redirect file can be deleted after <2021-04-05>. --> -<!-- Before deletion, see: https://docs.gitlab.com/ee/development/documentation/#move-or-rename-a-page --> diff --git a/doc/ci/jobs/index.md b/doc/ci/jobs/index.md index 1a31db09c92..a20fa1f8aa9 100644 --- a/doc/ci/jobs/index.md +++ b/doc/ci/jobs/index.md @@ -65,7 +65,7 @@ you can also see the reason it failed on the Job detail page. The order of jobs in a pipeline depends on the type of pipeline graph. -- For [regular pipeline graphs](../pipelines/index.md#regular-pipeline-graphs), jobs are sorted by name. +- For [full pipeline graphs](../pipelines/index.md#view-full-pipeline-graph), jobs are sorted by name. - For [pipeline mini graphs](../pipelines/index.md#pipeline-mini-graphs), jobs are sorted by severity and then by name. The order of severity is: diff --git a/doc/ci/jobs/job_control.md b/doc/ci/jobs/job_control.md new file mode 100644 index 00000000000..6e9197c223b --- /dev/null +++ b/doc/ci/jobs/job_control.md @@ -0,0 +1,317 @@ +--- +stage: Verify +group: Continuous Integration +info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/engineering/ux/technical-writing/#assignments +--- + +# Choose when to run jobs **(FREE)** + +When a new pipeline starts, GitLab checks the pipeline configuration to determine +which jobs should run in that pipeline. You can configure jobs to run depending on +the status of variables, the pipeline type, and so on. + +To configure a job to be included or excluded from certain pipelines, you can use: + +- [`rules`](../yaml/README.md#rules) +- [`only`](../yaml/README.md#only--except) +- [`except`](../yaml/README.md#only--except) + +Use [`needs`](../yaml/README.md#needs) to configure a job to run as soon as the +earlier jobs it depends on finish running. + +## Specify when jobs run with `only` and `except` + +You can use [`only`](../yaml/README.md#only--except) and [`except`](../yaml/README.md#only--except) +to control when to add jobs to pipelines. + +- Use `only` to define when a job runs. +- Use `except` to define when a job **does not** run. + +### `only:refs` / `except:refs` examples + +`only` or `except` used without `refs` is the same as +[`only:refs` / `except/refs`](../yaml/README.md#onlyrefs--exceptrefs) + +In the following example, `job` runs only for: + +- Git tags +- [Triggers](../triggers/README.md#trigger-token) +- [Scheduled pipelines](../pipelines/schedules.md) + +```yaml +job: + # use special keywords + only: + - tags + - triggers + - schedules +``` + +To execute jobs only for the parent repository and not forks: + +```yaml +job: + only: + - branches@gitlab-org/gitlab + except: + - main@gitlab-org/gitlab + - /^release/.*$/@gitlab-org/gitlab +``` + +This example runs `job` for all branches on `gitlab-org/gitlab`, +except `main` and branches that start with `release/`. + +### `only: variables` / `except: variables` examples + +You can use [`except:variables`](../yaml/README.md#onlyvariables--exceptvariables) to exclude jobs based on a commit message: + +```yaml +end-to-end: + script: rake test:end-to-end + except: + variables: + - $CI_COMMIT_MESSAGE =~ /skip-end-to-end-tests/ +``` + +You can use [parentheses](../variables/README.md#parentheses) with `&&` and `||` +to build more complicated variable expressions: + +```yaml +job1: + script: + - echo This rule uses parentheses. + only: + variables: + - ($CI_COMMIT_BRANCH == "master" || $CI_COMMIT_BRANCH == "develop") && $MY_VARIABLE +``` + +### `only:changes` / `except:changes` examples + +You can skip a job if a change is detected in any file with a +`.md` extension in the root directory of the repository: + +```yaml +build: + script: npm run build + except: + changes: + - "*.md" +``` + +If you change multiple files, but only one file ends in `.md`, +the `build` job is still skipped. The job does not run for any of the files. + +Read more about how to use `only:changes` and `except:changes`: + +- [New branches or tags *without* pipelines for merge requests](#use-onlychanges-without-pipelines-for-merge-requests). +- [Scheduled pipelines](#use-onlychanges-with-scheduled-pipelines). + +#### Use `only:changes` with pipelines for merge requests + +With [pipelines for merge requests](../merge_request_pipelines/index.md), +it's possible to define a job to be created based on files modified +in a merge request. + +Use this keyword with `only: [merge_requests]` so GitLab can find the correct base +SHA of the source branch. File differences are correctly calculated from any further +commits, and all changes in the merge requests are properly tested in pipelines. + +For example: + +```yaml +docker build service one: + script: docker build -t my-service-one-image:$CI_COMMIT_REF_SLUG . + only: + refs: + - merge_requests + changes: + - Dockerfile + - service-one/**/* +``` + +In this scenario, if a merge request changes +files in the `service-one` directory or the `Dockerfile`, GitLab creates +the `docker build service one` job. + +For example: + +```yaml +docker build service one: + script: docker build -t my-service-one-image:$CI_COMMIT_REF_SLUG . + only: + changes: + - Dockerfile + - service-one/**/* +``` + +In this example, the pipeline might fail because of changes to a file in `service-one/**/*`. + +A later commit that doesn't have changes in `service-one/**/*` +but does have changes to the `Dockerfile` can pass. The job +only tests the changes to the `Dockerfile`. + +GitLab checks the **most recent pipeline** that **passed**. If the merge request is mergeable, +it doesn't matter that an earlier pipeline failed because of a change that has not been corrected. + +When you use this configuration, ensure that the most recent pipeline +properly corrects any failures from previous pipelines. + +#### Use `only:changes` without pipelines for merge requests + +Without [pipelines for merge requests](../merge_request_pipelines/index.md), pipelines +run on branches or tags that don't have an explicit association with a merge request. +In this case, a previous SHA is used to calculate the diff, which is equivalent to `git diff HEAD~`. +This can result in some unexpected behavior, including: + +- When pushing a new branch or a new tag to GitLab, the policy always evaluates to true. +- When pushing a new commit, the changed files are calculated by using the previous commit + as the base SHA. + +#### Use `only:changes` with scheduled pipelines + +`only:changes` always evaluates as true in [Scheduled pipelines](../pipelines/schedules.md). +All files are considered to have changed when a scheduled pipeline runs. + +### Combine multiple keywords with `only` or `except` + +If you use multiple keywords with `only` or `except`, the keywords are evaluated +as a single conjoined expression. That is: + +- `only:` includes the job if **all** of the keys have at least one condition that matches. +- `except:` excludes the job if **any** of the keys have at least one condition that matches. + +With `only`, individual keys are logically joined by an `AND`. A job is added to +the pipeline if the following is true: + +- `(any listed refs are true) AND (any listed variables are true) AND (any listed changes are true) AND (any chosen Kubernetes status matches)` + +In the following example, the `test` job is only created when **all** of the following are true: + +- The pipeline is [scheduled](../pipelines/schedules.md) **or** runs for `main`. +- The `variables` keyword matches. +- The `kubernetes` service is active on the project. + +```yaml +test: + script: npm run test + only: + refs: + - main + - schedules + variables: + - $CI_COMMIT_MESSAGE =~ /run-end-to-end-tests/ + kubernetes: active +``` + +With `except`, individual keys are logically joined by an `OR`. A job is **not** +added if the following is true: + +- `(any listed refs are true) OR (any listed variables are true) OR (any listed changes are true) OR (a chosen Kubernetes status matches)` + +In the following example, the `test` job is **not** created when **any** of the following are true: + +- The pipeline runs for the `main` branch. +- There are changes to the `README.md` file in the root directory of the repository. + +```yaml +test: + script: npm run test + except: + refs: + - main + changes: + - "README.md" +``` + +## Use predefined CI/CD variables to run jobs only in specific pipeline types + +You can use [predefined CI/CD variables](../variables/predefined_variables.md) to choose +which pipeline types jobs run in, with: + +- [`rules`](../yaml/README.md#rules) +- [`only:variables`](../yaml/README.md#onlyvariables--exceptvariables) +- [`except:variables`](../yaml/README.md#onlyvariables--exceptvariables) + +The following table lists some of the variables that you can use, and the pipeline +types the variables can control for: + +- Branch pipelines that run for Git `push` events to a branch, like new commits or tags. +- Tag pipelines that run only when a new Git tag is pushed to a branch. +- [Merge request pipelines](../merge_request_pipelines/index.md) that run for changes + to a merge request, like new commits or selecting the **Run pipeline** button + in a merge request's pipelines tab. +- [Scheduled pipelines](../pipelines/schedules.md). + +| Variables | Branch | Tag | Merge request | Scheduled | +|--------------------------------------------|--------|-----|---------------|-----------| +| `CI_COMMIT_BRANCH` | Yes | | | Yes | +| `CI_COMMIT_TAG` | | Yes | | Yes, if the scheduled pipeline is configured to run on a tag. | +| `CI_PIPELINE_SOURCE = push` | Yes | Yes | | | +| `CI_PIPELINE_SOURCE = scheduled` | | | | Yes | +| `CI_PIPELINE_SOURCE = merge_request_event` | | | Yes | | +| `CI_MERGE_REQUEST_IID` | | | Yes | | + +For example, to configure a job to run for merge request pipelines and scheduled pipelines, +but not branch or tag pipelines: + +```yaml +job1: + script: + - echo + rules: + - if: $CI_PIPELINE_SOURCE == "merge_request_event" + - if: $CI_PIPELINE_SOURCE == "scheduled" + - if: $CI_PIPELINE_SOURCE == "push" + when: never +``` + +## Regular expressions + +The `@` symbol denotes the beginning of a ref's repository path. +To match a ref name that contains the `@` character in a regular expression, +you must use the hex character code match `\x40`. + +Only the tag or branch name can be matched by a regular expression. +The repository path, if given, is always matched literally. + +To match the tag or branch name, +the entire ref name part of the pattern must be a regular expression surrounded by `/`. +For example, you can't use `issue-/.*/` to match all tag names or branch names +that begin with `issue-`, but you can use `/issue-.*/`. + +Regular expression flags must be appended after the closing `/`. Pattern matching +is case-sensitive by default. Use the `i` flag modifier, like `/pattern/i`, to make +a pattern case-insensitive: + +```yaml +job: + # use regexp + only: + - /^issue-.*$/i + # use special keyword + except: + - branches +``` + +Use anchors `^` and `$` to avoid the regular expression +matching only a substring of the tag name or branch name. +For example, `/^issue-.*$/` is equivalent to `/^issue-/`, +while just `/issue/` would also match a branch called `severe-issues`. + +### `only` / `except` regex syntax + +In GitLab 11.9.4, GitLab began internally converting the regexp used +in `only` and `except` keywords to [RE2](https://github.com/google/re2/wiki/Syntax). + +[RE2](https://github.com/google/re2/wiki/Syntax) limits the set of available features +due to computational complexity, and some features, like negative lookaheads, became unavailable. +Only a subset of features provided by [Ruby Regexp](https://ruby-doc.org/core/Regexp.html) +are now supported. + +From GitLab 11.9.7 to GitLab 12.0, GitLab provided a feature flag to +let you use unsafe regexp syntax. After migrating to safe syntax, you should disable +this feature flag again: + +```ruby +Feature.enable(:allow_unsafe_ruby_regexp) +``` diff --git a/doc/ci/merge_request_pipelines/index.md b/doc/ci/merge_request_pipelines/index.md index 024155bdde7..a55804432ca 100644 --- a/doc/ci/merge_request_pipelines/index.md +++ b/doc/ci/merge_request_pipelines/index.md @@ -137,7 +137,7 @@ save resources. #### Excluding certain branches Pipelines for merge requests require special treatment when -using [`only`/`except`](../yaml/README.md#onlyexcept-basic). Unlike ordinary +using [`only`/`except`](../yaml/README.md#only--except). Unlike ordinary branch refs (for example `refs/heads/my-feature-branch`), merge request refs use a special Git reference that looks like `refs/merge-requests/:iid/head`. Because of this, the following configuration will **not** work as expected: @@ -153,7 +153,7 @@ Instead, you can use the [`$CI_COMMIT_REF_NAME` predefined environment variable](../variables/predefined_variables.md) in combination with -[`only:variables`](../yaml/README.md#onlyvariablesexceptvariables) to +[`only:variables`](../yaml/README.md#onlyvariables--exceptvariables) to accomplish this behavior: ```yaml diff --git a/doc/ci/migration/jenkins.md b/doc/ci/migration/jenkins.md index c7dd4a46137..c278160d5ee 100644 --- a/doc/ci/migration/jenkins.md +++ b/doc/ci/migration/jenkins.md @@ -349,8 +349,8 @@ variable entry. GitLab does support a [`when` keyword](../yaml/README.md#when) which is used to indicate when a job should be run in case of (or despite) failure, but most of the logic for controlling pipelines can be found in -our very powerful [`only/except` rules system](../yaml/README.md#onlyexcept-basic) -(see also our [advanced syntax](../yaml/README.md#onlyexcept-basic)): +our very powerful [`only/except` rules system](../yaml/README.md#only--except) +(see also our [advanced syntax](../yaml/README.md#only--except)): ```yaml my_job: diff --git a/doc/ci/multi_project_pipelines.md b/doc/ci/multi_project_pipelines.md index 28505fb7519..c1e552f5a9d 100644 --- a/doc/ci/multi_project_pipelines.md +++ b/doc/ci/multi_project_pipelines.md @@ -67,7 +67,7 @@ When using: - CI/CD Variables or [`rules`](yaml/README.md#rulesif) to control job behavior, the value of the [`$CI_PIPELINE_SOURCE` predefined variable](variables/predefined_variables.md) is `pipeline` for multi-project pipeline triggered through the API with `CI_JOB_TOKEN`. -- [`only/except`](yaml/README.md#onlyexcept-basic) to control job behavior, use the +- [`only/except`](yaml/README.md#only--except) to control job behavior, use the `pipelines` keyword. ## Creating multi-project pipelines from `.gitlab-ci.yml` @@ -113,7 +113,7 @@ When using: the [`$CI_PIPELINE_SOURCE` predefined variable](variables/predefined_variables.md) is `pipeline` for multi-project pipelines triggered with a bridge job (using the [`trigger:`](yaml/README.md#trigger) keyword). -- [`only/except`](yaml/README.md#onlyexcept-basic) to control job behavior, use the +- [`only/except`](yaml/README.md#only--except) to control job behavior, use the `pipelines` keyword. In the example, `staging` is marked as successful as soon as a downstream pipeline diff --git a/doc/ci/parent_child_pipelines.md b/doc/ci/parent_child_pipelines.md index bc1c02bc48c..1a0421258fd 100644 --- a/doc/ci/parent_child_pipelines.md +++ b/doc/ci/parent_child_pipelines.md @@ -38,7 +38,7 @@ set of concurrently running child pipelines, but within the same project: Child pipelines work well with other GitLab CI/CD features: -- Use [`only: changes`](yaml/README.md#onlychangesexceptchanges) to trigger pipelines only when +- Use [`only: changes`](yaml/README.md#onlychanges--exceptchanges) to trigger pipelines only when certain files change. This is useful for monorepos, for example. - Since the parent pipeline in `.gitlab-ci.yml` and the child pipeline run as normal pipelines, they can have their own behaviors and sequencing in relation to triggers. diff --git a/doc/ci/pipeline_editor/index.md b/doc/ci/pipeline_editor/index.md index 57aea5d493b..1527a05d3d7 100644 --- a/doc/ci/pipeline_editor/index.md +++ b/doc/ci/pipeline_editor/index.md @@ -15,6 +15,7 @@ the `.gitlab-ci.yml` file in the root of your repository. To access the editor, From the pipeline editor page you can: +- Select the branch to work from. [Introduced in GitLab 13.12](https://gitlab.com/gitlab-org/gitlab/-/issues/326189), disabled by default. - [Validate](#validate-ci-configuration) your configuration syntax while editing the file. - Do a deeper [lint](#lint-ci-configuration) of your configuration, that verifies it with any configuration added with the [`include`](../yaml/README.md#include) keyword. @@ -53,14 +54,7 @@ reflected in the CI lint. It displays the same results as the existing [CI Lint > - [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/241722) in GitLab 13.5. > - [Moved to **CI/CD > Editor**](https://gitlab.com/gitlab-org/gitlab/-/issues/263141) in GitLab 13.7. -> - It was [deployed behind a feature flag](../../user/feature_flags.md), disabled by default. -> - [Became enabled by default](https://gitlab.com/gitlab-org/gitlab/-/issues/290117) in GitLab 13.8. -> - It's enabled on GitLab.com. -> - It's recommended for production use. -> - To use it in GitLab self-managed instances, ask a GitLab administrator to [enable it](#enable-or-disable-cicd-configuration-visualization). **(FREE SELF)** - -WARNING: -This feature might not be available to you. Check the **version history** note above for details. +> - [Feature flag removed](https://gitlab.com/gitlab-org/gitlab/-/issues/290117) in GitLab 13.12. To view a visualization of your `gitlab-ci.yml` configuration, in your project, go to **CI/CD > Editor**, and then select the **Visualize** tab. The @@ -77,30 +71,10 @@ Hover over a job to highlight its `needs` relationships: If the configuration does not have any `needs` relationships, then no lines are drawn because each job depends only on the previous stage being completed successfully. -### Enable or disable CI/CD configuration visualization **(FREE SELF)** - -CI/CD configuration visualization is under development but ready for production use. -It is deployed behind a feature flag that is **enabled by default**. -[GitLab administrators with access to the GitLab Rails console](../../administration/feature_flags.md) -can opt to disable it. - -To disable it: - -```ruby -Feature.disable(:ci_config_visualization_tab) -``` - -To enable it: - -```ruby -Feature.enable(:ci_config_visualization_tab) -``` - ## View expanded configuration > - [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/246801) in GitLab 13.9. -> - It is [deployed behind a feature flag](../../user/feature_flags.md), enabled by default. -> - To use it in GitLab self-managed instances, ask a GitLab administrator to [enable it](#enable-or-disable-expanded-configuration). **(FREE SELF)** +> - [Feature flag removed](https://gitlab.com/gitlab-org/gitlab/-/issues/301103) in GitLab 13.12. To view the fully expanded CI/CD configuration as one combined file, go to the pipeline editor's **View merged YAML** tab. This tab displays an expanded configuration @@ -111,25 +85,6 @@ where: [extended configuration merged into the job](../yaml/README.md#merge-details). - YAML anchors are [replaced with the linked configuration](../yaml/README.md#anchors). -### Enable or disable expanded configuration **(FREE SELF)** - -Expanded CI/CD configuration is under development and not ready for production use. -It is deployed behind a feature flag that is **enabled by default**. -[GitLab administrators with access to the GitLab Rails console](../../administration/feature_flags.md) -can opt to enable it. - -To disable it: - -```ruby -Feature.disable(:ci_config_merged_tab) -``` - -To enable it: - -```ruby -Feature.enable(:ci_config_merged_tab) -``` - ## Commit changes to CI configuration The commit form appears at the bottom of each tab in the editor so you can commit diff --git a/doc/ci/pipelines/img/pipelines_graph_dependency_view_hover_v13_12.png b/doc/ci/pipelines/img/pipelines_graph_dependency_view_hover_v13_12.png Binary files differnew file mode 100644 index 00000000000..e73845b39b0 --- /dev/null +++ b/doc/ci/pipelines/img/pipelines_graph_dependency_view_hover_v13_12.png diff --git a/doc/ci/pipelines/img/pipelines_graph_dependency_view_links_v13_12.png b/doc/ci/pipelines/img/pipelines_graph_dependency_view_links_v13_12.png Binary files differnew file mode 100644 index 00000000000..1ce77881bc4 --- /dev/null +++ b/doc/ci/pipelines/img/pipelines_graph_dependency_view_links_v13_12.png diff --git a/doc/ci/pipelines/img/pipelines_graph_dependency_view_v13_12.png b/doc/ci/pipelines/img/pipelines_graph_dependency_view_v13_12.png Binary files differnew file mode 100644 index 00000000000..41840108441 --- /dev/null +++ b/doc/ci/pipelines/img/pipelines_graph_dependency_view_v13_12.png diff --git a/doc/ci/pipelines/img/pipelines_graph_stage_view_v13_12.png b/doc/ci/pipelines/img/pipelines_graph_stage_view_v13_12.png Binary files differnew file mode 100644 index 00000000000..d7d8f3c63d2 --- /dev/null +++ b/doc/ci/pipelines/img/pipelines_graph_stage_view_v13_12.png diff --git a/doc/ci/pipelines/img/pipelines_v13_11.png b/doc/ci/pipelines/img/pipelines_v13_11.png Binary files differdeleted file mode 100644 index 8981f4ce860..00000000000 --- a/doc/ci/pipelines/img/pipelines_v13_11.png +++ /dev/null diff --git a/doc/ci/pipelines/index.md b/doc/ci/pipelines/index.md index 6d013a43583..fa8a4cedf6f 100644 --- a/doc/ci/pipelines/index.md +++ b/doc/ci/pipelines/index.md @@ -325,23 +325,81 @@ Pipelines can be complex structures with many sequential and parallel jobs. To make it easier to understand the flow of a pipeline, GitLab has pipeline graphs for viewing pipelines and their statuses. -Pipeline graphs can be displayed in two different ways, depending on the page you +Pipeline graphs can be displayed as a large graph or a miniature representation, depending on the page you access the graph from. GitLab capitalizes the stages' names in the pipeline graphs. -### Regular pipeline graphs +### View full pipeline graph -> - [Visualization improved](https://gitlab.com/gitlab-org/gitlab/-/issues/276949) in GitLab 13.11. +> - [Visualization improvements introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/276949) in GitLab 13.11. -Regular pipeline graphs show the names of the jobs in each stage. Regular pipeline graphs can -be found when you are on a [single pipeline page](#view-pipelines). For example: +The [pipeline details page](#view-pipelines) displays the full pipeline graph of +all the jobs in the pipeline. - +You can group the jobs by: + +- Stage, which arranges jobs in the same stage together in the same column. + +  + +- [Job dependencies](#view-job-dependencies-in-the-pipeline-graph), which arranges + jobs based on their [`needs`](../yaml/README.md#needs) dependencies. [Multi-project pipeline graphs](../multi_project_pipelines.md#multi-project-pipeline-visualization) help you visualize the entire pipeline, including all cross-project inter-dependencies. **(PREMIUM)** +### View job dependencies in the pipeline graph + +> - [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/298973) in GitLab 13.12. +> - [Deployed behind a feature flag](../../user/feature_flags.md), disabled by default. +> - [Enabled by default](https://gitlab.com/gitlab-org/gitlab/-/issues/328538) in GitLab 13.12. +> - Enabled on GitLab.com. +> - Recommended for production use. +> - To disable in GitLab self-managed instances, ask a GitLab administrator to [disable it](#enable-or-disable-job-dependency-view). **(FREE SELF)** + +This in-development feature might not be available for your use. There can be +[risks when enabling features still in development](../../user/feature_flags.md#risks-when-enabling-features-still-in-development). +Refer to this feature's version history for more details. + +You can arrange jobs in the pipeline graph based on their [`needs`](../yaml/README.md#needs) +dependencies. + +Jobs in the leftmost column run first, and jobs that depend on them are grouped in the next columns. + +For example, `build-job2` depends only on jobs in the first column, so it displays +in the second column from the left. `deploy-job2` depends on jobs in both the first +and second column and displays in the third column: + + + +To add lines that show the `needs` relationships between jobs, select the **Show dependencies** toggle. +These lines are similar to the [needs visualization](../directed_acyclic_graph/index.md#needs-visualization): + + + +To see the full `needs` dependency tree for a job, hover over it: + + + +#### Enable or disable job dependency view **(FREE SELF)** + +The job dependency view is deployed behind a feature flag that is **enabled by default**. +[GitLab administrators with access to the GitLab Rails console](../../administration/feature_flags.md) +can disable it. + +To enable it: + +```ruby +Feature.enable(:pipeline_graph_layers_view) +``` + +To disable it: + +```ruby +Feature.disable(:pipeline_graph_layers_view) +``` + ### Pipeline mini graphs Pipeline mini graphs take less space and can tell you at a @@ -356,6 +414,8 @@ Pipeline mini graphs allow you to see all related jobs for a single commit and t of each stage of your pipeline. This allows you to quickly see what failed and fix it. +Pipeline mini graphs only display jobs by stage. + Stages in pipeline mini graphs are collapsible. Hover your mouse over them and click to expand their jobs. | Mini graph | Mini graph expanded | diff --git a/doc/ci/pipelines/job_artifacts.md b/doc/ci/pipelines/job_artifacts.md index fa97f9bd75d..76f05f5e1e7 100644 --- a/doc/ci/pipelines/job_artifacts.md +++ b/doc/ci/pipelines/job_artifacts.md @@ -118,7 +118,7 @@ job with the same name, the job artifact from the parent pipeline is returned. ## Access the latest job artifacts by URL -You can download the latest job artifacts by using a URL. +You can download job artifacts from the latest successful pipeline by using a URL. To download the whole artifacts archive: @@ -173,9 +173,8 @@ https://gitlab.com/gitlab-org/gitlab/-/jobs/artifacts/master/file/htmlcov/index. ## When job artifacts are deleted -By default, the latest job artifacts from the most recent successful jobs are never deleted. -If a job is configured with [`expire_in`](../yaml/README.md#artifactsexpire_in), -its artifacts only expire if a more recent artifact exists. +See the [`expire_in`](../yaml/README.md#artifactsexpire_in) documentation for information on when +job artifacts are deleted. ### Keep artifacts from most recent successful jobs diff --git a/doc/ci/pipelines/pipeline_artifacts.md b/doc/ci/pipelines/pipeline_artifacts.md index e405258092d..bc770dd3d90 100644 --- a/doc/ci/pipelines/pipeline_artifacts.md +++ b/doc/ci/pipelines/pipeline_artifacts.md @@ -15,4 +15,7 @@ Pipeline artifacts are used by the [test coverage visualization feature](../../u Pipeline artifacts are saved to disk or object storage. They count towards a project's [storage usage quota](../../user/usage_quotas.md#storage-usage-quota). The **Artifacts** on the Usage Quotas page is the sum of all job artifacts and pipeline artifacts. -Pipeline artifacts are erased after one week. +## When pipeline artifacts are deleted + +See the [`expire_in`](../yaml/README.md#artifactsexpire_in) documentation for information on when +pipeline artifacts are deleted. diff --git a/doc/ci/pipelines/pipeline_efficiency.md b/doc/ci/pipelines/pipeline_efficiency.md index faebf40462e..2deb3b27748 100644 --- a/doc/ci/pipelines/pipeline_efficiency.md +++ b/doc/ci/pipelines/pipeline_efficiency.md @@ -110,6 +110,8 @@ and get the pipeline status and duration. In combination with a Grafana dashboar this helps build an actionable view for your operations team. Metric graphs can also be embedded into incidents making problem resolving easier. Additionally, it can also export metrics about jobs and environments. +If you use the GitLab CI Pipelines Exporter, you should start with the [example configuration](https://github.com/mvisonneau/gitlab-ci-pipelines-exporter/blob/main/docs/configuration_syntax.md). +  Alternatively, you can use a monitoring tool that can execute scripts, like diff --git a/doc/ci/pipelines/schedules.md b/doc/ci/pipelines/schedules.md index 752e2a97fad..fb8de034d2a 100644 --- a/doc/ci/pipelines/schedules.md +++ b/doc/ci/pipelines/schedules.md @@ -65,7 +65,7 @@ GitLab CI/CD so that they can be used in your [`.gitlab-ci.yml` file](../../ci/y To configure a job to be executed only when the pipeline has been scheduled (or the opposite), use -[only and except](../yaml/README.md#onlyexcept-basic) configuration keywords. +[only and except](../yaml/README.md#only--except) configuration keywords. In the example below `make world` runs in scheduled pipelines, and `make build` runs in pipelines that are not scheduled: diff --git a/doc/ci/services/gitlab.md b/doc/ci/services/gitlab.md index 8a582cc87eb..a0e15b4e960 100644 --- a/doc/ci/services/gitlab.md +++ b/doc/ci/services/gitlab.md @@ -28,7 +28,7 @@ tests access to the GitLab API. [assign them to a variable in the user interface](../variables/README.md#project-cicd-variables). Then assign that variable to the corresponding variable in your `.gitlab-ci.yml` file. - + Then, commands in `script:` sections in your `.gitlab-ci.yml` file can access the API at `http://gitlab/api/v4`. For more information about why `gitlab` is used for the `Host`, see diff --git a/doc/ci/services/mysql.md b/doc/ci/services/mysql.md index 2185af0141d..1e0762ca010 100644 --- a/doc/ci/services/mysql.md +++ b/doc/ci/services/mysql.md @@ -14,6 +14,8 @@ need it for your tests to run. If you want to use a MySQL container, you can use [GitLab Runner](../runners/README.md) with the Docker executor. +This example shows you how to set a username and password that GitLab uses to access the MySQL container. If you do not set a username and password, you must use `root`. + 1. [Create CI/CD variables](../variables/README.md#custom-cicd-variables) for your MySQL database and password by going to **Settings > CI/CD**, expanding **Variables**, and clicking **Add Variable**. @@ -54,6 +56,9 @@ If you want to use a MySQL container, you can use [GitLab Runner](../runners/REA Database: <your_mysql_database> ``` + In this example, the user is `runner`. You should use a user that has permission to + access your database. + ## Use MySQL with the Shell executor You can also use MySQL on manually-configured servers that use diff --git a/doc/ci/triggers/README.md b/doc/ci/triggers/README.md index 3cdf45a8cbc..434adb0c8f3 100644 --- a/doc/ci/triggers/README.md +++ b/doc/ci/triggers/README.md @@ -26,7 +26,7 @@ depending on which trigger method is used. | `pipeline` | Using the `trigger:` keyword in the CI/CD configuration file, or using the trigger API with `$CI_JOB_TOKEN`. | | `trigger` | Using the trigger API using a generated trigger token | -This also applies when using the `pipelines` or `triggers` keywords with the legacy [`only/except` basic syntax](../yaml/README.md#onlyexcept-basic). +This also applies when using the `pipelines` or `triggers` keywords with the legacy [`only/except` basic syntax](../yaml/README.md#only--except). ### Trigger token diff --git a/doc/ci/troubleshooting.md b/doc/ci/troubleshooting.md index d4b9282ac38..cc6d02cbf36 100644 --- a/doc/ci/troubleshooting.md +++ b/doc/ci/troubleshooting.md @@ -123,7 +123,7 @@ This is usually caused by the `rules` configuration, and there are several ways #### A job is not in the pipeline -GitLab determines if a job is added to a pipeline based on the [`only/except`](yaml/README.md#onlyexcept-basic) +GitLab determines if a job is added to a pipeline based on the [`only/except`](yaml/README.md#only--except) or [`rules`](yaml/README.md#rules) defined for the job. If it didn't run, it's probably not evaluating as you expect. @@ -150,7 +150,7 @@ A common reason a job is added to a pipeline unexpectedly is because the `change keyword always evaluates to true in certain cases. For example, `changes` is always true in certain pipeline types, including scheduled pipelines and pipelines for tags. -The `changes` keyword is used in combination with [`only/except`](yaml/README.md#onlychangesexceptchanges) +The `changes` keyword is used in combination with [`only/except`](yaml/README.md#onlychanges--exceptchanges) or [`rules`](yaml/README.md#ruleschanges)). It's recommended to use `changes` with `rules` or `only/except` configuration that ensures the job is only added to branch pipelines or merge request pipelines. @@ -269,7 +269,7 @@ which pipelines can run. resource_group = Project.find_by_full_path('...').resource_groups.find_by(key: 'the-group-name') busy_resources = resource_group.resources.where('build_id IS NOT NULL') -# identify which builds are occupying the resource +# identify which builds are occupying the resource # (I think it should be 1 as of today) busy_resources.pluck(:build_id) diff --git a/doc/ci/unit_test_reports.md b/doc/ci/unit_test_reports.md index c4f3073e142..bbb62f74caa 100644 --- a/doc/ci/unit_test_reports.md +++ b/doc/ci/unit_test_reports.md @@ -11,12 +11,12 @@ type: reference > - [Renamed](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/39737) from JUnit test reports to Unit test reports in GitLab 13.4. It is very common that a [CI/CD pipeline](pipelines/index.md) contains a -test job that will verify your code. +test job that verifies your code. If the tests fail, the pipeline fails and users get notified. The person that -works on the merge request will have to check the job logs and see where the +works on the merge request has to check the job logs and see where the tests failed so that they can fix them. -You can configure your job to use Unit test reports, and GitLab will display a +You can configure your job to use Unit test reports, and GitLab displays a report on the merge request so that it's easier and faster to identify the failure without having to check the entire log. Unit test reports currently only support test reports in the JUnit report format. @@ -49,7 +49,7 @@ comparing the head and base branch's JUnit report format XML files, where: The reports panel has a summary showing how many tests failed, how many had errors and how many were fixed. If no comparison can be done because data for the base branch -is not available, the panel will just show the list of failed tests for head. +is not available, the panel just shows the list of failed tests for head. There are four types of results: @@ -59,8 +59,8 @@ There are four types of results: 1. **Existing failures:** Test cases which failed on base branch and failed on head branch 1. **Resolved failures:** Test cases which failed on base branch and passed on head branch -Each entry in the panel will show the test name and its type from the list -above. Clicking on the test name will open a modal window with details of its +Each entry in the panel shows the test name and its type from the list +above. Clicking on the test name opens a modal window with details of its execution time and the error output.  @@ -115,7 +115,7 @@ ruby: ### Go example Use the following job in `.gitlab-ci.yml`, and ensure you use `-set-exit-code`, -otherwise the pipeline will be marked successful, even if the tests fail: +otherwise the pipeline is marked successful, even if the tests fail: ```yaml ## Use https://github.com/jstemmer/go-junit-report to generate a JUnit report format XML file with go @@ -137,7 +137,7 @@ There are a few tools that can produce JUnit report format XML file in Java. #### Gradle In the following example, `gradle` is used to generate the test reports. -If there are multiple test tasks defined, `gradle` will generate multiple +If there are multiple test tasks defined, `gradle` generates multiple directories under `build/test-results/`. In that case, you can leverage glob matching by defining the following path: `build/test-results/test/**/TEST-*.xml`: @@ -198,8 +198,8 @@ There are a few tools that can produce JUnit report format XML files in C/C++. In the following example, `gtest` is used to generate the test reports. If there are multiple `gtest` executables created for different architectures (`x86`, `x64` or `arm`), -you will be required to run each test providing a unique filename. The results -will then be aggregated together. +you are required to run each test providing a unique filename. The results +are then aggregated together. ```yaml cpp: @@ -313,8 +313,8 @@ test: > - The feature flag was removed and the feature was [made generally available](https://gitlab.com/gitlab-org/gitlab/-/issues/216478) in GitLab 13.3. If JUnit report format XML files are generated and uploaded as part of a pipeline, these reports -can be viewed inside the pipelines details page. The **Tests** tab on this page will -display a list of test suites and cases reported from the XML file. +can be viewed inside the pipelines details page. The **Tests** tab on this page +displays a list of test suites and cases reported from the XML file.  @@ -333,32 +333,24 @@ If parsing JUnit report XML results in an error, an indicator is shown next to t ## Viewing JUnit screenshots on GitLab -> - [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/202114) in GitLab 13.0. -> - It's deployed behind a feature flag, disabled by default. -> - To use it in GitLab self-managed instances, ask a GitLab administrator to [enable it](#enabling-the-junit-screenshots-feature). **(FREE SELF)** +> - [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/202114) in GitLab 13.0 behind the `:junit_pipeline_screenshots_view` feature flag, disabled by default. +> - The feature flag was removed and was [made generally available](https://gitlab.com/gitlab-org/gitlab/-/issues/216979) in GitLab 13.12. -WARNING: -This feature might not be available to you. Check the **version history** note above for details. +Upload your screenshots as [artifacts](yaml/README.md#artifactsreportsjunit) to GitLab. If JUnit +report format XML files contain an `attachment` tag, GitLab parses the attachment. Note that: -When [this issue](https://gitlab.com/gitlab-org/gitlab/-/issues/6061) is complete, the attached file will be visible on the pipeline details page. +- The `attachment` tag **must** contain the absolute path to the screenshots you uploaded. For + example: -If JUnit report format XML files contain an `attachment` tag, GitLab parses the attachment. + ```xml + <testcase time="1.00" name="Test"> + <system-out>[[ATTACHMENT|/absolute/path/to/some/file]]</system-out> + </testcase> + ``` -Upload your screenshots as [artifacts](yaml/README.md#artifactsreportsjunit) to GitLab. The `attachment` tag **must** contain the absolute path to the screenshots you uploaded. +- You should set the job that uploads the screenshot to + [`artifacts:when: always`](yaml/README.md#artifactswhen) so that it still uploads a screenshot + when a test fails. -```xml -<testcase time="1.00" name="Test"> - <system-out>[[ATTACHMENT|/absolute/path/to/some/file]]</system-out> -</testcase> -``` - -### Enabling the JUnit screenshots feature **(FREE SELF)** - -This feature comes with the `:junit_pipeline_screenshots_view` feature flag disabled by default. - -To enable this feature, ask a GitLab administrator with [Rails console access](../administration/feature_flags.md#how-to-enable-and-disable-features-behind-flags) to run the -following command: - -```ruby -Feature.enable(:junit_pipeline_screenshots_view) -``` +A link to the test case attachment appears in the test case details in +[the pipeline test report](#viewing-unit-test-reports-on-gitlab). diff --git a/doc/ci/variables/README.md b/doc/ci/variables/README.md index 20de736a6e6..272f379611e 100644 --- a/doc/ci/variables/README.md +++ b/doc/ci/variables/README.md @@ -43,7 +43,7 @@ predefined variable: test_variable: stage: test script: - - echo $CI_JOB_STAGE + - echo "$CI_JOB_STAGE" ``` The script outputs the `stage` for the `test_variable`, which is `test`: @@ -88,7 +88,7 @@ job1: variables: TEST_VAR_JOB: "Only job1 can use this variable's value" script: - - echo $TEST_VAR and $TEST_VAR_JOB + - echo "$TEST_VAR" and "$TEST_VAR_JOB" ``` Variables saved in the `.gitlab-ci.yml` file should store only non-sensitive project @@ -114,9 +114,9 @@ name inside another variable: ```yaml variables: FLAGS: '-al' - LS_CMD: 'ls $FLAGS $$TMP_DIR' + LS_CMD: 'ls "$FLAGS" $$TMP_DIR' script: - - 'eval $LS_CMD' # Executes 'ls -al $TMP_DIR' + - 'eval "$LS_CMD"' # Executes 'ls -al $TMP_DIR' ``` Use the [`value` and `description`](../yaml/README.md#prefill-variables-in-manual-pipelines) @@ -151,10 +151,10 @@ After you create a variable, you can use it in the `.gitlab-ci.yml` file: test_variable: stage: test script: - - echo $CI_JOB_STAGE # calls a predefined variable - - echo $TEST # calls a custom variable of type `env_var` - - echo $GREETING # calls a custom variable of type `file` that contains the path to the temp file - - cat $GREETING # the temp file itself contains the variable value + - echo "$CI_JOB_STAGE" # calls a predefined variable + - echo "$TEST" # calls a custom variable of type `env_var` + - echo "$GREETING" # calls a custom variable of type `file` that contains the path to the temp file + - cat "$GREETING" # the temp file itself contains the variable value ``` The output is: @@ -181,7 +181,7 @@ To add a group variable: - **Key**: Must be one line, with no spaces, using only letters, numbers, or `_`. - **Value**: No limitations. - **Type**: [`File` or `Variable`](#cicd-variable-types). - - **Environment scope** (optional): `All`, or specific [environments](#limit-the-environment-scope-of-a-cicd-variable). + - **Environment scope** (optional): `All`, or specific [environments](#limit-the-environment-scope-of-a-cicd-variable). **(PREMIUM)** - **Protect variable** (Optional): If selected, the variable is only available in pipelines that run on protected branches or tags. - **Mask variable** (Optional): If selected, the variable's **Value** is masked @@ -298,6 +298,7 @@ The value of the variable must: - Characters from the Base64 alphabet (RFC4648). - The `@` and `:` characters ([In GitLab 12.2](https://gitlab.com/gitlab-org/gitlab-foss/-/issues/63043) and later). - The `.` character ([In GitLab 12.10](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/29022) and later). + - The `~` character ([In GitLab 13.12](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/61517) and later). - Not match the name of an existing predefined or custom CI/CD variable. ### Protect a CI/CD variable @@ -366,7 +367,7 @@ CI/CD variable with (`$`): ```yaml job_name: script: - - echo $CI_JOB_ID + - echo "$CI_JOB_ID" ``` ### Use variables with PowerShell @@ -506,7 +507,7 @@ build: deploy: stage: deploy script: - - echo $BUILD_VERSION # Output is: 'hello' + - echo "$BUILD_VERSION" # Output is: 'hello' dependencies: - build ``` @@ -525,7 +526,7 @@ build: deploy: stage: deploy script: - - echo $BUILD_VERSION # Output is: 'hello' + - echo "$BUILD_VERSION" # Output is: 'hello' needs: - job: build artifacts: true @@ -603,11 +604,18 @@ to enable the `restrict_user_defined_variables` setting. The setting is `disable ## Limit the environment scope of a CI/CD variable -You can limit the environment scope of a variable by -[defining which environments](../environments/index.md) it can be available for. +By default, all CI/CD variables are available to any job in a pipeline. Therefore, if a project uses a +compromised tool in a test job, it could expose all CI/CD variables that a deployment job used. This is +a common scenario in supply chain attacks. GitLab helps mitigate supply chain attacks by limiting +the environment scope of a variable. GitLab does this by +[defining which environments and corresponding jobs](../environments/index.md) +the variable can be available for. To learn more about scoping environments, see [Scoping environments with specs](../environments/index.md#scoping-environments-with-specs). +To learn more about ensuring CI/CD variables are only exposed in pipelines running from protected +branches or tags, see [Protect a CI/CD Variable](#protect-a-cicd-variable). + ## Deployment variables Integrations that are responsible for deployment configuration can define their own @@ -635,7 +643,7 @@ CI/CD variables with multi-line values are not supported. ## CI/CD variable expressions -> - [Introduced](https://gitlab.com/gitlab-org/gitlab-foss/-/issues/37397) in GitLab 10.7 for [the `only` and `except` CI keywords](../yaml/README.md#onlyexcept-advanced) +> - [Introduced](https://gitlab.com/gitlab-org/gitlab-foss/-/issues/37397) in GitLab 10.7 for [the `only` and `except` CI keywords](../yaml/README.md#onlyvariables--exceptvariables) > - [Expanded](https://gitlab.com/gitlab-org/gitlab/-/issues/27863) in GitLab 12.3 with [the `rules` keyword](../yaml/README.md#rules) Use variable expressions to limit which jobs are created @@ -644,7 +652,7 @@ in a pipeline after changes are pushed to GitLab. In `.gitlab-ci.yml`, variable expressions work with both: - [`rules`](../yaml/README.md#rules), which is the recommended approach, and -- [`only` and `except`](../yaml/README.md#onlyexcept-basic), which are candidates for deprecation. +- [`only` and `except`](../yaml/README.md#only--except), which are candidates for deprecation. This is particularly useful in combination with variables and triggered pipeline variables. @@ -665,7 +673,7 @@ If any of the conditions in `variables` evaluates to true when using `only`, a new job is created. If any of the expressions evaluates to true when `except` is being used, a job is not created. -This follows the usual rules for [`only` / `except` policies](../yaml/README.md#onlyexcept-advanced). +This follows the usual rules for [`only` / `except` policies](../yaml/README.md#onlyvariables--exceptvariables). ### Syntax of CI/CD variable expressions diff --git a/doc/ci/variables/deprecated_variables.md b/doc/ci/variables/deprecated_variables.md deleted file mode 100644 index 8d23ec1fd97..00000000000 --- a/doc/ci/variables/deprecated_variables.md +++ /dev/null @@ -1,8 +0,0 @@ ---- -redirect_to: 'README.md' ---- - -This documentation page was removed. For information about variables, see [GitLab CI/CD environment variables](README.md) - -<!-- This redirect file can be deleted after 2021-04-14. --> -<!-- Before deletion, see: https://docs.gitlab.com/ee/development/documentation/#move-or-rename-a-page --> diff --git a/doc/ci/variables/predefined_variables.md b/doc/ci/variables/predefined_variables.md index 5ceab9c0ff3..9cb960ae8ec 100644 --- a/doc/ci/variables/predefined_variables.md +++ b/doc/ci/variables/predefined_variables.md @@ -50,7 +50,7 @@ There are also [Kubernetes-specific deployment variables](../../user/project/clu | `CI_DEPLOY_USER` | 10.8 | all | The authentication username of the [GitLab Deploy Token](../../user/project/deploy_tokens/index.md#gitlab-deploy-token), if the project has one. | | `CI_DISPOSABLE_ENVIRONMENT` | all | 10.1 | Only available if the job is executed in a disposable environment (something that is created only for this job and disposed of/destroyed after the execution - all executors except `shell` and `ssh`). `true` when available. | | `CI_ENVIRONMENT_NAME` | 8.15 | all | The name of the environment for this job. Available if [`environment:name`](../yaml/README.md#environmentname) is set. | -| `CI_ENVIRONMENT_SLUG` | 8.15 | all | The simplified version of the environment name, suitable for inclusion in DNS, URLs, Kubernetes labels, and so on. Available if [`environment:name`](../yaml/README.md#environmentname) is set. | +| `CI_ENVIRONMENT_SLUG` | 8.15 | all | The simplified version of the environment name, suitable for inclusion in DNS, URLs, Kubernetes labels, and so on. Available if [`environment:name`](../yaml/README.md#environmentname) is set. The slug is [truncated to 24 characters](https://gitlab.com/gitlab-org/gitlab/-/issues/20941). | | `CI_ENVIRONMENT_URL` | 9.3 | all | The URL of the environment for this job. Available if [`environment:url`](../yaml/README.md#environmenturl) is set. | | `CI_HAS_OPEN_REQUIREMENTS` | 13.1 | all | Only available if the pipeline's project has an open [requirement](../../user/project/requirements/index.md). `true` when available. | | `CI_JOB_ID` | 9.0 | all | The internal ID of the job, unique across all jobs in the GitLab instance. | diff --git a/doc/ci/yaml/README.md b/doc/ci/yaml/README.md index 49daa2b17fb..e9b3a2213c8 100644 --- a/doc/ci/yaml/README.md +++ b/doc/ci/yaml/README.md @@ -36,14 +36,14 @@ The keywords available for jobs are: | [`coverage`](#coverage) | Code coverage settings for a given job. | | [`dependencies`](#dependencies) | Restrict which artifacts are passed to a specific job by providing a list of jobs to fetch artifacts from. | | [`environment`](#environment) | Name of an environment to which the job deploys. | -| [`except`](#onlyexcept-basic) | Limit when jobs are not created. | +| [`except`](#only--except) | Control when jobs are not created. | | [`extends`](#extends) | Configuration entries that this job inherits from. | | [`image`](#image) | Use Docker images. | | [`include`](#include) | Include external YAML files. | | [`inherit`](#inherit) | Select which global defaults all jobs inherit. | | [`interruptible`](#interruptible) | Defines if a job can be canceled when made redundant by a newer run. | | [`needs`](#needs) | Execute jobs earlier than the stage ordering. | -| [`only`](#onlyexcept-basic) | Limit when jobs are created. | +| [`only`](#only--except) | Control when jobs are created. | | [`pages`](#pages) | Upload the result of a job to use with GitLab Pages. | | [`parallel`](#parallel) | How many instances of a job should be run in parallel. | | [`release`](#release) | Instructs the runner to generate a [release](../../user/project/releases/index.md) object. | @@ -152,6 +152,13 @@ are the default pipeline stages. If a job does not specify a [`stage`](#stage), the job is assigned the `test` stage. +If a stage is defined, but no jobs use it, the stage is not visible in the pipeline. This is +useful for [compliance pipeline configuration](../../user/project/settings/index.md#compliance-pipeline-configuration) +because: + +- Stages can be defined in the compliance configuration but remain hidden if not used. +- The defined stages become visible when developers use them in job definitions. + To make a job start earlier and ignore the stage order, use the [`needs`](#needs) keyword. @@ -226,13 +233,15 @@ If your rules match both branch pipelines and merge request pipelines, #### `workflow:rules:variables` > - [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/294232) in GitLab 13.11. -> - It's [deployed behind a feature flag](../../user/feature_flags.md), disabled by default. -> - It's disabled on GitLab.com. -> - It's not recommended for production use. -> - To use it in GitLab self-managed instances, ask a GitLab administrator to [enable it](#enable-or-disable-workflowrulesvariables). **(CORE ONLY)** +> - [Deployed behind a feature flag](../../user/feature_flags.md), disabled by default. +> - [Enabled by default](https://gitlab.com/gitlab-org/gitlab/-/issues/300997) in GitLab 13.12. +> - Enabled on GitLab.com. +> - Recommended for production use. +> - For GitLab self-managed instances, GitLab administrators can opt to [disable it](#enable-or-disable-workflowrulesvariables). **(FREE SELF)** -WARNING: -This feature might not be available to you. Check the **version history** note above for details. +There can be +[risks when disabling released features](../../user/feature_flags.md#risks-when-disabling-released-features). +Refer to this feature's version history for more details. You can use [`variables`](#variables) in `workflow:rules:` to define variables for specific pipeline conditions. @@ -285,12 +294,12 @@ When the branch is something else: - job1's `DEPLOY_VARIABLE` is `job1-default-deploy`. - job2's `DEPLOY_VARIABLE` is `default-deploy`. -##### Enable or disable workflow:rules:variables **(CORE ONLY)** +##### Enable or disable workflow:rules:variables **(FREE SELF)** -rules:variables is under development and not ready for production use. -It is deployed behind a feature flag that is **disabled by default**. +workflow:rules:variables is under development but ready for production use. +It is deployed behind a feature flag that is **enabled by default**. [GitLab administrators with access to the GitLab Rails console](../../administration/feature_flags.md) -can enable it. +can opt to disable it. To enable it: @@ -480,12 +489,17 @@ Use local includes instead of symbolic links. ##### `include:local` with wildcard file paths > - [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/25921) in GitLab 13.11. -> - It's [deployed behind a feature flag](../../user/feature_flags.md), disabled by default. -> - It's disabled on GitLab.com. -> - It's not recommended for production use. -> - To use it in GitLab self-managed instances, ask a GitLab administrator to enable it. **(CORE ONLY)** +> - [Deployed behind a feature flag](../../user/feature_flags.md), disabled by default. +> - [Enabled by default](https://gitlab.com/gitlab-org/gitlab/-/issues/327315) in GitLab 13.12. +> - Enabled on GitLab.com. +> - Recommended for production use. +> - For GitLab self-managed instances, GitLab administrators can opt to disable it. **(CORE ONLY)** -You can use wildcard paths (`*`) with `include:local`. +There can be +[risks when disabling released features](../../user/feature_flags.md#risks-when-disabling-released-features). +Refer to this feature's version history for more details. + +You can use wildcard paths (`*` and `**`) with `include:local`. Example: @@ -493,12 +507,24 @@ Example: include: 'configs/*.yml' ``` -When the pipeline runs, it adds all `.yml` files in the `configs` folder into the pipeline configuration. +When the pipeline runs, GitLab: + +- Adds all `.yml` files in the `configs` directory into the pipeline configuration. +- Does not add `.yml` files in subfolders of the `configs` directory. To allow this, + add the following configuration: + + ```yaml + # This matches all `.yml` files in `configs` and any subfolder in it. + include: 'configs/**.yml' -The wildcard file paths feature is under development and not ready for production use. It is -deployed behind a feature flag that is **disabled by default**. + # This matches all `.yml` files only in subfolders of `configs`. + include: 'configs/**/*.yml' + ``` + +The wildcard file paths feature is under development but ready for production use. +It is deployed behind a feature flag that is **enabled by default**. [GitLab administrators with access to the GitLab Rails console](../../administration/feature_flags.md) -can enable it. +can opt to disable it. To enable it: @@ -1090,7 +1116,7 @@ is either included or excluded from the pipeline, depending on the configuration The job can also have [certain attributes](#rules-attributes) added to it. -`rules` replaces [`only/except`](#onlyexcept-basic) and they can't be used together +`rules` replaces [`only/except`](#only--except) and they can't be used together in the same job. If you configure one job to use both keywords, the linter returns a `key may not be used with rules` error. @@ -1123,8 +1149,8 @@ Available rule clauses are: | Clause | Description | |----------------------------|------------------------------------------------------------------------------------------------------------------------------------| -| [`if`](#rulesif) | Add or exclude jobs from a pipeline by evaluating an `if` statement. Similar to [`only:variables`](#onlyvariablesexceptvariables). | -| [`changes`](#ruleschanges) | Add or exclude jobs from a pipeline based on what files are changed. Same as [`only:changes`](#onlychangesexceptchanges). | +| [`if`](#rulesif) | Add or exclude jobs from a pipeline by evaluating an `if` statement. Similar to [`only:variables`](#onlyvariables--exceptvariables). | +| [`changes`](#ruleschanges) | Add or exclude jobs from a pipeline based on what files are changed. Same as [`only:changes`](#onlychanges--exceptchanges). | | [`exists`](#rulesexists) | Add or exclude jobs from a pipeline based on the presence of specific files. | Rules are evaluated in order until a match is found. If a match is found, the attributes @@ -1281,7 +1307,7 @@ job-with-rules: For every change pushed to the branch, duplicate pipelines run. One branch pipeline runs a single job (`job-with-no-rules`), and one merge request pipeline runs the other job (`job-with-rules`). Jobs with no rules default -to [`except: merge_requests`](#onlyexcept-basic), so `job-with-no-rules` +to [`except: merge_requests`](#only--except), so `job-with-no-rules` runs in all cases except merge requests. #### `rules:if` @@ -1330,7 +1356,7 @@ Some details regarding the logic that determines the `when` for the job: ##### Common `if` clauses for `rules` -For behavior similar to the [`only`/`except` keywords](#onlyexcept-basic), you can +For behavior similar to the [`only`/`except` keywords](#only--except), you can check the value of the `$CI_PIPELINE_SOURCE` variable: | Value | Description | @@ -1392,7 +1418,7 @@ Other commonly used variables for `if` clauses: Use `rules:changes` to specify when to add a job to a pipeline by checking for changes to specific files. -`rules: changes` works the same way as [`only: changes` and `except: changes`](#onlychangesexceptchanges). +`rules: changes` works the same way as [`only: changes` and `except: changes`](#onlychanges--exceptchanges). It accepts an array of paths. You should use `rules: changes` only with branch pipelines or merge request pipelines. For example, it's common to use `rules: changes` with merge request pipelines: @@ -1423,7 +1449,7 @@ rules: - if: $CI_PIPELINE_SOURCE == "push" && $CI_COMMIT_BRANCH ``` -To implement a rule similar to [`except:changes`](#onlychangesexceptchanges), +To implement a rule similar to [`except:changes`](#onlychanges--exceptchanges), use `when: never`. WARNING: @@ -1583,318 +1609,162 @@ WARNING: [Before GitLab 13.3](https://gitlab.com/gitlab-org/gitlab/-/issues/230938), rules that use both `||` and `&&` may evaluate with an unexpected order of operations. -### `only`/`except` (basic) +### `only` / `except` NOTE: -`only` and `except` are not being actively developed. To define when -to add jobs to pipelines, use [`rules`](#rules). +`only` and `except` are not being actively developed. [`rules`](#rules) is the preferred +keyword to control when to add jobs to pipelines. -`only` and `except` are two keywords that determine when to add jobs to pipelines: +You can use `only` and `except` to control when to add jobs to pipelines. -1. `only` defines the names of branches and tags the job runs for. -1. `except` defines the names of branches and tags the job does - **not** run for. +- Use `only` to define when a job runs. +- Use `except` to define when a job **does not** run. -A few rules apply to the usage of job policy: +Four keywords can be used with `only` and `except`: -- `only` and `except` are inclusive. If both `only` and `except` are defined - in a job specification, the ref is filtered by `only` and `except`. -- `only` and `except` can use regular expressions ([supported regexp syntax](#supported-onlyexcept-regexp-syntax)). -- `only` and `except` can specify a repository path to filter jobs for forks. +- [`refs`](#onlyrefs--exceptrefs) +- [`variables`](#onlyvariables--exceptvariables) +- [`changes`](#onlychanges--exceptchanges) +- [`kubernetes`](#onlykubernetes--exceptkubernetes) -In addition, `only` and `except` can use these keywords: +See [specify when jobs run with `only` and `except`](../jobs/job_control.md#specify-when-jobs-run-with-only-and-except) +for more details and examples. -| **Value** | **Description** | -|--------------------------|----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------| -| `api` | For pipelines triggered by the [pipelines API](../../api/pipelines.md#create-a-new-pipeline). | -| `branches` | When the Git reference for a pipeline is a branch. | -| `chat` | For pipelines created by using a [GitLab ChatOps](../chatops/index.md) command. | -| `external` | When you use CI services other than GitLab. | -| `external_pull_requests` | When an external pull request on GitHub is created or updated (See [Pipelines for external pull requests](../ci_cd_for_external_repos/index.md#pipelines-for-external-pull-requests)). | -| `merge_requests` | For pipelines created when a merge request is created or updated. Enables [merge request pipelines](../merge_request_pipelines/index.md), [merged results pipelines](../merge_request_pipelines/pipelines_for_merged_results/index.md), and [merge trains](../merge_request_pipelines/pipelines_for_merged_results/merge_trains/index.md). | -| `pipelines` | For [multi-project pipelines](../multi_project_pipelines.md) created by [using the API with `CI_JOB_TOKEN`](../multi_project_pipelines.md#triggering-multi-project-pipelines-through-api), or the [`trigger`](#trigger) keyword. | -| `pushes` | For pipelines triggered by a `git push` event, including for branches and tags. | -| `schedules` | For [scheduled pipelines](../pipelines/schedules.md). | -| `tags` | When the Git reference for a pipeline is a tag. | -| `triggers` | For pipelines created by using a [trigger token](../triggers/README.md#trigger-token). | -| `web` | For pipelines created by using **Run pipeline** button in the GitLab UI, from the project's **CI/CD > Pipelines** section. | +#### `only:refs` / `except:refs` -Scheduled pipelines run on specific branches, so jobs configured with `only: branches` -run on scheduled pipelines too. Add `except: schedules` to prevent jobs with `only: branches` -from running on scheduled pipelines. +Use the `only:refs` and `except:refs` keywords to control when to add jobs to a +pipeline based on branch names or pipeline types. -In the following example, `job` runs only for refs that start with `issue-`. -All branches are skipped: +**Keyword type**: Job keyword. You can use it only as part of a job. -```yaml -job: - # use regexp - only: - - /^issue-.*$/ - # use special keyword - except: - - branches -``` - -Pattern matching is case-sensitive by default. Use the `i` flag modifier, like -`/pattern/i`, to make a pattern case-insensitive: +**Possible inputs**: An array including any number of: -```yaml -job: - # use regexp - only: - - /^issue-.*$/i - # use special keyword - except: - - branches -``` +- Branch names, for example `main` or `my-feature-branch`. +- [Regular expressions](../jobs/job_control.md#only--except-regex-syntax) + that match against branch names, for example `/^feature-.*/`. +- The following keywords: -In the following example, `job` runs only for: + | **Value** | **Description** | + | -------------------------|-----------------| + | `api` | For pipelines triggered by the [pipelines API](../../api/pipelines.md#create-a-new-pipeline). | + | `branches` | When the Git reference for a pipeline is a branch. | + | `chat` | For pipelines created by using a [GitLab ChatOps](../chatops/index.md) command. | + | `external` | When you use CI services other than GitLab. | + | `external_pull_requests` | When an external pull request on GitHub is created or updated (See [Pipelines for external pull requests](../ci_cd_for_external_repos/index.md#pipelines-for-external-pull-requests)). | + | `merge_requests` | For pipelines created when a merge request is created or updated. Enables [merge request pipelines](../merge_request_pipelines/index.md), [merged results pipelines](../merge_request_pipelines/pipelines_for_merged_results/index.md), and [merge trains](../merge_request_pipelines/pipelines_for_merged_results/merge_trains/index.md). | + | `pipelines` | For [multi-project pipelines](../multi_project_pipelines.md) created by [using the API with `CI_JOB_TOKEN`](../multi_project_pipelines.md#triggering-multi-project-pipelines-through-api), or the [`trigger`](#trigger) keyword. | + | `pushes` | For pipelines triggered by a `git push` event, including for branches and tags. | + | `schedules` | For [scheduled pipelines](../pipelines/schedules.md). | + | `tags` | When the Git reference for a pipeline is a tag. | + | `triggers` | For pipelines created by using a [trigger token](../triggers/README.md#trigger-token). | + | `web` | For pipelines created by using **Run pipeline** button in the GitLab UI, from the project's **CI/CD > Pipelines** section. | -- Git tags -- [Triggers](../triggers/README.md#trigger-token) -- [Scheduled pipelines](../pipelines/schedules.md) - -```yaml -job: - # use special keywords - only: - - tags - - triggers - - schedules -``` - -To execute jobs only for the parent repository and not forks: - -```yaml -job: - only: - - branches@gitlab-org/gitlab - except: - - master@gitlab-org/gitlab - - /^release/.*$/@gitlab-org/gitlab -``` - -This example runs `job` for all branches on `gitlab-org/gitlab`, -except `master` and branches that start with `release/`. - -If a job does not have an `only` rule, `only: ['branches', 'tags']` is set by -default. If the job does not have an `except` rule, it's empty. - -For example, `job1` and `job2` are essentially the same: +**Example of `only:refs` and `except:refs`**: ```yaml job1: - script: echo 'test' - -job2: - script: echo 'test' - only: ['branches', 'tags'] -``` - -#### Regular expressions - -The `@` symbol denotes the beginning of a ref's repository path. -To match a ref name that contains the `@` character in a regular expression, -you must use the hex character code match `\x40`. - -Only the tag or branch name can be matched by a regular expression. -The repository path, if given, is always matched literally. - -To match the tag or branch name, -the entire ref name part of the pattern must be a regular expression surrounded by `/`. -For example, you can't use `issue-/.*/` to match all tag names or branch names -that begin with `issue-`, but you can use `/issue-.*/`. - -Regular expression flags must be appended after the closing `/`. - -NOTE: -Use anchors `^` and `$` to avoid the regular expression -matching only a substring of the tag name or branch name. -For example, `/^issue-.*$/` is equivalent to `/^issue-/`, -while just `/issue/` would also match a branch called `severe-issues`. - -#### Supported `only`/`except` regexp syntax - -In GitLab 11.9.4, GitLab began internally converting the regexp used -in `only` and `except` keywords to [RE2](https://github.com/google/re2/wiki/Syntax). - -[RE2](https://github.com/google/re2/wiki/Syntax) limits the set of available features -due to computational complexity, and some features, like negative lookaheads, became unavailable. -Only a subset of features provided by [Ruby Regexp](https://ruby-doc.org/core/Regexp.html) -are now supported. - -From GitLab 11.9.7 to GitLab 12.0, GitLab provided a feature flag to -let you use unsafe regexp syntax. After migrating to safe syntax, you should disable -this feature flag again: - -```ruby -Feature.enable(:allow_unsafe_ruby_regexp) -``` - -### `only`/`except` (advanced) - -GitLab supports multiple strategies, and it's possible to use an -array or a hash configuration scheme. - -Four keys are available: - -- `refs` -- `variables` -- `changes` -- `kubernetes` - -If you use multiple keys under `only` or `except`, the keys are evaluated as a -single conjoined expression. That is: - -- `only:` includes the job if **all** of the keys have at least one condition that matches. -- `except:` excludes the job if **any** of the keys have at least one condition that matches. - -With `only`, individual keys are logically joined by an `AND`. A job is added to -the pipeline if the following is true: - -- `(any listed refs are true) AND (any listed variables are true) AND (any listed changes are true) AND (any chosen Kubernetes status matches)` - -In the following example, the `test` job is `only` created when **all** of the following are true: - -- The pipeline is [scheduled](../pipelines/schedules.md) **or** runs for `master`. -- The `variables` keyword matches. -- The `kubernetes` service is active on the project. - -```yaml -test: - script: npm run test + script: echo only: - refs: - - master - - schedules - variables: - - $CI_COMMIT_MESSAGE =~ /run-end-to-end-tests/ - kubernetes: active -``` - -With `except`, individual keys are logically joined by an `OR`. A job is **not** -added if the following is true: - -- `(any listed refs are true) OR (any listed variables are true) OR (any listed changes are true) OR (a chosen Kubernetes status matches)` - -In the following example, the `test` job is **not** created when **any** of the following are true: - -- The pipeline runs for the `master` branch. -- There are changes to the `README.md` file in the root directory of the repository. + - main + - /^issue-.*$/ + - merge_requests -```yaml -test: - script: npm run test +job2: + script: echo except: - refs: - - master - changes: - - "README.md" + - main + - /^stable-branch.*$/ + - schedules ``` -#### `only:refs`/`except:refs` +**Additional details:** -> `refs` policy introduced in GitLab 10.0. +- Scheduled pipelines run on specific branches, so jobs configured with `only: branches` + run on scheduled pipelines too. Add `except: schedules` to prevent jobs with `only: branches` + from running on scheduled pipelines. +- `only` or `except` used without any other keywords are equivalent to `only: refs` + or `except: refs`. For example, the following two jobs configurations have the same + behavior: -The `refs` strategy can take the same values as the -[simplified only/except configuration](#onlyexcept-basic). - -In the following example, the `deploy` job is created only when the -pipeline is [scheduled](../pipelines/schedules.md) or runs for the `master` branch: - -```yaml -deploy: - only: - refs: - - master - - schedules -``` + ```yaml + job1: + script: echo + only: + - branches -#### `only:kubernetes`/`except:kubernetes` + job2: + script: echo + only: + refs: + - branches + ``` -> `kubernetes` policy introduced in GitLab 10.0. +- If a job does not use `only`, `except`, or [`rules`](#rules), then `only` is set to `branches` + and `tags` by default. -The `kubernetes` strategy accepts only the `active` keyword. + For example, `job1` and `job2` are equivalent: -In the following example, the `deploy` job is created only when the -Kubernetes service is active in the project: + ```yaml + job1: + script: echo 'test' -```yaml -deploy: - only: - kubernetes: active -``` + job2: + script: echo 'test' + only: + - branches + - tags + ``` -#### `only:variables`/`except:variables` +#### `only:variables` / `except:variables` -> `variables` policy introduced in GitLab 10.7. +Use the `only:variables` or `except:variables` keywords to control when to add jobs +to a pipeline, based on the status of [CI/CD variables](../variables/README.md). -The `variables` keyword defines variable expressions. +**Keyword type**: Job keyword. You can use it only as part of a job. -These expressions determine whether or not a job should be created. +**Possible inputs**: An array of [CI/CD variable expressions](../variables/README.md#cicd-variable-expressions). -Examples of variable expressions: +**Example of `only:variables`**: ```yaml deploy: script: cap staging deploy only: - refs: - - branches variables: - $RELEASE == "staging" - $STAGING ``` -Another use case is excluding jobs depending on a commit message: - -```yaml -end-to-end: - script: rake test:end-to-end - except: - variables: - - $CI_COMMIT_MESSAGE =~ /skip-end-to-end-tests/ -``` - -You can use [parentheses](../variables/README.md#parentheses) with `&&` and `||` to build more complicated variable expressions. -[Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/230938) in GitLab 13.3: +**Related topics**: -```yaml -job1: - script: - - echo This rule uses parentheses. - only: - variables: - - ($CI_COMMIT_BRANCH == "master" || $CI_COMMIT_BRANCH == "develop") && $MY_VARIABLE -``` +- [`only:variables` and `except:variables` examples](../jobs/job_control.md#only-variables--except-variables-examples). -#### `only:changes`/`except:changes` +#### `only:changes` / `except:changes` -> `changes` policy [introduced](https://gitlab.com/gitlab-org/gitlab-foss/-/issues/19232) in GitLab 11.4. +> [Introduced](https://gitlab.com/gitlab-org/gitlab-foss/-/issues/19232) in GitLab 11.4. Use the `changes` keyword with `only` to run a job, or with `except` to skip a job, when a Git push event modifies a file. -Use `only:changes` with pipelines triggered by the following refs only: +Use `changes` in pipelines with the following refs: - `branches` - `external_pull_requests` -- `merge_requests` (see additional details about [using `only:changes` with pipelines for merge requests](#use-onlychanges-with-pipelines-for-merge-requests)) +- `merge_requests` (see additional details about [using `only:changes` with pipelines for merge requests](../jobs/job_control.md#use-onlychanges-with-pipelines-for-merge-requests)) -WARNING: -In pipelines with [sources other than the three above](../variables/predefined_variables.md) -`changes` can't determine if a given file is new or old and always returns `true`. -You can configure jobs to use `only: changes` with other `only: refs` keywords. However, -those jobs ignore the changes and always run. +**Keyword type**: Job keyword. You can use it only as part of a job. -In the following example, when you push commits to an existing branch, the `docker build` job -runs only if any of these files change: +**Possible inputs**: An array including any number of: -- The `Dockerfile` file. -- Files in the `docker/scripts/` directory. -- Files and subdirectories in the `dockerfiles` directory. -- Files with `rb`, `py`, `sh` extensions in the `more_scripts` directory. +- Paths to files. +- Wildcard paths for single directories, for example `path/to/directory/*`, or a directory + and all its subdirectories, for example `path/to/directory/**/*`. +- Wildcard ([glob](https://en.wikipedia.org/wiki/Glob_(programming))) paths for all + files with the same extension or multiple extensions, for example `*.md` or `path/to/directory/*.{rb,py,sh}`. +- Wildcard paths to files in the root directory, or all directories, wrapped in double quotes. + For example `"*.json"` or `"**/*.json"`. + +**Example of `only:changes`**: ```yaml docker build: @@ -1909,110 +1779,40 @@ docker build: - more_scripts/*.{rb,py,sh} ``` -WARNING: -If you use `only:changes` with [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), -you should [also use `only:merge_requests`](#use-onlychanges-with-pipelines-for-merge-requests). Otherwise it may not work as expected. +**Additional details**: -You can also use [glob](https://en.wikipedia.org/wiki/Glob_(programming)) -patterns to match multiple files in either the root directory -of the repository, or in _any_ directory in the repository. However, they must be wrapped -in double quotes or GitLab can't parse them: +- If you use refs other than `branches`, `external_pull_requests`, or `merge_requests`, + `changes` can't determine if a given file is new or old and always returns `true`. +- If you use `only: changes` with other refs, jobs ignore the changes and always run. +- If you use `except: changes` with other refs, jobs ignore the changes and never run. -```yaml -test: - script: npm run test - only: - refs: - - branches - changes: - - "*.json" - - "**/*.sql" -``` +**Related topics**: -You can skip a job if a change is detected in any file with a -`.md` extension in the root directory of the repository: +- [`only: changes` and `except: changes` examples](../jobs/job_control.md#onlychanges--exceptchanges-examples). +- If you use `changes` with [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), + you should [also use `only:merge_requests`](../jobs/job_control.md#use-onlychanges-with-pipelines-for-merge-requests). +- Use `changes` with [new branches or tags *without* pipelines for merge requests](../jobs/job_control.md#use-onlychanges-without-pipelines-for-merge-requests). +- Use `changes` with [scheduled pipelines](../jobs/job_control.md#use-onlychanges-with-scheduled-pipelines). -```yaml -build: - script: npm run build - except: - changes: - - "*.md" -``` +#### `only:kubernetes` / `except:kubernetes` -If you change multiple files, but only one file ends in `.md`, -the `build` job is still skipped. The job does not run for any of the files. +Use `only:kubernetes` or `except:kubernetes` to control if jobs are added to the pipeline +when the Kubernetes service is active in the project. -Read more about how to use this feature with: +**Keyword type**: Job-specific. You can use it only as part of a job. -- [New branches or tags *without* pipelines for merge requests](#use-onlychanges-without-pipelines-for-merge-requests). -- [Scheduled pipelines](#use-onlychanges-with-scheduled-pipelines). +**Possible inputs**: The `kubernetes` strategy accepts only the `active` keyword. -##### Use `only:changes` with pipelines for merge requests - -With [pipelines for merge requests](../merge_request_pipelines/index.md), -it's possible to define a job to be created based on files modified -in a merge request. - -Use this keyword with `only: [merge_requests]` so GitLab can find the correct base -SHA of the source branch. File differences are correctly calculated from any further -commits, and all changes in the merge requests are properly tested in pipelines. - -For example: +**Example of `only:kubernetes`**: ```yaml -docker build service one: - script: docker build -t my-service-one-image:$CI_COMMIT_REF_SLUG . - only: - refs: - - merge_requests - changes: - - Dockerfile - - service-one/**/* -``` - -In this scenario, if a merge request changes -files in the `service-one` directory or the `Dockerfile`, GitLab creates -the `docker build service one` job. - -For example: - -```yaml -docker build service one: - script: docker build -t my-service-one-image:$CI_COMMIT_REF_SLUG . +deploy: only: - changes: - - Dockerfile - - service-one/**/* + kubernetes: active ``` -In this example, the pipeline might fail because of changes to a file in `service-one/**/*`. - -A later commit that doesn't have changes in `service-one/**/*` -but does have changes to the `Dockerfile` can pass. The job -only tests the changes to the `Dockerfile`. - -GitLab checks the **most recent pipeline** that **passed**. If the merge request is mergeable, -it doesn't matter that an earlier pipeline failed because of a change that has not been corrected. - -When you use this configuration, ensure that the most recent pipeline -properly corrects any failures from previous pipelines. - -##### Use `only:changes` without pipelines for merge requests - -Without [pipelines for merge requests](../merge_request_pipelines/index.md), pipelines -run on branches or tags that don't have an explicit association with a merge request. -In this case, a previous SHA is used to calculate the diff, which is equivalent to `git diff HEAD~`. -This can result in some unexpected behavior, including: - -- When pushing a new branch or a new tag to GitLab, the policy always evaluates to true. -- When pushing a new commit, the changed files are calculated by using the previous commit - as the base SHA. - -##### Use `only:changes` with scheduled pipelines - -`only:changes` always evaluates as true in [Scheduled pipelines](../pipelines/schedules.md). -All files are considered to have changed when a scheduled pipeline runs. +In this example, the `deploy` job runs only when the Kubernetes service is active +in the project. ### `needs` @@ -2281,7 +2081,7 @@ This feature might not be available to you. Check the **version history** note a To need a job that sometimes does not exist in the pipeline, add `optional: true` to the `needs` configuration. If not defined, `optional: false` is the default. -Jobs that use [`rules`](#rules), [`only`, or `except`](#onlyexcept-basic), might +Jobs that use [`rules`](#rules), [`only`, or `except`](#only--except), might not always exist in a pipeline. When the pipeline starts, it checks the `needs` relationships before running. Without `optional: true`, needs relationships that point to a job that does not exist stops the pipeline from starting and causes a pipeline @@ -2755,8 +2555,8 @@ The `stop_review_app` job is **required** to have the following keywords defined - `environment:name` - `environment:action` -Additionally, both jobs should have matching [`rules`](#onlyexcept-basic) -or [`only/except`](#onlyexcept-basic) configuration. +Additionally, both jobs should have matching [`rules`](#only--except) +or [`only/except`](#only--except) configuration. In the examples above, if the configuration is not identical: @@ -2956,11 +2756,7 @@ You can specify a [fallback cache key](#fallback-cache-key) to use if the specif ##### Multiple caches > - [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/32814) in GitLab 13.10. -> - [Deployed behind a feature flag](../../user/feature_flags.md), disabled by default. -> - [Enabled by default](https://gitlab.com/gitlab-org/gitlab/-/issues/321877) in GitLab 13.11. -> - Enabled on GitLab.com. -> - Recommended for production use. -> - For GitLab self-managed instances, GitLab administrators can opt to [disable it](#enable-or-disable-multiple-caches). **(FREE SELF)** +> - [Feature Flag removed](https://gitlab.com/gitlab-org/gitlab/-/issues/321877), in GitLab 13.12. You can have a maximum of four caches: @@ -2987,25 +2783,6 @@ test-job: If multiple caches are combined with a [Fallback cache key](#fallback-cache-key), the fallback is fetched multiple times if multiple caches are not found. -##### Enable or disable multiple caches **(FREE SELF)** - -The multiple caches feature is under development but ready for production use. -It is deployed behind a feature flag that is **enabled by default**. -[GitLab administrators with access to the GitLab Rails console](../../administration/feature_flags.md) -can opt to disable it. - -To enable it: - -```ruby -Feature.enable(:multiple_cache_per_job) -``` - -To disable it: - -```ruby -Feature.disable(:multiple_cache_per_job) -``` - #### Fallback cache key > [Introduced](https://gitlab.com/gitlab-org/gitlab-runner/-/merge_requests/1534) in GitLab Runner 13.4. @@ -3273,10 +3050,6 @@ If the artifacts of the job that is set as a dependency are [deleted](../pipelines/job_artifacts.md#delete-job-artifacts), then the dependent job fails. -You can ask your administrator to -[flip this switch](../../administration/job_artifacts.md#validation-for-dependencies) -and bring back the old behavior. - #### `artifacts:exclude` > - [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/15122) in GitLab 13.1 @@ -3318,25 +3091,25 @@ Files matched by [`artifacts:untracked`](#artifactsuntracked) can be excluded us #### `artifacts:expire_in` -Use `expire_in` to specify how long artifacts are active before they -expire and are deleted. - -The expiration time period begins when the artifact is uploaded and -stored on GitLab. If the expiry time is not defined, it defaults to the -[instance wide setting](../../user/admin_area/settings/continuous_integration.md#default-artifacts-expiration) -(30 days by default). - -To override the expiration date and protect artifacts from being automatically deleted: +> - [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/16267) in GitLab 13.0 behind a disabled feature flag, the latest job artifacts are kept regardless of expiry time. +> - [Made default behavior](https://gitlab.com/gitlab-org/gitlab/-/issues/229936) in GitLab 13.4. +> - [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/241026) in GitLab 13.8, keeping latest job artifacts can be disabled at the project level. +> - [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/276583) in GitLab 13.9, keeping latest job artifacts can be disabled instance-wide. +> - [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/321323) in GitLab 13.12, the latest pipeline artifacts are kept regardless of expiry time. -- Use the **Keep** button on the job page. -- Set the value of `expire_in` to `never`. [Available](https://gitlab.com/gitlab-org/gitlab/-/issues/22761) - in GitLab 13.3 and later. +Use `expire_in` to specify how long [job artifacts](../pipelines/job_artifacts.md) are stored before +they expire and are deleted. The `expire_in` setting does not affect: -After their expiry, artifacts are deleted hourly by default (via a cron job), -and are not accessible anymore. +- Artifacts from the latest job, unless this keeping the latest job artifacts is: + - [Disabled at the project level](../pipelines/job_artifacts.md#keep-artifacts-from-most-recent-successful-jobs). + - [Disabled instance-wide](../../user/admin_area/settings/continuous_integration.md#keep-the-latest-artifacts-for-all-jobs-in-the-latest-successful-pipelines). +- [Pipeline artifacts](../pipelines/pipeline_artifacts.md). It's not possible to specify an + expiration date for these: + - Pipeline artifacts from the latest pipeline are kept forever. + - Other pipeline artifacts are erased after one week. -The value of `expire_in` is an elapsed time in seconds, unless a unit is -provided. Examples of valid values: +The value of `expire_in` is an elapsed time in seconds, unless a unit is provided. Valid values +include: - `'42'` - `42 seconds` @@ -3348,7 +3121,7 @@ provided. Examples of valid values: - `3 weeks and 2 days` - `never` -To expire artifacts 1 week after being uploaded: +To expire artifacts one week after being uploaded: ```yaml job: @@ -3356,12 +3129,19 @@ job: expire_in: 1 week ``` -The latest artifacts for refs are locked against deletion, and kept regardless of -the expiry time. [Introduced in](https://gitlab.com/gitlab-org/gitlab/-/issues/16267) -GitLab 13.0 behind a disabled feature flag, and [made the default behavior](https://gitlab.com/gitlab-org/gitlab/-/issues/229936) -in GitLab 13.4. +The expiration time period begins when the artifact is uploaded and stored on GitLab. If the expiry +time is not defined, it defaults to the +[instance wide setting](../../user/admin_area/settings/continuous_integration.md#default-artifacts-expiration) +(30 days by default). -In [GitLab 13.8 and later](https://gitlab.com/gitlab-org/gitlab/-/issues/241026), you can [disable this behavior at the project level in the CI/CD settings](../pipelines/job_artifacts.md#keep-artifacts-from-most-recent-successful-jobs). In [GitLab 13.9 and later](https://gitlab.com/gitlab-org/gitlab/-/issues/276583), you can [disable this behavior instance-wide](../../user/admin_area/settings/continuous_integration.md#keep-the-latest-artifacts-for-all-jobs-in-the-latest-successful-pipelines). +To override the expiration date and protect artifacts from being automatically deleted: + +- Use the **Keep** button on the job page. +- [In GitLab 13.3 and later](https://gitlab.com/gitlab-org/gitlab/-/issues/22761), set the value of + `expire_in` to `never`. + +After their expiry, artifacts are deleted hourly by default (using a cron job), and are not +accessible anymore. #### `artifacts:expose_as` @@ -3612,8 +3392,8 @@ third party ports for other languages like JavaScript, Python, Ruby, and so on. ##### `artifacts:reports:codequality` -> - Introduced in [GitLab Starter](https://about.gitlab.com/pricing/) 11.5. -> - Made [available in all tiers](https://gitlab.com/gitlab-org/gitlab/-/issues/212499) in GitLab 13.2. +> - Introduced in GitLab 11.5. +> - [Moved](https://gitlab.com/gitlab-org/gitlab/-/issues/212499) to GitLab Free in 13.2. > - Requires GitLab Runner 11.5 and above. The `codequality` report collects [Code Quality issues](../../user/project/merge_requests/code_quality.md) @@ -3865,7 +3645,9 @@ failure. 1. `on_success` (default): Upload artifacts only when the job succeeds. 1. `on_failure`: Upload artifacts only when the job fails. -1. `always`: Always upload artifacts. +1. `always`: Always upload artifacts. Useful, for example, when + [uploading artifacts](../unit_test_reports.md#viewing-junit-screenshots-on-gitlab) required to + troubleshoot failing tests. For example, to upload artifacts only when a job fails: @@ -4472,6 +4254,7 @@ These keywords are supported: - [`ref`](#releaseref) (optional) - [`milestones`](#releasemilestones) (optional) - [`released_at`](#releasereleased_at) (optional) +- [`assets:links`](#releaseassetslinks) (optional) The release is created only if the job processes without error. If the Rails API returns an error during release creation, the `release` job fails. @@ -4680,6 +4463,26 @@ defined. Should be enclosed in quotes and expressed in ISO 8601 format. released_at: '2021-03-15T08:00:00Z' ``` +#### `release:assets:links` + +> [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/271454) in GitLab 13.12. + +Include [asset links](../../user/project/releases/index.md#release-assets) in the release. + +NOTE: +Requires `release-cli` version v0.4.0 or higher. + +```yaml +assets: + links: + - name: 'asset1' + url: 'https://example.com/assets/1' + - name: 'asset2' + url: 'https://example.com/assets/2' + filepath: '/pretty/url/1' # optional + link_type: 'other' # optional +``` + #### Complete example for `release` If you combine the previous examples for `release`, you get two options, depending on how you generate the @@ -4706,6 +4509,14 @@ tags. You can't use these options together, so choose one: - 'm2' - 'm3' released_at: '2020-07-15T08:00:00Z' # Optional, is auto generated if not defined, or can use a variable. + assets: # Optional, multiple asset links + links: + - name: 'asset1' + url: 'https://example.com/assets/1' + - name: 'asset2' + url: 'https://example.com/assets/2' + filepath: '/pretty/url/1' # optional + link_type: 'other' # optional ``` - To create a release automatically when commits are pushed or merged to the default branch, @@ -4752,6 +4563,14 @@ tags. You can't use these options together, so choose one: - 'm2' - 'm3' released_at: '2020-07-15T08:00:00Z' # Optional, is auto generated if not defined, or can use a variable. + assets: + links: + - name: 'asset1' + url: 'https://example.com/assets/1' + - name: 'asset2' + url: 'https://example.com/assets/2' + filepath: '/pretty/url/1' # optional + link_type: 'other' # optional ``` #### Release assets as Generic packages @@ -4769,7 +4588,7 @@ You can also call the `release-cli` directly from a `script` entry. For example, if you use the YAML described previously: ```shell -release-cli create --name "Release $CI_COMMIT_SHA" --description "Created using the release-cli $EXTRA_DESCRIPTION" --tag-name "v${MAJOR}.${MINOR}.${REVISION}" --ref "$CI_COMMIT_SHA" --released-at "2020-07-15T08:00:00Z" --milestone "m1" --milestone "m2" --milestone "m3" +release-cli create --name "Release $CI_COMMIT_SHA" --description "Created using the release-cli $EXTRA_DESCRIPTION" --tag-name "v${MAJOR}.${MINOR}.${REVISION}" --ref "$CI_COMMIT_SHA" --released-at "2020-07-15T08:00:00Z" --milestone "m1" --milestone "m2" --milestone "m3" --assets-link "{\"name\":\"asset1\",\"url\":\"https://example.com/assets/1\",\"link_type\":\"other\"} ``` ### `secrets` diff --git a/doc/ci/yaml/script.md b/doc/ci/yaml/script.md index 4fc52995fc1..f4e099c3128 100644 --- a/doc/ci/yaml/script.md +++ b/doc/ci/yaml/script.md @@ -86,7 +86,7 @@ Second command line. When you omit the `>` or `|` block scalar indicators, GitLab concatenates non-empty lines to form the command. Make sure the lines can run when concatenated. -[Shell here documents](https://en.wikipedia.org/wiki/Here_document) work with the +[These documents](https://en.wikipedia.org/wiki/Here_document) work with the `|` and `>` operators as well. The example below transliterates lower case letters to upper case: diff --git a/doc/ci/yaml/visualization.md b/doc/ci/yaml/visualization.md deleted file mode 100644 index ff3b0456eca..00000000000 --- a/doc/ci/yaml/visualization.md +++ /dev/null @@ -1,8 +0,0 @@ ---- -redirect_to: '../pipeline_editor/index.md#visualize-ci-configuration' ---- - -This document was moved to [another location](../pipeline_editor/index.md#visualize-ci-configuration). - -<!-- This redirect file can be deleted after 2021-04-13. --> -<!-- Before deletion, see: https://docs.gitlab.com/ee/development/documentation/#move-or-rename-a-page --> |
