Skip to content

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

Merge branch 'docs-restyle-script-keywords' into 'master' 

Revamp script, before_script and after_script reference docs

See merge request gitlab-org/gitlab!67138
parents 9e44919c 11220743
Hide whitespace changes
Inline Side-by-side
Showing with 154 additions and 87 deletions
doc/ci/yaml/index.md
View file @ 3369d72c
......@@ -684,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`
You can verify the syntax is valid with the [CI Lint](../lint.md) tool.
Use `before_script` to define an array of commands that should run before each job's
`script` commands, but after [artifacts](#artifacts) are restored.
Be careful when using these characters as well:
**Keyword type**: Job keyword. You can use it only as part of a job or in the
[`default:` section](#custom-default-keyword-values).
- `{`, `}`, `[`, `]`, `,`, `&`, `*`, `#`, `?`, `|`, `-`, `<`, `>`, `=`, `!`, `%`, `@`, `` ` ``.
**Possible inputs**: An array including:
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:
- Single line commands.
- Long commands [split over multiple lines](script.md#split-long-commands).
- [YAML anchors](#yaml-anchors-for-scripts).
**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.
......
doc/ci/yaml/script.md
View file @ 3369d72c
......@@ -14,6 +14,85 @@ 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:`
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.
For example, this script uses a colon:
```yaml
job:
script:
- curl --request POST --header 'Content-Type: application/json' "https://gitlab/api/v4/projects"
```
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:
```yaml
job:
script:
- 'curl --request POST --header "Content-Type: application/json" "https://gitlab/api/v4/projects"'
```
You can verify the syntax is valid with the [CI Lint](../lint.md) tool.
Be careful when using these characters as well:
- `{`, `}`, `[`, `]`, `,`, `&`, `*`, `#`, `?`, `|`, `-`, `<`, `>`, `=`, `!`, `%`, `@`, `` ` ``.
## Ignore non-zero exit codes
When script commands return an exit code other than zero, the job fails and further
commands do not execute.
Store the exit code in a variable to avoid this behavior:
```yaml
job:
script:
- false || exit_code=$?
- if [ $exit_code -ne 0 ]; then echo "Previous command failed"; fi;
```
## Set a default `before_script` or `after_script` for all jobs
You can use [`before_script`](index.md#before_script) and [`after_script`](index.md#after_script)
with [`default`](index.md#custom-default-keyword-values):
- Use `before_script` with `default` to define a default array of commands that
should run before the `script` commands in all jobs.
- Use `after_script` with default to define a default array of commands
that should run after the job completes.
You can overwrite a default by defining a different one in a job. To ignore the default
use `before_script: []` or `after_script: []`:
```yaml
default:
before_script:
- echo "Execute this `before_script` in all jobs by default."
after_script:
- echo "Execute this `after_script` in all jobs by default."
job1:
script:
- echo "These script commands execute after the default `before_script`,"
- echo "and before the default `after_script`."
job2:
before_script:
- echo "Execute this script instead of the default `before_script`."
script:
- echo "This script executes after the job's `before_script`,"
- echo "but the job does not use the default `after_script`."
after_script: []
```
## Split long commands
You can split long commands into multiline commands to improve readability with
......
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