147 lines
4.3 KiB
Markdown
147 lines
4.3 KiB
Markdown
---
|
|
stage: Verify
|
|
group: Continuous Integration
|
|
info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/engineering/ux/technical-writing/#designated-technical-writers
|
|
type: reference
|
|
---
|
|
|
|
# GitLab CI/CD script syntax
|
|
|
|
You can use special syntax in [`script`](README.md#script) sections to:
|
|
|
|
- [Split long commands](#split-long-commands) into multiline commands.
|
|
- [Use color codes](#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.
|
|
|
|
## Split long commands
|
|
|
|
You can split long commands into multiline commands to improve readability with
|
|
`|` (literal) and `>` (folded) [YAML multiline block scalar indicators](https://yaml-multiline.info/).
|
|
|
|
CAUTION: **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`
|
|
command to each command string.
|
|
|
|
You can use the `|` (literal) YAML multiline block scalar indicator to write
|
|
commands over multiple lines in the `script` section of a job description.
|
|
Each line is treated as a separate command.
|
|
Only the first command is repeated in the job log, but additional
|
|
commands are still executed:
|
|
|
|
```yaml
|
|
job:
|
|
script:
|
|
- |
|
|
echo "First command line."
|
|
echo "Second command line."
|
|
echo "Third command line."
|
|
```
|
|
|
|
The example above renders in the job log as:
|
|
|
|
```shell
|
|
$ echo First command line # collapsed multiline command
|
|
First command line
|
|
Second command line.
|
|
Third command line.
|
|
```
|
|
|
|
The `>` (folded) YAML multiline block scalar indicator treats empty lines between
|
|
sections as the start of a new command:
|
|
|
|
```yaml
|
|
job:
|
|
script:
|
|
- >
|
|
echo "First command line
|
|
is split over two lines."
|
|
|
|
echo "Second command line."
|
|
```
|
|
|
|
This behaves similarly to multiline commands without the `>` or `|` block
|
|
scalar indicators:
|
|
|
|
```yaml
|
|
job:
|
|
script:
|
|
- echo "First command line
|
|
is split over two lines."
|
|
|
|
echo "Second command line."
|
|
```
|
|
|
|
Both examples above render in the job log as:
|
|
|
|
```shell
|
|
$ echo First command line is split over two lines. # collapsed multiline command
|
|
First command line is split over two lines.
|
|
Second command line.
|
|
```
|
|
|
|
When you omit the `>` or `|` block scalar indicators, GitLab concatenates non-empty
|
|
lines to form the command. Make sure the lines can run when concatenated.
|
|
|
|
[Shell here documents](https://en.wikipedia.org/wiki/Here_document) work with the
|
|
`|` and `>` operators as well. The example below transliterates lower case letters
|
|
to upper case:
|
|
|
|
```yaml
|
|
job:
|
|
script:
|
|
- |
|
|
tr a-z A-Z << END_TEXT
|
|
one two three
|
|
four five six
|
|
END_TEXT
|
|
```
|
|
|
|
Results in:
|
|
|
|
```shell
|
|
$ tr a-z A-Z << END_TEXT # collapsed multiline command
|
|
ONE TWO THREE
|
|
FOUR FIVE SIX
|
|
```
|
|
|
|
## Add color codes to script output
|
|
|
|
Script output can be colored using [ANSI escape codes](https://en.wikipedia.org/wiki/ANSI_escape_code#Colors),
|
|
or by running commands or programs that output ANSI escape codes.
|
|
|
|
For example, using [Bash with color codes](https://misc.flogisoft.com/bash/tip_colors_and_formatting):
|
|
|
|
```yaml
|
|
job:
|
|
script:
|
|
- echo -e "\e[31mThis text is red,\e[0m but this text isn't\e[31m however this text is red again."
|
|
```
|
|
|
|
You can define the color codes in Shell variables, or even [custom environment variables](../variables/README.md#custom-environment-variables),
|
|
which makes the commands easier to read and reusable.
|
|
|
|
For example, using the same example as above and variables defined in a `before_script`:
|
|
|
|
```yaml
|
|
job:
|
|
before_script:
|
|
- TXT_RED="\e[31m" && TXT_CLEAR="\e[0m"
|
|
script:
|
|
- echo -e "${TXT_RED}This text is red,${TXT_CLEAR} but this part isn't${TXT_RED} however this part is again."
|
|
- echo "This text is not colored"
|
|
```
|
|
|
|
Or with [PowerShell color codes](https://superuser.com/a/1259916):
|
|
|
|
```yaml
|
|
job:
|
|
before_script:
|
|
- $esc="$([char]27)"; $TXT_RED="$esc[31m"; $TXT_CLEAR="$esc[0m"
|
|
script:
|
|
- Write-Host $TXT_RED"This text is red,"$TXT_CLEAR" but this text isn't"$TXT_RED" however this text is red again."
|
|
- Write-Host "This text is not colored"
|
|
```
|