Skip to content

G
gitlab-ce
Commit d2be6d74 authored by Suzanne Selhorn's avatar Suzanne Selhorn
Browse files
Options

Merge branch 'docs-ci-ref-this' into 'master' 

Improve the usage of "this" in the CI ref

See merge request gitlab-org/gitlab!48111
parents 4ffbeefd 0e5725c3
Hide whitespace changes
Inline Side-by-side
Showing with 118 additions and 139 deletions
doc/ci/yaml/README.md
View file @ d2be6d74
......@@ -233,7 +233,7 @@ There are also two edge cases worth mentioning:
> [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/29654) in GitLab 12.5
The top-level `workflow:` keyword determines whether or not a pipeline is created.
It accepts a single `rules:` keyword that is similar to [`rules:` defined within jobs](#rules).
It accepts a single `rules:` keyword that is similar to [`rules:` defined in jobs](#rules).
Use it to define what can trigger a new pipeline.
You can use the [`workflow:rules` templates](#workflowrules-templates) to import
......@@ -289,12 +289,11 @@ workflow:
```
This example prevents pipelines for schedules or `push` (branches and tags) pipelines.
The final `when: always` rule lets all other pipeline types run, **including** merge
The final `when: always` rule runs all other pipeline types, **including** merge
request pipelines.
Be careful not to have rules that match both branch pipelines
and merge request pipelines. Similar to `rules` defined in jobs, this can cause
[duplicate pipelines](#prevent-duplicate-pipelines).
If your rules match both branch pipelines and merge request pipelines,
[duplicate pipelines](#prevent-duplicate-pipelines) can occur.
#### `workflow:rules` templates
......@@ -306,7 +305,7 @@ for common scenarios. These templates help prevent duplicate pipelines.
The [`Branch-Pipelines` template](https://gitlab.com/gitlab-org/gitlab/-/tree/master/lib/gitlab/ci/templates/Workflows/Branch-Pipelines.gitlab-ci.yml)
makes your pipelines run for branches and tags.
Branch pipeline status is displayed within merge requests that use the branch
Branch pipeline status is displayed in merge requests that use the branch
as a source. However, this pipeline type does not support any features offered by
[Merge Request Pipelines](../merge_request_pipelines/), like
[Pipelines for Merge Results](../merge_request_pipelines/#pipelines-for-merged-results)
......@@ -339,10 +338,11 @@ include:
> - Available for Starter, Premium, and Ultimate in GitLab 10.6 and later.
> - [Moved](https://gitlab.com/gitlab-org/gitlab-foss/-/issues/42861) to GitLab Core in 11.4.
Use the `include` keyword to include external YAML files in your CI/CD configuration. This
breaks down the CI/CD configuration into multiple files and increases readability for long configuration files.
It's also possible to have template files stored in a central repository and projects include their
configuration files. This helps avoid duplicated configuration, for example, global default variables for all projects.
Use the `include` keyword to include external YAML files in your CI/CD configuration.
You can break down one long `gitlab-ci.yml` into multiple files to increase readability,
or reduce duplication of the same configuration in multiple places.
You can also store template files in a central repository and `include` them in projects.
`include` requires the external YAML file to have the extensions `.yml` or `.yaml`,
otherwise the external file is not included.
......@@ -437,8 +437,7 @@ include:
```
All [nested includes](#nested-includes) are executed in the scope of the target project.
This means you can use local (relative to target project), project, remote,
or template includes.
You can use local (relative to target project), project, remote, or template includes.
##### Multiple files from a project
......@@ -631,8 +630,8 @@ job:
#### `before_script`
`before_script` is used to define commands that should run before each job, including
deploy jobs, but after the restoration of any [artifacts](#artifacts). This must be an array.
`before_script` is used to define an array of commands that should run before each job,
but after [artifacts](#artifacts) are restored.
Scripts specified in `before_script` are concatenated with any scripts specified
in the main [`script`](#script), and executed together in a single shell.
......@@ -642,25 +641,25 @@ It's possible to overwrite a globally defined `before_script` if you define it i
```yaml
default:
before_script:
- echo "Execute this in all jobs that don't already have a before_script section."
- echo "Execute this script in all jobs that don't already have a before_script section."
job1:
script:
- echo "This executes after the global before_script."
- echo "This script executes after the global before_script."
job:
before_script:
- echo "Execute this instead of the global before_script."
- echo "Execute this script instead of the global before_script."
script:
- echo "This executes after the job's `before_script`"
- echo "This script executes after the job's `before_script`"
```
You can use [YAML anchors with `before_script`](#yaml-anchors-for-scripts).
#### `after_script`
`after_script` is used to define commands that run after each job, including failed
jobs. This must be an array.
`after_script` is used to define an array of commands that run after each job,
including failed jobs.
If a job times out or is cancelled, the `after_script` commands are not executed.
Support for executing `after_script` commands for timed-out or cancelled jobs
......@@ -682,17 +681,17 @@ Scripts specified in `after_script` are executed in a new shell, separate from a
```yaml
default:
after_script:
- echo "Execute this in all jobs that don't already have an after_script section."
- echo "Execute this script in all jobs that don't already have an after_script section."
job1:
script:
- echo "This executes first. When it completes, the global after_script executes."
- echo "This script executes first. When it completes, the global after_script executes."
job:
script:
- echo "This executes first. When it completes, the job's `after_script` executes."
- echo "This script executes first. When it completes, the job's `after_script` executes."
after_script:
- echo "Execute this instead of the global after_script."
- echo "Execute this script instead of the global after_script."
```
You can use [YAML anchors with `after_script`](#yaml-anchors-for-scripts).
......@@ -848,9 +847,8 @@ If you do want to include the `rake test`, see [`before_script`](#before_script)
`.tests` in this example is a [hidden job](#hide-jobs), but it's
possible to inherit from regular jobs as well.
`extends` supports multi-level inheritance. You should avoid using more than 3 levels,
but you can use as many as eleven.
The following example has two levels of inheritance:
`extends` supports multi-level inheritance. You should avoid using more than three levels,
but you can use as many as eleven. The following example has two levels of inheritance:
```yaml
.tests:
......@@ -916,7 +914,7 @@ rspec:
- rake rspec
```
This results in the following `rspec` job:
The result is this `rspec` job:
```yaml
rspec:
......@@ -955,7 +953,7 @@ For example, if you have a local `included.yml` file:
- echo Hello!
```
Then, in `.gitlab-ci.yml` you can use it like this:
Then, in `.gitlab-ci.yml`:
```yaml
include: included.yml
......@@ -1041,7 +1039,7 @@ For example, using `if` clauses to strictly limit when jobs run:
```yaml
job:
script: "echo Hello, Rules!"
script: echo "Hello, Rules!"
rules:
- if: '$CI_PIPELINE_SOURCE == "merge_request_event"'
when: manual
......@@ -1070,7 +1068,7 @@ run them in all other cases:
```yaml
job:
script: "echo Hello, Rules!"
script: echo "Hello, Rules!"
rules:
- if: '$CI_PIPELINE_SOURCE == "merge_request_event"'
when: never
......@@ -1105,7 +1103,7 @@ For example:
```yaml
job:
script: "echo This creates double pipelines!"
script: echo "This job creates double pipelines!"
rules:
- if: '$CUSTOM_VARIABLE == "false"'
when: never
......@@ -1117,7 +1115,7 @@ other pipelines, including **both** push (branch) and merge request pipelines. W
this configuration, every push to an open merge request's source branch
causes duplicated pipelines.
There are multiple ways to avoid this:
There are multiple ways to avoid duplicate pipelines:
- Use [`workflow: rules`](#workflowrules) to specify which types of pipelines
can run. To eliminate duplicate pipelines, use merge request pipelines only
......@@ -1128,7 +1126,7 @@ There are multiple ways to avoid this:
```yaml
job:
script: "echo This does NOT create double pipelines!"
script: echo "This job does NOT create double pipelines!"
rules:
- if: '$CUSTOM_VARIABLE == "true" && $CI_PIPELINE_SOURCE == "merge_request_event"'
```
......@@ -1142,7 +1140,7 @@ without `workflow: rules`:
```yaml
job:
script: "echo This does NOT create double pipelines!"
script: echo "This job does NOT create double pipelines!"
rules:
- if: '$CI_PIPELINE_SOURCE == "push"'
when: never
......@@ -1153,7 +1151,7 @@ Do not include both push and merge request pipelines in the same job:
```yaml
job:
script: "echo This creates double pipelines!"
script: echo "This job creates double pipelines!"
rules:
- if: '$CI_PIPELINE_SOURCE == "push"'
- if: '$CI_PIPELINE_SOURCE == "merge_request_event"'
......@@ -1165,10 +1163,10 @@ and `rules` can cause issues that are difficult to troubleshoot:
```yaml
job-with-no-rules:
script: "echo This job runs in branch pipelines."
script: echo "This job runs in branch pipelines."
job-with-rules:
script: "echo This job runs in merge request pipelines."
script: echo "This job runs in merge request pipelines."
rules:
- if: '$CI_PIPELINE_SOURCE == "merge_request_event"'
```
......@@ -1211,7 +1209,7 @@ For example:
```yaml
job:
script: "echo Hello, Rules!"
script: echo "Hello, Rules!"
rules:
- if: '$CI_MERGE_REQUEST_SOURCE_BRANCH_NAME =~ /^feature/ && $CI_MERGE_REQUEST_TARGET_BRANCH_NAME == "master"'
when: always
......@@ -1244,7 +1242,7 @@ check the value of the `$CI_PIPELINE_SOURCE` variable:
| `external` | When using CI services other than GitLab. |
| `external_pull_request_event` | 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_request_event` | For pipelines created when a merge request is created or updated. Required to enable [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). |
| `parent_pipeline` | For pipelines triggered by a [parent/child pipeline](../parent_child_pipelines.md) with `rules`, use this in the child pipeline configuration so that it can be triggered by the parent pipeline. |
| `parent_pipeline` | For pipelines triggered by a [parent/child pipeline](../parent_child_pipelines.md) with `rules`. Use this pipeline source in the child pipeline configuration so that it can be triggered by the parent pipeline. |
| `pipeline` | 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. |
| `push` | For pipelines triggered by a `git push` event, including for branches and tags. |
| `schedule` | For [scheduled pipelines](../pipelines/schedules.md). |
......@@ -1256,7 +1254,7 @@ For example:
```yaml
job:
script: "echo Hello, Rules!"
script: echo "Hello, Rules!"
rules:
- if: '$CI_PIPELINE_SOURCE == "schedule"'
when: manual
......@@ -1272,7 +1270,7 @@ Another example:
```yaml
job:
script: "echo Hello, Rules!"
script: echo "Hello, Rules!"
rules:
- if: '$CI_PIPELINE_SOURCE == "merge_request_event"'
- if: '$CI_PIPELINE_SOURCE == "schedule"'
......@@ -1394,9 +1392,7 @@ Feature.disable(:ci_variable_expansion_in_rules_changes)
> [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/24021) in GitLab 12.4.
`exists` accepts an array of paths and matches if any of these paths exist
as files in the repository.
For example:
as files in the repository:
```yaml
job:
......@@ -1406,10 +1402,7 @@ job:
- Dockerfile
```
You can also use glob patterns to match multiple files in any directory within
the repository.
For example:
You can also use glob patterns to match multiple files in any directory in the repository:
```yaml
job:
......@@ -1426,7 +1419,7 @@ checks. After the 10,000th check, rules with patterned globs always match.
> [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/30235) in GitLab 12.8.
You can use [`allow_failure: true`](#allow_failure) within `rules:` to allow a job to fail, or a manual job to
You can use [`allow_failure: true`](#allow_failure) in `rules:` to allow a job to fail, or a manual job to
wait for action, without stopping the pipeline itself. All jobs using `rules:` default to `allow_failure: false`
if `allow_failure:` is not defined.
......@@ -1436,7 +1429,7 @@ triggered by the particular rule.
```yaml
job:
script: "echo Hello, Rules!"
script: echo "Hello, Rules!"
rules:
- if: '$CI_MERGE_REQUEST_TARGET_BRANCH_NAME == "master"'
when: manual
......@@ -1465,7 +1458,7 @@ docker build:
- Dockerfile
- docker/scripts/*
when: manual
# - when: never would be redundant here, this is implied any time rules are listed.
# - "when: never" would be redundant here. It is implied any time rules are listed.
```
Keywords such as `branches` or `refs` that are available for
......@@ -1792,8 +1785,8 @@ refs only:
CAUTION: **Caution:**
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`.
This includes pipelines triggered by pushing new tags. Configuring jobs to use `only: changes`
with other `only: refs` keywords is possible, but not recommended.
You can configure jobs to use `only: changes` with other `only: refs` keywords. However,
those jobs ignore the changes and always run.
A basic example of using `only: changes`:
......@@ -1823,7 +1816,7 @@ If you use `only:changes` with [only allow merge requests to be merged if the pi
you should [also use `only:merge_requests`](#using-onlychanges-with-pipelines-for-merge-requests). Otherwise it may not work as expected.
You can also use glob patterns to match multiple files in either the root directory
of the repository, or in _any_ directory within the repository. However, they must be wrapped
of the repository, or in _any_ directory in the repository. However, they must be wrapped
in double quotes or GitLab can't parse them. For example:
```yaml
......@@ -1862,10 +1855,9 @@ 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.
To deduce the correct base SHA of the source branch, we recommend combining
this keyword with `only: [merge_requests]`. This way, file differences are correctly
calculated from any further commits, thus all changes in the merge requests are properly
tested in pipelines.
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:
......@@ -1933,8 +1925,8 @@ runs.
Use the `needs:` keyword 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).
This lets you run some jobs without waiting for other ones, disregarding stage ordering
so you can have multiple stages running concurrently.
You can ignore stage ordering and run some jobs without waiting for others to complete.
Jobs in multiple stages can run concurrently.
Let's consider the following example:
......@@ -2002,7 +1994,7 @@ This example creates four paths of execution:
##### Changing the `needs:` job limit **(CORE ONLY)**
The maximum number of jobs that can be defined within `needs:` defaults to 50.
The maximum number of jobs that can be defined in `needs:` defaults to 50.
A GitLab administrator with [access to the GitLab Rails console](../../administration/feature_flags.md)
can choose a custom limit. For example, to set the limit to 100:
......@@ -2211,16 +2203,13 @@ failure.
`when` can be set to one of the following values:
1. `on_success` - execute job only when all jobs from prior stages
succeed (or are considered succeeding because they have `allow_failure: true`).
This is the default.
1. `on_failure` - execute job only when at least one job from prior stages
fails.
1. `always` - execute job regardless of the status of jobs from prior stages.
1. `manual` - execute job manually. Read about
[manual jobs](#whenmanual) below.
1. `delayed` - execute job after a certain period (added in GitLab 11.14).
Read about [delayed jobs](#whendelayed) below.
1. `on_success` (default) - Execute job only when all jobs in earlier stages succeed,
or are considered successful because they have `allow_failure: true`.
1. `on_failure` - Execute job only when at least one job in an earlier stage fails.
1. `always` - Execute job regardless of the status of jobs in earlier stages.
1. `manual` - Execute job [manually](#whenmanual).
1. `delayed` - [Delay the execution of a job](#whendelayed) for a specified duration.
Added in GitLab 11.14.
1. `never`:
- With [`rules`](#rules), don't execute job.
- With [`workflow:rules`](#workflowrules), don't run pipeline.
......@@ -2318,7 +2307,7 @@ the users associated with a protected environment to trigger manual jobs, which
- More precisely limit who can deploy to an environment.
- Block a pipeline until an approved user "approves" it.
To do this, you must:
To protect a manual job:
1. Add an `environment` to the job. For example:
......@@ -2341,10 +2330,10 @@ To do this, you must:
this list can trigger this manual job, as well as GitLab administrators
who are always able to use protected environments.
Additionally, if you define a manual job as blocking by adding `allow_failure: false`,
the pipeline's next stages don't run until the manual job is triggered. You can use this
to define a list of users allowed to "approve" later pipeline
stages by triggering the blocking manual job.
You can use protected environments with blocking manual jobs to have a list of users
allowed to approve later pipeline stages. Add `allow_failure: false` to the protected
manual job and the pipeline's next stages only run after the manual job is triggered
by authorized users.
#### `when:delayed`
......@@ -2363,7 +2352,7 @@ provided. `start_in` key must be less than or equal to one week. Examples of val
- `1 week`
When there is a delayed job in a stage, the pipeline doesn't progress until the delayed job has finished.
This means this keyword can also be used for inserting delays between different stages.
This keyword can also be used for inserting delays between different stages.
The timer of a delayed job starts immediately after the previous stage has completed.
Similar to other types of jobs, a delayed job's timer doesn't start unless the previous stage passed.
......@@ -2517,8 +2506,8 @@ Also in the example, `GIT_STRATEGY` is set to `none`. If the
the runner won’t try to check out the code after the branch is deleted.
The example also overwrites global variables. If your `stop` `environment` job depends
on global variables, you can use [anchor variables](#yaml-anchors-for-variables) when you set the `GIT_STRATEGY`.
This changes the job without overriding the global variables.
on global variables, use [anchor variables](#yaml-anchors-for-variables) when you set the `GIT_STRATEGY`
to change the job without overriding the global variables.
The `stop_review_app` job is **required** to have the following keywords defined:
......@@ -2607,16 +2596,12 @@ deploy as review app:
url: https://$CI_ENVIRONMENT_SLUG.example.com/
```
The `deploy as review app` job is marked as deployment to dynamically
create the `review/$CI_COMMIT_REF_NAME` environment, where `$CI_COMMIT_REF_NAME`
The `deploy as review app` job is marked as a deployment to dynamically
create the `review/$CI_COMMIT_REF_NAME` environment. `$CI_COMMIT_REF_NAME`
is an [environment variable](../variables/README.md) set by the runner. The
`$CI_ENVIRONMENT_SLUG` variable is based on the environment name, but suitable
for inclusion in URLs. In this case, if the `deploy as review app` job is run
in a branch named `pow`, this environment would be accessible with an URL like
`https://review-pow.example.com/`.
This implies that the underlying server that hosts the application
is properly configured.
for inclusion in URLs. If the `deploy as review app` job runs in a branch named
`pow`, this environment would be accessible with a URL like `https://review-pow.example.com/`.
The common use case is to create dynamic environments for branches and use them
as Review Apps. You can see an example that uses Review Apps at
......@@ -2625,8 +2610,7 @@ as Review Apps. You can see an example that uses Review Apps at
### `cache`
`cache` is used to specify a list of files and directories that should be
cached between jobs. You can only use paths that are within the local working
copy.
cached between jobs. You can only use paths that are in the local working copy.
If `cache` is defined outside the scope of jobs, it means it's set
globally and all jobs use that definition.
......@@ -2681,11 +2665,9 @@ Otherwise cache content can be overwritten.
#### `cache:key`
> Introduced in GitLab Runner v1.0.0.
The `key` keyword defines the affinity of caching between jobs.
You can have a single cache for all jobs, cache per-job, cache per-branch,
or any other way that fits your workflow. This way, you can fine tune caching,
or any other way that fits your workflow. You can fine tune caching,
including caching data between different jobs or even different branches.
The `cache:key` variable can use any of the
......@@ -2841,9 +2823,9 @@ rspec:
`cache:when` defines when to save the cache, based on the status of the job. You can
set `cache:when` to:
- `on_success` - save the cache only when the job succeeds. This is the default.
- `on_failure` - save the cache only when the job fails.
- `always` - save the cache regardless of the job status.
- `on_success` (default): Save the cache only when the job succeeds.
- `on_failure`: Save the cache only when the job fails.
- `always`: Always save the cache.
For example, to store a cache whether or not the job fails or succeeds:
......@@ -2864,9 +2846,8 @@ job are persisted for future runs. This behavior is known as the `pull-push` cac
policy.
If you know the job does not alter the cached files, you can skip the upload step
by setting `policy: pull` in the job specification. Typically, this would be
twinned with an ordinary cache job at an earlier stage to ensure the cache
is updated from time to time:
by setting `policy: pull` in the job specification. You can add an ordinary cache
job at an earlier stage to ensure the cache is updated from time to time:
```yaml
stages:
......@@ -2893,9 +2874,8 @@ rspec:
- bundle exec rspec ...
```
This helps to speed up job execution and reduce load on the cache server.
It is especially helpful when you have a large number of cache-using jobs executing in
parallel.
The `pull` policy speeds up job execution and reduces load on the cache server. It
can be used when you have many jobs that use caches executing in parallel.
If you have a job that unconditionally recreates the cache without
referring to its previous contents, you can skip the download step.
......@@ -3163,9 +3143,9 @@ failure.
`artifacts:when` can be set to one of the following values:
1. `on_success` - upload artifacts only when the job succeeds. This is the default.
1. `on_failure` - upload artifacts only when the job fails.
1. `always` - upload artifacts regardless of the job status.
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.
For example, to upload artifacts only when a job fails:
......@@ -3397,7 +3377,7 @@ Possible values for `when` are:
The test there makes sure that all documented
values are valid as a configuration option and therefore should always
stay in sync with this documentation.
-->
-->
- `always`: Retry on any failure (default).
- `unknown_failure`: Retry when the failure reason is unknown.
......@@ -3440,16 +3420,11 @@ exceed the runner-specific timeout.
> [Introduced](https://gitlab.com/gitlab-org/gitlab-foss/-/issues/21480) in GitLab 11.5.
Use `parallel` to configure how many instances of a job to run in
parallel. This value can be from 2 to 50.
This creates N instances of the same job that run in parallel. They are named
sequentially from `job_name 1/N` to `job_name N/N`.
For every job, `CI_NODE_INDEX` and `CI_NODE_TOTAL` [environment variables](../variables/README.md#predefined-environment-variables) are set.
Use `parallel` to configure how many instances of a job to run in parallel.
The value can be from 2 to 50.
Marking a job to be run in parallel requires adding `parallel` to your configuration
file. For example:
The `parallel` keyword creates N instances of the same job that run in parallel.
They are named sequentially from `job_name 1/N` to `job_name N/N`:
```yaml
test:
......@@ -3457,10 +3432,12 @@ test:
parallel: 5
```
Parallelize tests suites across parallel jobs.
Different languages have different tools to facilitate this.
Every parallel job has a `CI_NODE_INDEX` and `CI_NODE_TOTAL`
[environment variable](../variables/README.md#predefined-environment-variables) set.
For example, using [Semaphore Test Boosters](https://github.com/renderedtext/test-boosters) and RSpec to run some Ruby tests:
Different languages and test suites have different methods to enable parallelization.
For example, use [Semaphore Test Boosters](https://github.com/renderedtext/test-boosters)
and RSpec to run Ruby tests in parallel:
```ruby
# Gemfile
......@@ -3479,7 +3456,7 @@ test:
```
CAUTION: **Caution:**
Test Boosters reports usages statistics to the author.
Test Boosters reports usage statistics to the author.
You can then navigate to the **Jobs** tab of a new pipeline build and see your RSpec
job split into three separate jobs.
......@@ -3514,7 +3491,8 @@ deploystacks:
STACK: [data, processing]
```
This generates 10 parallel `deploystacks` jobs, each with different values for `PROVIDER` and `STACK`:
This example generates 10 parallel `deploystacks` jobs, each with different values
for `PROVIDER` and `STACK`:
```plaintext
deploystacks: [aws, monitoring]
......@@ -3529,7 +3507,7 @@ deploystacks: [vultr, data]
deploystacks: [vultr, processing]
```
Job naming style [was improved](https://gitlab.com/gitlab-org/gitlab/-/issues/230452) in GitLab 13.4.
The job naming style was [improved in GitLab 13.4](https://gitlab.com/gitlab-org/gitlab/-/issues/230452).
### `trigger`
......@@ -3782,8 +3760,8 @@ deploy-to-production:
In this case, two `deploy-to-production` jobs in two separate pipelines can never run at the same time. As a result,
you can ensure that concurrent deployments never happen to the production environment.
There can be multiple `resource_group`s defined per environment. A good use case for this
is when deploying to physical devices. You may have multiple physical devices that
You can define multiple resource groups per environment. For example,
when deploying to physical devices, you may have multiple physical devices. Each device
can be deployed to, but there can be only one deployment per device at any given time.
The `resource_group` value can only contain letters, digits, `-`, `_`, `/`, `$`, `{`, `}`, `.`, and spaces.
......@@ -3819,8 +3797,9 @@ image: registry.gitlab.com/gitlab-org/release-cli:latest
#### Script
All jobs require a `script` tag at a minimum. A `:release` job can use the output of a
`:script` tag, but if this is not necessary, a placeholder script can be used, for example:
All jobs except [trigger](#trigger) jobs must have the `script` keyword. A `release`
job can use the output from script commands, but a placeholder script can be used if
the script is not needed:
```yaml
script:
......@@ -3980,15 +3959,16 @@ tags. These options cannot be used together, so choose one:
#### Release assets as Generic packages
You can use [Generic packages](../../user/packages/generic_packages/) to host your release assets.
For a complete example of how to do this, see the [example in the repository](https://gitlab.com/gitlab-org/release-cli/-/tree/master/docs/examples/release-assets-as-generic-package/).
For a complete example, see the [Release assets as Generic packages](https://gitlab.com/gitlab-org/release-cli/-/tree/master/docs/examples/release-assets-as-generic-package/)
project.
#### `releaser-cli` command line
The entries under the `:release` node are transformed into a `bash` command line and sent
The entries under the `release` node are transformed into a `bash` command line and sent
to the Docker container, which contains the [release-cli](https://gitlab.com/gitlab-org/release-cli).
You can also call the `release-cli` directly from a `script` entry.
The YAML described above would be translated into a CLI command like this:
For example, using the YAML described above:
```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"
......@@ -4112,7 +4092,7 @@ deploy_review_job:
You can use only integers and strings for the variable's name and value.
If you define a variable at the top level of the `gitlab-ci.yml` file, it is global,
meaning it applies to all jobs. If you define a variable within a job, it's available
meaning it applies to all jobs. If you define a variable in a job, it's available
to that job only.
If a variable of the same name is defined globally and for a specific job, the
......@@ -4160,7 +4140,7 @@ to provide templates for your jobs. When there are duplicate keys, GitLab
performs a reverse deep merge based on the keys.
You can't use YAML anchors across multiple files when leveraging the [`include`](#include)
feature. Anchors are only valid within the file they were defined in. Instead
feature. Anchors are only valid in the file they were defined in. Instead
of using YAML anchors, you can use the [`extends` keyword](#extends).
The following example uses anchors and map merging. It creates two jobs,
......@@ -4187,7 +4167,7 @@ test2:
`&` sets up the name of the anchor (`job_definition`), `<<` means "merge the
given hash into the current one", and `*` includes the named anchor
(`job_definition` again). The expanded version looks like this:
(`job_definition` again). The expanded version of the example above is:
```yaml
.job_template:
......@@ -4213,10 +4193,9 @@ test2:
- test2 project
```
Let's see another example. This time we use anchors to define two sets
of services. This configuration creates two jobs, `test:postgres` and `test:mysql`, that
share the `script` directive defined in `.job_template`, and the `services`
directive defined in `.postgres_services` and `.mysql_services` respectively:
You can use anchors to define two sets of services. For example, `test:postgres`
and `test:mysql` share the `script` defined in `.job_template`, but use different
`services`, defined in `.postgres_services` and `.mysql_services`:
```yaml
.job_template: &job_definition
......@@ -4246,7 +4225,7 @@ test:mysql:
services: *mysql_definition
```
The expanded version looks like this:
The expanded version is:
```yaml
.job_template:
......@@ -4296,13 +4275,13 @@ and [`after_script`](#after_script) to use predefined commands in multiple jobs:
```yaml
.some-script: &some-script
- echo "Execute this in `before_script` sections"
- echo "Execute this script in `before_script` sections"
.some-script-before: &some-script-before
- echo "Execute this in `script` sections"
- echo "Execute this script in `script` sections"
.some-script-after: &some-script-after
- echo "Execute this in `after_script` sections"
- echo "Execute this script in `after_script` sections"
job_name:
before_script:
......
Markdown is supported
0% or
You are about to add 0 people to the discussion. Proceed with caution.
Finish editing this message first!
Please register or to comment
GitLab Nexedi Edition | About GitLab | About Nexedi | 沪ICP备2021021310号-2 | 沪ICP备2021021310号-7