diff options
Diffstat (limited to 'doc/ci')
-rw-r--r-- | doc/ci/caching/index.md | 2 | ||||
-rw-r--r-- | doc/ci/directed_acyclic_graph/index.md | 6 | ||||
-rw-r--r-- | doc/ci/environments/index.md | 8 | ||||
-rw-r--r-- | doc/ci/jobs/job_control.md | 8 | ||||
-rw-r--r-- | doc/ci/migration/jenkins.md | 10 | ||||
-rw-r--r-- | doc/ci/pipelines/merge_request_pipelines.md | 4 | ||||
-rw-r--r-- | doc/ci/pipelines/multi_project_pipelines.md | 2 | ||||
-rw-r--r-- | doc/ci/pipelines/parent_child_pipelines.md | 4 | ||||
-rw-r--r-- | doc/ci/pipelines/pipeline_architectures.md | 4 | ||||
-rw-r--r-- | doc/ci/pipelines/settings.md | 2 | ||||
-rw-r--r-- | doc/ci/services/gitlab.md | 2 | ||||
-rw-r--r-- | doc/ci/triggers/index.md | 2 | ||||
-rw-r--r-- | doc/ci/troubleshooting.md | 2 | ||||
-rw-r--r-- | doc/ci/yaml/index.md | 150 | ||||
-rw-r--r-- | doc/ci/yaml/script.md | 4 |
15 files changed, 105 insertions, 105 deletions
diff --git a/doc/ci/caching/index.md b/doc/ci/caching/index.md index 57cbf387115..491454aed28 100644 --- a/doc/ci/caching/index.md +++ b/doc/ci/caching/index.md @@ -27,7 +27,7 @@ can't link to files outside it. ### Cache -- Define cache per job by using the `cache:` keyword. Otherwise it is disabled. +- Define cache per job by using the `cache` keyword. Otherwise it is disabled. - Subsequent pipelines can use the cache. - Subsequent jobs in the same pipeline can use the cache, if the dependencies are identical. - Different projects cannot share the cache. diff --git a/doc/ci/directed_acyclic_graph/index.md b/doc/ci/directed_acyclic_graph/index.md index f26a678962a..abf43390834 100644 --- a/doc/ci/directed_acyclic_graph/index.md +++ b/doc/ci/directed_acyclic_graph/index.md @@ -66,9 +66,9 @@ as quickly as possible. ## Usage -Relationships are defined between jobs using the [`needs:` keyword](../yaml/index.md#needs). +Relationships are defined between jobs using the [`needs` keyword](../yaml/index.md#needs). -Note that `needs:` also works with the [parallel](../yaml/index.md#parallel) keyword, +Note that `needs` also works with the [parallel](../yaml/index.md#parallel) keyword, giving you powerful options for parallelization within your pipeline. ## Limitations @@ -87,7 +87,7 @@ are certain use cases that you may need to work around. For more information, ch The needs visualization makes it easier to visualize the relationships between dependent jobs in a DAG. This graph displays all the jobs in a pipeline that need or are needed by other jobs. Jobs with no relationships are not displayed in this view. -To see the needs visualization, click on the **Needs** tab when viewing a pipeline that uses the `needs:` keyword. +To see the needs visualization, click on the **Needs** tab when viewing a pipeline that uses the `needs` keyword. ![Needs visualization example](img/dag_graph_example_v13_1.png) diff --git a/doc/ci/environments/index.md b/doc/ci/environments/index.md index fe6844b89a2..8e88c5f89e8 100644 --- a/doc/ci/environments/index.md +++ b/doc/ci/environments/index.md @@ -294,7 +294,7 @@ As soon as the `review` job finishes, GitLab updates the `review/your-branch-nam environment's URL. It parses the `deploy.env` report artifact, registers a list of variables as runtime-created, uses it for expanding `environment:url: $DYNAMIC_ENVIRONMENT_URL` and sets it to the environment URL. -You can also specify a static part of the URL at `environment:url:`, such as +You can also specify a static part of the URL at `environment:url`, such as `https://$DYNAMIC_ENVIRONMENT_URL`. If the value of `DYNAMIC_ENVIRONMENT_URL` is `example.com`, the final result is `https://example.com`. @@ -303,7 +303,7 @@ The assigned URL for the `review/your-branch-name` environment is visible in the Note the following: - `stop_review` doesn't generate a dotenv report artifact, so it doesn't recognize the - `DYNAMIC_ENVIRONMENT_URL` environment variable. Therefore you shouldn't set `environment:url:` in the + `DYNAMIC_ENVIRONMENT_URL` environment variable. Therefore you shouldn't set `environment:url` in the `stop_review` job. - If the environment URL isn't valid (for example, the URL is malformed), the system doesn't update the environment URL. @@ -451,7 +451,7 @@ Read more in the [`.gitlab-ci.yml` reference](../yaml/index.md#environmenton_sto You can set an environment to stop when another job is finished. -In your `.gitlab-ci.yml` file, specify in the [`on_stop:`](../yaml/index.md#environmenton_stop) +In your `.gitlab-ci.yml` file, specify in the [`on_stop`](../yaml/index.md#environmenton_stop) keyword the name of the job that stops the environment. The following example shows a `review_app` job that calls a `stop_review_app` job after the first @@ -478,7 +478,7 @@ The `stop_review_app` job **must** have the following keywords defined: - `when`, defined at either: - [The job level](../yaml/index.md#when). - - [In a rules clause](../yaml/index.md#rules). If you use `rules:` and `when: manual`, you should + - [In a rules clause](../yaml/index.md#rules). If you use `rules` and `when: manual`, you should also set [`allow_failure: true`](../yaml/index.md#allow_failure) so the pipeline can complete even if the job doesn't run. - `environment:name` diff --git a/doc/ci/jobs/job_control.md b/doc/ci/jobs/job_control.md index cb7e779051d..dd6b6c0f006 100644 --- a/doc/ci/jobs/job_control.md +++ b/doc/ci/jobs/job_control.md @@ -79,7 +79,7 @@ job: - In **all other cases**, the job is added to the pipeline, with `when: on_success`. WARNING: -If you use a `when:` clause as the final rule (not including `when: never`), two +If you use a `when` clause as the final rule (not including `when: never`), two simultaneous pipelines may start. Both push pipelines and merge request pipelines can be triggered by the same event (a push to the source branch for an open merge request). See how to [prevent duplicate pipelines](#avoid-duplicate-pipelines) @@ -153,7 +153,7 @@ To avoid duplicate pipelines, you can: - Use [`workflow`](../yaml/index.md#workflow) to specify which types of pipelines can run. - Rewrite the rules to run the job only in very specific cases, - and avoid a final `when:` rule: + and avoid a final `when` rule: ```yaml job: @@ -480,8 +480,8 @@ All files are considered to have changed when a scheduled pipeline runs. 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. +- `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: diff --git a/doc/ci/migration/jenkins.md b/doc/ci/migration/jenkins.md index c2c06375d7b..041b1bd45ea 100644 --- a/doc/ci/migration/jenkins.md +++ b/doc/ci/migration/jenkins.md @@ -146,15 +146,15 @@ as well. Jenkins Pipelines are based on [Groovy](https://groovy-lang.org/), so the pipeline specification is written as code. GitLab works a bit differently, we use the more highly structured [YAML](https://yaml.org/) format, which -places scripting elements inside of `script:` blocks separate from the pipeline specification itself. +places scripting elements inside of `script` blocks separate from the pipeline specification itself. This is a strength of GitLab, in that it helps keep the learning curve much simpler to get up and running and avoids some of the problem of unconstrained complexity which can make your Jenkinsfile hard to understand and manage. That said, we do of course still value DRY (don't repeat yourself) principles and want to ensure that -behaviors of your jobs can be codified once and applied as needed. You can use the `extends:` syntax to -[reuse configuration in your jobs](../yaml/index.md#extends), and `include:` can +behaviors of your jobs can be codified once and applied as needed. You can use the `extends` syntax to +[reuse configuration in your jobs](../yaml/index.md#extends), and `include` can be used to [reuse pipeline configurations](../yaml/index.md#include) in pipelines in different projects: @@ -174,7 +174,7 @@ rspec: ## Artifact publishing Artifacts may work a bit differently than you've used them with Jenkins. In GitLab, any job can define -a set of artifacts to be saved by using the `artifacts:` keyword. This can be configured to point to a file +a set of artifacts to be saved by using the `artifacts` keyword. This can be configured to point to a file or set of files that can then be persisted from job to job. Read more on our detailed [artifacts documentation](../pipelines/job_artifacts.md): @@ -271,7 +271,7 @@ default: GitLab CI/CD also lets you define stages, but is a little bit more free-form to configure. The GitLab [`stages` keyword](../yaml/index.md#stages) is a top level setting that enumerates the list of stages, but you are not required to nest individual jobs underneath the `stages` section. Any job defined in the `.gitlab-ci.yml` can be made a part of any stage through use of the -[`stage:` keyword](../yaml/index.md#stage). +[`stage` keyword](../yaml/index.md#stage). Note that, unless otherwise specified, every pipeline is instantiated with a `build`, `test`, and `deploy` stage which are run in that order. Jobs that have no `stage` defined are placed by default in the `test` stage. diff --git a/doc/ci/pipelines/merge_request_pipelines.md b/doc/ci/pipelines/merge_request_pipelines.md index 119633d38e2..85e5b62b0c4 100644 --- a/doc/ci/pipelines/merge_request_pipelines.md +++ b/doc/ci/pipelines/merge_request_pipelines.md @@ -112,11 +112,11 @@ C: - merge_requests ``` -- `A` and `B` always run, because they get the `only:` rule to execute in all cases. +- `A` and `B` always run, because they get the `only` rule to execute in all cases. - `C` only runs for merge requests. It doesn't run for any pipeline except a merge request pipeline. -In this example, you don't have to add the `only:` rule to all of your jobs to make +In this example, you don't have to add the `only` rule to all of your jobs to make them always run. You can use this format to set up a Review App, which helps to save resources. diff --git a/doc/ci/pipelines/multi_project_pipelines.md b/doc/ci/pipelines/multi_project_pipelines.md index 30b3bc2e277..8a83e7e31f4 100644 --- a/doc/ci/pipelines/multi_project_pipelines.md +++ b/doc/ci/pipelines/multi_project_pipelines.md @@ -213,7 +213,7 @@ In the upstream pipeline: ``` 1. Set the `test` job in the downstream pipeline to inherit the variables from the `build_vars` - job in the upstream project with `needs:`. The `test` job inherits the variables in the + job in the upstream project with `needs`. The `test` job inherits the variables in the `dotenv` report and it can access `BUILD_VERSION` in the script: ```yaml diff --git a/doc/ci/pipelines/parent_child_pipelines.md b/doc/ci/pipelines/parent_child_pipelines.md index 5b8729757cc..5e4b707a38c 100644 --- a/doc/ci/pipelines/parent_child_pipelines.md +++ b/doc/ci/pipelines/parent_child_pipelines.md @@ -42,7 +42,7 @@ Child pipelines work well with other GitLab CI/CD features: - 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. -See the [`trigger:`](../yaml/index.md#trigger) keyword documentation for full details on how to +See the [`trigger`](../yaml/index.md#trigger) keyword documentation for full details on how to include the child pipeline configuration. <i class="fa fa-youtube-play youtube" aria-hidden="true"></i> @@ -84,7 +84,7 @@ microservice_a: file: '/path/to/child-pipeline.yml' ``` -The maximum number of entries that are accepted for `trigger:include:` is three. +The maximum number of entries that are accepted for `trigger:include` is three. Similar to [multi-project pipelines](multi_project_pipelines.md#mirror-status-of-a-triggered-pipeline-in-the-trigger-job), we can set the parent pipeline to depend on the status of the child pipeline upon completion: diff --git a/doc/ci/pipelines/pipeline_architectures.md b/doc/ci/pipelines/pipeline_architectures.md index 1b23727b142..3ff22a16900 100644 --- a/doc/ci/pipelines/pipeline_architectures.md +++ b/doc/ci/pipelines/pipeline_architectures.md @@ -211,7 +211,7 @@ trigger_b: ``` Example child `a` pipeline configuration, located in `/a/.gitlab-ci.yml`, making -use of the DAG `needs:` keyword: +use of the DAG `needs` keyword: ```yaml stages: @@ -240,7 +240,7 @@ deploy_a: ``` Example child `b` pipeline configuration, located in `/b/.gitlab-ci.yml`, making -use of the DAG `needs:` keyword: +use of the DAG `needs` keyword: ```yaml stages: diff --git a/doc/ci/pipelines/settings.md b/doc/ci/pipelines/settings.md index a8ecb5e0d74..e8789cc2326 100644 --- a/doc/ci/pipelines/settings.md +++ b/doc/ci/pipelines/settings.md @@ -267,7 +267,7 @@ when merging a merge request would cause the project's test coverage to decline. Follow these steps to enable the `Coverage-Check` MR approval rule: -1. Set up a [`coverage:`](../yaml/index.md#coverage) regular expression for all jobs you want to include in the overall coverage value. +1. Set up a [`coverage`](../yaml/index.md#coverage) regular expression for all jobs you want to include in the overall coverage value. 1. Go to your project and select **Settings > General**. 1. Expand **Merge request approvals**. 1. Select **Enable** next to the `Coverage-Check` approval rule. diff --git a/doc/ci/services/gitlab.md b/doc/ci/services/gitlab.md index 5ac66846ab7..689ce884ae4 100644 --- a/doc/ci/services/gitlab.md +++ b/doc/ci/services/gitlab.md @@ -28,7 +28,7 @@ NOTE: Variables set in the GitLab UI are not passed down to the service containers. [Learn more](../variables/index.md#). -Then, commands in `script:` sections in your `.gitlab-ci.yml` file can access the API at `http://gitlab/api/v4`. +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 [How services are linked to the job](../docker/using_docker_images.md#extended-docker-configuration-options). diff --git a/doc/ci/triggers/index.md b/doc/ci/triggers/index.md index afcf8ae629a..1e586fdd016 100644 --- a/doc/ci/triggers/index.md +++ b/doc/ci/triggers/index.md @@ -23,7 +23,7 @@ depending on which trigger method is used. | `$CI_PIPELINE_SOURCE` value | Trigger method | |-----------------------------|----------------| -| `pipeline` | Using the `trigger:` keyword in the CI/CD configuration file, or using the trigger API with `$CI_JOB_TOKEN`. | +| `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/index.md#only--except). diff --git a/doc/ci/troubleshooting.md b/doc/ci/troubleshooting.md index 037e8d3497d..4d550f6da13 100644 --- a/doc/ci/troubleshooting.md +++ b/doc/ci/troubleshooting.md @@ -291,7 +291,7 @@ Pipeline configuration warnings are shown when you: ### "Job may allow multiple pipelines to run for a single action" warning -When you use [`rules`](yaml/index.md#rules) with a `when:` clause without an `if:` +When you use [`rules`](yaml/index.md#rules) with a `when` clause without an `if` clause, multiple pipelines may run. Usually this occurs when you push a commit to a branch that has an open merge request associated with it. diff --git a/doc/ci/yaml/index.md b/doc/ci/yaml/index.md index 6a7c9ae1673..83b627e08f7 100644 --- a/doc/ci/yaml/index.md +++ b/doc/ci/yaml/index.md @@ -73,7 +73,7 @@ or import additional pipeline configuration. ### `default` You can set global defaults for some keywords. Jobs that do not define one or more -of the listed keywords use the value defined in the `default:` section. +of the listed keywords use the value defined in the `default` section. **Keyword type**: Global keyword. @@ -90,7 +90,7 @@ of the listed keywords use the value defined in the `default:` section. - [`tags`](#tags) - [`timeout`](#timeout) -**Example of `default`:** +**Example of `default`**: ```yaml default: @@ -106,7 +106,7 @@ rspec 2.7: In this example, `ruby:3.0` is the default `image` value for all jobs in the pipeline. The `rspec 2.7` job does not use the default, because it overrides the default with -a job-specific `image:` section: +a job-specific `image` section: **Additional details**: @@ -324,7 +324,7 @@ The order of the items in `stages` defines the execution order for jobs: **Keyword type**: Global keyword. -**Example of `stages`:** +**Example of `stages`**: ```yaml stages: @@ -368,7 +368,7 @@ Use [`workflow`](workflow.md) to control pipeline behavior. #### `workflow:rules` -The `rules` keyword in `workflow` is similar to [`rules:` defined in jobs](#rules), +The `rules` keyword in `workflow` is similar to [`rules` defined in jobs](#rules), but controls whether or not a whole pipeline is created. When no rules evaluate to true, the pipeline does not run. @@ -381,7 +381,7 @@ When no rules evaluate to true, the pipeline does not run. - [`when`](#when), can only be `always` or `never` when used with `workflow`. - [`variables`](#workflowrulesvariables). -**Example of `workflow:rules`:** +**Example of `workflow:rules`**: ```yaml workflow: @@ -414,7 +414,7 @@ and the pipeline is for either: > - [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/294232) in GitLab 13.11. > - [Feature flag removed](https://gitlab.com/gitlab-org/gitlab/-/issues/300997) in GitLab 14.1. -You can use [`variables`](#variables) in `workflow:rules:` to define variables for +You can use [`variables`](#variables) in `workflow:rules` to define variables for specific pipeline conditions. When the condition matches, the variable is created and can be used by all jobs @@ -428,7 +428,7 @@ variable takes precedence and overrides the global variable. - The name can use only numbers, letters, and underscores (`_`). - The value must be a string. -**Example of `workflow:rules:variables`:** +**Example of `workflow:rules:variables`**: ```yaml variables: @@ -486,7 +486,7 @@ The following topics explain how to use keywords to configure CI/CD pipelines. Use `after_script` to define an array of commands that run after each job, including failed jobs. **Keyword type**: Job keyword. You can use it only as part of a job or in the -[`default:` section](#default). +[`default` section](#default). **Possible inputs**: An array including: @@ -494,7 +494,7 @@ Use `after_script` to define an array of commands that run after each job, inclu - Long commands [split over multiple lines](script.md#split-long-commands). - [YAML anchors](yaml_optimization.md#yaml-anchors-for-scripts). -**Example of `after_script`:** +**Example of `after_script`**: ```yaml job: @@ -585,7 +585,7 @@ In this example, `job1` and `job2` run in parallel: **Additional details**: -- You can use `allow_failure` as a subkey of [`rules:`](#rulesallow_failure). +- You can use `allow_failure` as a subkey of [`rules`](#rulesallow_failure). - You can use `allow_failure: false` with a manual job to create a [blocking manual job](../jobs/job_control.md#types-of-manual-jobs). A blocked pipeline does not run any jobs in later stages until the manual job is started and completes successfully. @@ -656,7 +656,7 @@ artifacts are restored after [caches](#cache). Use `artifacts:exclude` to prevent files from being added to an artifacts archive. **Keyword type**: Job keyword. You can use it only as part of a job or in the -[`default:` section](#default). +[`default` section](#default). **Possible inputs**: @@ -709,7 +709,7 @@ After their expiry, artifacts are deleted hourly by default (using a cron job), accessible anymore. **Keyword type**: Job keyword. You can use it only as part of a job or in the -[`default:` section](#default). +[`default` section](#default). **Possible inputs**: The expiry time. If no unit is provided, the time is in seconds. Valid values include: @@ -749,7 +749,7 @@ Use the `artifacts:expose_as` keyword to [expose job artifacts in the merge request UI](../pipelines/job_artifacts.md#expose-job-artifacts-in-the-merge-request-ui). **Keyword type**: Job keyword. You can use it only as part of a job or in the -[`default:` section](#default). +[`default` section](#default). **Possible inputs**: @@ -793,7 +793,7 @@ archive. You can specify a unique name for every archive. If not defined, the default name is `artifacts`, which becomes `artifacts.zip` when downloaded. **Keyword type**: Job keyword. You can use it only as part of a job or in the -[`default:` section](#default). +[`default` section](#default). **Possible inputs**: @@ -822,7 +822,7 @@ Paths are relative to the project directory (`$CI_PROJECT_DIR`) and can't direct link outside it. **Keyword type**: Job keyword. You can use it only as part of a job or in the -[`default:` section](#default). +[`default` section](#default). **Possible inputs**: @@ -872,7 +872,7 @@ To deny read access for anonymous and guest users to artifacts in public pipelines, set `artifacts:public` to `false`: **Keyword type**: Job keyword. You can use it only as part of a job or in the -[`default:` section](#default). +[`default` section](#default). **Possible inputs**: @@ -892,7 +892,7 @@ Use [`artifacts:reports`](artifacts_reports.md) to collect artifacts generated b included templates in jobs. **Keyword type**: Job keyword. You can use it only as part of a job or in the -[`default:` section](#default). +[`default` section](#default). **Possible inputs**: See list of available [artifacts reports types](artifacts_reports.md). @@ -925,7 +925,7 @@ with the paths defined in `artifacts:paths`). `artifacts:untracked` ignores conf in the repository's `.gitignore` file. **Keyword type**: Job keyword. You can use it only as part of a job or in the -[`default:` section](#default). +[`default` section](#default). **Possible inputs**: @@ -951,7 +951,7 @@ Use `artifacts:when` to upload artifacts on job failure or despite the failure. **Keyword type**: Job keyword. You can use it only as part of a job or in the -[`default:` section](#default). +[`default` section](#default). **Possible inputs**: @@ -975,7 +975,7 @@ Use `before_script` to define an array of commands that should run before each j `script` commands, but after [artifacts](#artifacts) are restored. **Keyword type**: Job keyword. You can use it only as part of a job or in the -[`default:` section](#default). +[`default` section](#default). **Possible inputs**: An array including: @@ -983,7 +983,7 @@ Use `before_script` to define an array of commands that should run before each j - Long commands [split over multiple lines](script.md#split-long-commands). - [YAML anchors](yaml_optimization.md#yaml-anchors-for-scripts). -**Example of `before_script`:** +**Example of `before_script`**: ```yaml job: @@ -1022,7 +1022,7 @@ Learn more about caches in [Caching in GitLab CI/CD](../caching/index.md). Use the `cache:paths` keyword to choose which files or directories to cache. **Keyword type**: Job keyword. You can use it only as part of a job or in the -[`default:` section](#default). +[`default` section](#default). **Possible inputs**: An array of paths relative to the project directory (`$CI_PROJECT_DIR`). You can use wildcards that use [glob](https://en.wikipedia.org/wiki/Glob_(programming)) @@ -1058,11 +1058,11 @@ rspec: Use the `cache:key` keyword to give each cache a unique identifying key. All jobs that use the same cache key use the same cache, including in different pipelines. -If not set, the default key is `default`. All jobs with the `cache:` keyword but +If not set, the default key is `default`. All jobs with the `cache` keyword but no `cache:key` share the `default` cache. **Keyword type**: Job keyword. You can use it only as part of a job or in the -[`default:` section](#default). +[`default` section](#default). **Possible inputs**: @@ -1112,7 +1112,7 @@ change. `cache:key:files` lets you reuse some caches, and rebuild them less ofte which speeds up subsequent pipeline runs. **Keyword type**: Job keyword. You can use it only as part of a job or in the -[`default:` section](#default). +[`default` section](#default). **Possible inputs**: An array of one or two file paths. @@ -1151,7 +1151,7 @@ that changed each listed file. Use `cache:key:prefix` to combine a prefix with the SHA computed for [`cache:key:files`](#cachekeyfiles). **Keyword type**: Job keyword. You can use it only as part of a job or in the -[`default:` section](#default). +[`default` section](#default). **Possible inputs**: @@ -1188,7 +1188,7 @@ is not found, the prefix is added to `default`, so the key in the example would Use `untracked: true` to cache all files that are untracked in your Git repository: **Keyword type**: Job keyword. You can use it only as part of a job or in the -[`default:` section](#default). +[`default` section](#default). **Possible inputs**: `true` or `false` (default). @@ -1222,7 +1222,7 @@ rspec: Use `cache:when` to define when to save the cache, based on the status of the job. **Keyword type**: Job keyword. You can use it only as part of a job or in the -[`default:` section](#default). +[`default` section](#default). **Possible inputs**: @@ -1260,7 +1260,7 @@ This policy speeds up job execution and reduces load on the cache server. You ca use a job with the `push` policy to build the cache. **Keyword type**: Job keyword. You can use it only as part of a job or in the -[`default:` section](#default). +[`default` section](#default). **Possible inputs**: @@ -1359,7 +1359,7 @@ dast: scanner_profile: "Quick Passive Test" ``` -In this example, the `dast` job extends the `dast` configuration added with the `include:` keyword +In this example, the `dast` job extends the `dast` configuration added with the `include` keyword to select a specific site profile and scanner profile. **Additional details**: @@ -1685,12 +1685,12 @@ and is a little more flexible and readable. **Keyword type**: Job keyword. You can use it only as part of a job. -**Possible inputs:** +**Possible inputs**: - The name of another job in the pipeline. - A list (array) of names of other jobs in the pipeline. -**Example of `extends`:** +**Example of `extends`**: ```yaml .tests: @@ -1728,7 +1728,7 @@ rspec: - $RSPEC ``` -**Additional details:** +**Additional details**: - In GitLab 12.0 and later, you can use multiple parents for `extends`. - The `extends` keyword supports up to eleven levels of inheritance, but you should @@ -1736,7 +1736,7 @@ rspec: - In the example above, `.tests` is a [hidden job](../jobs/index.md#hide-jobs), but you can extend configuration from regular jobs as well. -**Related topics:** +**Related topics**: - [Reuse configuration sections by using `extends`](yaml_optimization.md#use-extends-to-reuse-configuration-sections). - Use `extends` to reuse configuration from [included configuration files](yaml_optimization.md#use-extends-and-include-together). @@ -1746,7 +1746,7 @@ rspec: Use `image` to specify a Docker image that the job runs in. **Keyword type**: Job keyword. You can use it only as part of a job or in the -[`default:` section](#default). +[`default` section](#default). **Possible inputs**: The name of the image, including the registry path if needed, in one of these formats: @@ -1770,7 +1770,7 @@ rspec 2.7: In this example, the `ruby:3.0` image is the default for all jobs in the pipeline. The `rspec 2.7` job does not use the default, because it overrides the default with -a job-specific `image:` section. +a job-specific `image` section. **Related topics**: @@ -1778,10 +1778,10 @@ a job-specific `image:` section. #### `image:name` -The name of the Docker image that the job runs in. Similar to [`image:`](#image) used by itself. +The name of the Docker image that the job runs in. Similar to [`image`](#image) used by itself. **Keyword type**: Job keyword. You can use it only as part of a job or in the -[`default:` section](#default). +[`default` section](#default). **Possible inputs**: The name of the image, including the registry path if needed, in one of these formats: @@ -1809,7 +1809,7 @@ The syntax is similar to the [Dockerfile `ENTRYPOINT` directive](https://docs.do where each shell token is a separate string in the array. **Keyword type**: Job keyword. You can use it only as part of a job or in the -[`default:` section](#default). +[`default` section](#default). **Possible inputs**: A string. @@ -1829,7 +1829,7 @@ image: > [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/207484) in GitLab 12.9. -Use `inherit:` to [control inheritance of globally-defined defaults and variables](../jobs/index.md#control-the-inheritance-of-default-keywords-and-global-variables). +Use `inherit` to [control inheritance of globally-defined defaults and variables](../jobs/index.md#control-the-inheritance-of-default-keywords-and-global-variables). #### `inherit:default` @@ -1842,7 +1842,7 @@ Use `inherit:default` to control the inheritance of [default keywords](#default) - `true` (default) or `false` to enable or disable the inheritance of all default keywords. - A list of specific default keywords to inherit. -**Example of `inherit:default`:** +**Example of `inherit:default`**: ```yaml default: @@ -1863,7 +1863,7 @@ job2: - image ``` -**Additional details:** +**Additional details**: - You can also list default keywords to inherit on one line: `default: [keyword1, keyword2]` @@ -1878,7 +1878,7 @@ Use `inherit:variables` to control the inheritance of [global variables](#variab - `true` (default) or `false` to enable or disable the inheritance of all global variables. - A list of specific variables to inherit. -**Example of `inherit:variables`:** +**Example of `inherit:variables`**: ```yaml variables: @@ -1899,7 +1899,7 @@ job2: - VARIABLE2 ``` -**Additional details:** +**Additional details**: - You can also list global variables to inherit on one line: `variables: [VARIABLE1, VARIABLE2]` @@ -1916,7 +1916,7 @@ a new pipeline starts on the same branch. You can't cancel subsequent jobs after a job with `interruptible: false` starts. **Keyword type**: Job keyword. You can use it only as part of a job or in the -[`default:` section](#default). +[`default` section](#default). **Possible inputs**: `true` or `false` (default). @@ -1965,7 +1965,7 @@ In this example, a new pipeline causes a running pipeline to be: > - [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/30631) in GitLab 12.8, `needs: []` lets jobs start immediately. > - [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/30632) in GitLab 14.2, you can refer to jobs in the same stage as the job you are configuring. -Use `needs:` to execute jobs out-of-order. Relationships between jobs +Use `needs` to execute jobs out-of-order. Relationships between jobs that use `needs` can be visualized as a [directed acyclic graph](../directed_acyclic_graph/index.md). You can ignore stage ordering and run some jobs without waiting for others to complete. @@ -2022,11 +2022,11 @@ This example creates four paths of execution: **Additional details**: -- The maximum number of jobs that a single job can have in the `needs:` array is limited: +- The maximum number of jobs that a single job can have in the `needs` array is limited: - For GitLab.com, the limit is 50. For more information, see our [infrastructure issue](https://gitlab.com/gitlab-com/gl-infra/infrastructure/-/issues/7541). - For self-managed instances, the default limit is 50. This limit [can be changed](../../administration/cicd.md#set-the-needs-job-limit). -- If `needs:` refers to a job that uses the [`parallel`](#parallel) keyword, +- If `needs` refers to a job that uses the [`parallel`](#parallel) keyword, it depends on all jobs created in parallel, not just one job. It also downloads artifacts from all the parallel jobs by default. If the artifacts have the same name, they overwrite each other and only the last one downloaded is saved. @@ -2035,9 +2035,9 @@ This example creates four paths of execution: enabled on GitLab.com and ready for production use. On self-managed [GitLab 14.2 and later](https://gitlab.com/gitlab-org/gitlab/-/issues/30632) this feature is available by default. - In GitLab 14.0 and older, you can only refer to jobs in earlier stages. Stages must be - explicitly defined for all jobs that use the `needs:` keyword, or are referenced - in a job's `needs:` section. -- In GitLab 13.9 and older, if `needs:` refers to a job that might not be added to + explicitly defined for all jobs that use the `needs` keyword, or are referenced + in a job's `needs` section. +- In GitLab 13.9 and older, if `needs` refers to a job that might not be added to a pipeline because of `only`, `except`, or `rules`, the pipeline might fail to create. #### `needs:artifacts` @@ -2046,7 +2046,7 @@ This example creates four paths of execution: When a job uses `needs`, it no longer downloads all artifacts from previous stages by default, because jobs with `needs` can start before earlier stages complete. With -`needs` you can only download artifacts from the jobs listed in the `needs:` configuration. +`needs` you can only download artifacts from the jobs listed in the `needs` configuration. Use `artifacts: true` (default) or `artifacts: false` to control when artifacts are downloaded in jobs that use `needs`. @@ -2085,7 +2085,7 @@ In this example: - The `test-job1` job downloads the `build_job1` artifacts - The `test-job2` job does not download the `build_job2` artifacts. - The `test-job3` job downloads the artifacts from all three `build_jobs`, because - `artifacts:` is `true`, or defaults to `true`, for all three needed jobs. + `artifacts` is `true`, or defaults to `true`, for all three needed jobs. **Additional details**: @@ -2103,14 +2103,14 @@ If there is a pipeline running for the specified ref, a job with `needs:project` does not wait for the pipeline to complete. Instead, the job downloads the artifact from the latest pipeline that completed successfully. -`needs:project` must be used with `job:`, `ref:`, and `artifacts:`. +`needs:project` must be used with `job`, `ref`, and `artifacts`. **Keyword type**: Job keyword. You can use it only as part of a job. **Possible inputs**: - `needs:project`: A full project path, including namespace and group. If the - project is in the same group or namespace, you can omit them from the `project:` + project is in the same group or namespace, you can omit them from the `project` keyword. For example: `project: group/project-name` or `project: project-name`. - `job`: The job to download artifacts from. - `ref`: The ref to download artifacts from. @@ -2150,7 +2150,7 @@ build_job: **Additional details**: -- To download artifacts from a different pipeline in the current project, set `project:` +- To download artifacts from a different pipeline in the current project, set `project` to be the same as the current project, but use a different ref than the current pipeline. Concurrent pipelines running on the same ref could override the artifacts. - The user running the pipeline must have at least the Reporter role for the group or project, @@ -2160,7 +2160,7 @@ build_job: the needed job to complete. [Directed acyclic graph](../directed_acyclic_graph/index.md) behavior is limited to jobs in the same pipeline. Make sure that the needed job in the other pipeline completes before the job that needs it tries to download the artifacts. -- You can't download artifacts from jobs that run in [`parallel:`](#parallel). +- You can't download artifacts from jobs that run in [`parallel`](#parallel). - Support for [CI/CD variables](../variables/index.md) in `project`, `job`, and `ref` was [introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/202093) in GitLab 13.3. [Feature flag removed](https://gitlab.com/gitlab-org/gitlab/-/issues/235761) in GitLab 13.4. @@ -2182,7 +2182,7 @@ its parent pipeline or another child pipeline in the same parent-child pipeline **Possible inputs**: - `needs:pipeline`: A pipeline ID. Must be a pipeline present in the same parent-child pipeline hierarchy. -- `job:`: The job to download artifacts from. +- `job`: The job to download artifacts from. **Example of `needs:pipeline:job`**: @@ -2244,7 +2244,7 @@ error similar to: **Possible inputs**: -- `job:`: The job to make optional. +- `job`: The job to make optional. - `true` or `false` (default). **Example of `needs:optional`**: @@ -2281,7 +2281,7 @@ replicated to the bridge job. **Possible inputs**: - A full project path, including namespace and group. If the - project is in the same group or namespace, you can omit them from the `project:` + project is in the same group or namespace, you can omit them from the `project` keyword. For example: `project: group/project-name` or `project: project-name`. **Example of `needs:pipeline`**: @@ -2366,7 +2366,7 @@ job2: - schedules ``` -**Additional details:** +**Additional details**: - 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` @@ -2636,7 +2636,7 @@ you can use this image from the GitLab Container Registry: `registry.gitlab.com/ **Keyword type**: Job keyword. You can use it only as part of a job. -**Possible inputs**: The `release:` subkeys: +**Possible inputs**: The `release` subkeys: - [`tag_name`](#releasetag_name) - [`name`](#releasename) (optional) @@ -2873,7 +2873,7 @@ By default, all failure types cause the job to be retried. Use [`retry:when`](#r to select which failures to retry on. **Keyword type**: Job keyword. You can use it only as part of a job or in the -[`default:` section](#default). +[`default` section](#default). **Possible inputs**: `0` (default), `1`, or `2`. @@ -2892,7 +2892,7 @@ Use `retry:when` with `retry:max` to retry jobs for only specific failure cases. `0`, `1`, or `2`. **Keyword type**: Job keyword. You can use it only as part of a job or in the -[`default:` section](#default). +[`default` section](#default). **Possible inputs**: A single failure type, or an array of one or more failure types: @@ -2996,7 +2996,7 @@ Use `rules:if` clauses to specify when to add a job to a pipeline: - If an `if` statement is true, but it's combined with `when: never`, do not add the job to the pipeline. - If no `if` statements are true, do not add the job to the pipeline. -`if:` clauses are evaluated based on the values of [predefined CI/CD variables](../variables/predefined_variables.md) +`if` clauses are evaluated based on the values of [predefined CI/CD variables](../variables/predefined_variables.md) or [custom CI/CD variables](../variables/index.md#custom-cicd-variables). **Keyword type**: Job-specific and pipeline-specific. You can use it as part of a job @@ -3043,7 +3043,7 @@ You should use `rules: changes` only with **branch pipelines** or **merge reques You can use `rules: changes` with other pipeline types, but `rules: changes` always evaluates to true when there is no Git `push` event. Tag pipelines, scheduled pipelines, and so on do **not** have a Git `push` event associated with them. A `rules: changes` job -is **always** added to those pipelines if there is no `if:` that limits the job to +is **always** added to those pipelines if there is no `if` that limits the job to branch or merge request pipelines. **Keyword type**: Job keyword. You can use it only as part of a job. @@ -3112,7 +3112,7 @@ job: > [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/30235) in GitLab 12.8. -Use [`allow_failure: true`](#allow_failure) in `rules:` to allow a job to fail +Use [`allow_failure: true`](#allow_failure) in `rules` to allow a job to fail without stopping the pipeline. You can also use `allow_failure: true` with a manual job. The pipeline continues @@ -3147,7 +3147,7 @@ If the rule matches, then the job is a manual job with `allow_failure: true`. > - [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/209864) in GitLab 13.7. > - [Feature flag removed](https://gitlab.com/gitlab-org/gitlab/-/issues/289803) in GitLab 13.10. -Use [`variables`](#variables) in `rules:` to define variables for specific conditions. +Use [`variables`](#variables) in `rules` to define variables for specific conditions. **Keyword type**: Job-specific. You can use it only as part of a job. @@ -3185,7 +3185,7 @@ All jobs except [trigger jobs](#trigger) require a `script` keyword. - Long commands [split over multiple lines](script.md#split-long-commands). - [YAML anchors](yaml_optimization.md#yaml-anchors-for-scripts). -**Example of `script`:** +**Example of `script`**: ```yaml job1: @@ -3309,7 +3309,7 @@ Use `services` to specify an additional Docker image to run scripts in. The [`se to the image specified in the [`image`](#image) keyword. **Keyword type**: Job keyword. You can use it only as part of a job or in the -[`default:` section](#default). +[`default` section](#default). **Possible inputs**: The name of the services image, including the registry path if needed, in one of these formats: @@ -3482,7 +3482,7 @@ example `ruby`, `postgres`, or `development`. To pick up and run a job, a runner be assigned every tag listed in the job. **Keyword type**: Job keyword. You can use it only as part of a job or in the -[`default:` section](#default). +[`default` section](#default). **Possible inputs**: @@ -3520,7 +3520,7 @@ The job-level timeout can be longer than the [project-level timeout](../pipeline but can't be longer than the [runner's timeout](../runners/configure_runners.md#set-maximum-job-timeout-for-a-runner). **Keyword type**: Job keyword. You can use it only as part of a job or in the -[`default:` section](#default). +[`default` section](#default). **Possible inputs**: A period of time written in natural language. For example, these are all equivalent: @@ -3639,7 +3639,7 @@ variable defined, the [job-level variable takes precedence](../variables/index.m the first character must be a letter. - The value must be a string. -**Examples of `variables`:** +**Examples of `variables`**: ```yaml variables: @@ -3793,7 +3793,7 @@ Defining `image`, `services`, `cache`, `before_script`, and `after_script` globally is deprecated. Support could be removed from a future release. -Use [`default:`](#default) instead. For example: +Use [`default`](#default) instead. For example: ```yaml default: diff --git a/doc/ci/yaml/script.md b/doc/ci/yaml/script.md index c1b283ff10f..fdec0947df5 100644 --- a/doc/ci/yaml/script.md +++ b/doc/ci/yaml/script.md @@ -13,7 +13,7 @@ You can use special syntax in [`script`](index.md#script) sections to: - [Create custom collapsible sections](../jobs/index.md#custom-collapsible-sections) to simplify job log output. -## Use special characters with `script:` +## Use special characters with `script` Sometimes, `script` commands must be wrapped in single or double quotes. For example, commands that contain a colon (`:`) must be wrapped in single quotes (`'`). @@ -101,7 +101,7 @@ WARNING: If multiple commands are combined into one command string, only the last command's failure or success is reported. [Failures from earlier commands are ignored due to a bug](https://gitlab.com/gitlab-org/gitlab-runner/-/issues/25394). -To work around this, run each command as a separate `script:` item, or add an `exit 1` +To work around this, run each command as a separate `script` item, or add an `exit 1` command to each command string. You can use the `|` (literal) YAML multiline block scalar indicator to write |