diff options
Diffstat (limited to 'doc/ci/yaml/index.md')
| -rw-r--r-- | doc/ci/yaml/index.md | 170 |
1 files changed, 81 insertions, 89 deletions
diff --git a/doc/ci/yaml/index.md b/doc/ci/yaml/index.md index e6beef08896..1d69bc8d930 100644 --- a/doc/ci/yaml/index.md +++ b/doc/ci/yaml/index.md @@ -419,9 +419,13 @@ configurations. Local configurations in the `.gitlab-ci.yml` file override inclu > - [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/284883) in GitLab 13.8. > - [Feature flag removed](https://gitlab.com/gitlab-org/gitlab/-/issues/294294) in GitLab 13.9. +> - [Custom variable support added](https://gitlab.com/gitlab-org/gitlab/-/issues/219065) in GitLab 14.2. -You can [use some predefined variables in `include` sections](../variables/where_variables_can_be_used.md#gitlab-ciyml-file) -in your `.gitlab-ci.yml` file: +In `include` sections in your `.gitlab-ci.yml` file, you can use: + +- Project [predefined variables](../variables/predefined_variables.md). +- [Custom instance, group, and project variables](../variables/index.md#custom-cicd-variables) + in GitLab 14.2 and later. ```yaml include: @@ -680,142 +684,130 @@ For more information, see [Available settings for `services`](../services/index. ### `script` -Use `script` to specify a shell script for the runner to execute. +Use `script` to specify commands for the runner to execute. All jobs except [trigger jobs](#trigger) require a `script` keyword. -For example: +**Keyword type**: Job keyword. You can use it only as part of a job. -```yaml -job: - script: "bundle exec rspec" -``` +**Possible inputs**: An array including: -You can use [YAML anchors with `script`](#yaml-anchors-for-scripts). +- Single line commands. +- Long commands [split over multiple lines](script.md#split-long-commands). +- [YAML anchors](#yaml-anchors-for-scripts). -The `script` keyword can also contain several commands in an array: +**Example of `script`:** ```yaml -job: +job1: + script: "bundle exec rspec" + +job2: script: - uname -a - bundle exec rspec ``` -Sometimes, `script` commands must be wrapped in single or double quotes. -For example, commands that contain a colon (`:`) must be wrapped in single quotes (`'`). -The YAML parser needs to interpret the text as a string rather than -a "key: value" pair. +**Additional details**: -For example, this script uses a colon: +You might need to use single quotes (`'`) or double quotes (`"`) when using +[special characters in `script`](script.md#use-special-characters-with-script). -```yaml -job: - script: - - curl --request POST --header 'Content-Type: application/json' "https://gitlab/api/v4/projects" -``` +**Related topics**: -To be considered valid YAML, you must wrap the entire command in single quotes. If -the command already uses single quotes, you should change them to double quotes (`"`) -if possible: +- You can [ignore non-zero exit codes](script.md#ignore-non-zero-exit-codes). +- [Use color codes with `script`](script.md#add-color-codes-to-script-output) + to make job logs easier to review. +- [Create custom collapsible sections](../jobs/index.md#custom-collapsible-sections) + to simplify job log output. -```yaml -job: - script: - - 'curl --request POST --header "Content-Type: application/json" "https://gitlab/api/v4/projects"' -``` +#### `before_script` + +Use `before_script` to define an array of commands that should run before each job's +`script` commands, but after [artifacts](#artifacts) are restored. -You can verify the syntax is valid with the [CI Lint](../lint.md) tool. +**Keyword type**: Job keyword. You can use it only as part of a job or in the +[`default:` section](#custom-default-keyword-values). -Be careful when using these characters as well: +**Possible inputs**: An array including: -- `{`, `}`, `[`, `]`, `,`, `&`, `*`, `#`, `?`, `|`, `-`, `<`, `>`, `=`, `!`, `%`, `@`, `` ` ``. +- Single line commands. +- Long commands [split over multiple lines](script.md#split-long-commands). +- [YAML anchors](#yaml-anchors-for-scripts). -If any of the script commands return an exit code other than zero, the job -fails and further commands are not executed. Store the exit code in a variable to -avoid this behavior: +**Example of `before_script`:** ```yaml job: + before_script: + - echo "Execute this command before any `script:` commands." script: - - false || exit_code=$? - - if [ $exit_code -ne 0 ]; then echo "Previous command failed"; fi; + - echo "This command executes after the job's `before_script` commands." ``` -#### `before_script` - -Use `before_script` to define an array of commands that should run before each job, -but after [artifacts](#artifacts) are restored. +**Additional details**: Scripts you specify in `before_script` are concatenated with any scripts you specify -in the main [`script`](#script). The combine scripts execute together in a single shell. +in the main [`script`](#script). The combined scripts execute together in a single shell. -You can overwrite a globally-defined `before_script` if you define it in a job: +**Related topics**: -```yaml -default: - before_script: - - echo "Execute this script in all jobs that don't already have a before_script section." +- [Use `before_script` with `default`](script.md#set-a-default-before_script-or-after_script-for-all-jobs) + to define a default array of commands that should run before the `script` commands in all jobs. +- You can [ignore non-zero exit codes](script.md#ignore-non-zero-exit-codes). +- [Use color codes with `before_script`](script.md#add-color-codes-to-script-output) + to make job logs easier to review. +- [Create custom collapsible sections](../jobs/index.md#custom-collapsible-sections) + to simplify job log output. -job1: - script: - - echo "This script executes after the global before_script." +#### `after_script` -job: - before_script: - - echo "Execute this script instead of the global before_script." - script: - - echo "This script executes after the job's `before_script`" -``` +Use `after_script` to define an array of commands that run after each job, including failed jobs. -You can use [YAML anchors with `before_script`](#yaml-anchors-for-scripts). +**Keyword type**: Job keyword. You can use it only as part of a job or in the +[`default:` section](#custom-default-keyword-values). -#### `after_script` +**Possible inputs**: An array including: -Use `after_script` to define an array of commands that run after each job, -including failed jobs. +- Single line commands. +- Long commands [split over multiple lines](script.md#split-long-commands). +- [YAML anchors](#yaml-anchors-for-scripts). -If a job times out or is cancelled, the `after_script` commands do not execute. -An [issue](https://gitlab.com/gitlab-org/gitlab/-/issues/15603) exists to support -executing `after_script` commands for timed-out or cancelled jobs. +**Example of `after_script`:** + +```yaml +job: + script: + - echo "An example script section." + after_script: + - echo "Execute this command after the `script` section completes." +``` + +**Additional details**: Scripts you specify in `after_script` execute in a new shell, separate from any -`before_script` or `script` scripts. As a result, they: +`before_script` or `script` commands. As a result, they: - Have a current working directory set back to the default. -- Have no access to changes done by scripts defined in `before_script` or `script`, including: +- Don't have access to changes done by commands defined in the `before_script` or `script`, + including: - Command aliases and variables exported in `script` scripts. - Changes outside of the working tree (depending on the runner executor), like software installed by a `before_script` or `script` script. -- Have a separate timeout, which is hard coded to 5 minutes. See the - [related issue](https://gitlab.com/gitlab-org/gitlab-runner/-/issues/2716) for details. +- Have a separate timeout, which is [hard-coded to 5 minutes](https://gitlab.com/gitlab-org/gitlab-runner/-/issues/2716). - Don't affect the job's exit code. If the `script` section succeeds and the `after_script` times out or fails, the job exits with code `0` (`Job Succeeded`). -```yaml -default: - after_script: - - echo "Execute this script in all jobs that don't already have an after_script section." - -job1: - script: - - echo "This script executes first. When it completes, the global after_script executes." - -job: - script: - - echo "This script executes first. When it completes, the job's `after_script` executes." - after_script: - - echo "Execute this script instead of the global after_script." -``` - -You can use [YAML anchors with `after_script`](#yaml-anchors-for-scripts). - -#### Script syntax +If a job times out or is cancelled, the `after_script` commands do not execute. +[An issue exists](https://gitlab.com/gitlab-org/gitlab/-/issues/15603) to add support for executing `after_script` commands for timed-out or cancelled jobs. -You can use syntax in [`script`](#script) sections to: +**Related topics**: -- [Split long commands](script.md#split-long-commands) into multiline commands. -- [Use color codes](script.md#add-color-codes-to-script-output) to make job logs easier to review. +- [Use `after_script` with `default`](script.md#set-a-default-before_script-or-after_script-for-all-jobs) + to define a default array of commands that should run after all jobs. +- You can [ignore non-zero exit codes](script.md#ignore-non-zero-exit-codes). +- [Use color codes with `after_script`](script.md#add-color-codes-to-script-output) + to make job logs easier to review. - [Create custom collapsible sections](../jobs/index.md#custom-collapsible-sections) to simplify job log output. |