CI/CD steps
Steps are reusable units of a job that when composed together replace the script
used in a GitLab CI/CD job.
While you are not required to use steps, the reusability, composability, testability, and independence
of steps make it easier to understand and maintain CI/CD pipeline.
To get started, you can try the Set up steps tutorial. To start creating your own steps, see Creating your own step.
This experimental feature is still in active development and might have breaking changes at any time. Review the changelog for full details on any breaking changes.
CI/CD steps are different than CI/CD components. Components are reusable single pipeline configuration units. They are included in a pipeline when it is created, adding jobs and configuration to the pipeline. Files such as common scripts or programs from the component project cannot be referenced from a CI/CD job.
CI/CD Steps are reusable units of a job. When the job runs, the referenced step is downloaded to
the execution environment or image, bringing along any extra files included with the step.
Execution of the step replaces the script
in the job.
Step workflow
A step either runs a sequence of steps or executes a command. Each step specifies inputs received and outputs returned, has access to CI/CD job variables, environment variables, and resources provided by the execution environment such as the file system and networking. Steps are hosted locally on the file system, in GitLab.com repositories, or in any other Git source.
Additionally, steps:
- Run in a Docker container created by the Steps team, you can review the
Dockerfile
. Follow epic 15073 to track when steps will run inside the environment defined by the CI/CD job. - Are specific to Linux. Follow epic 15074 to track when steps supports multiple operating systems.
For example, this job uses the run
CI/CD keyword to run a step:
job:
variables:
CI_SAY_HI_TO: "Sally"
run:
- name: say_hi
step: gitlab.com/gitlab-org/ci-cd/runner-tools/echo-step@v1.0.0
inputs:
message: "hello, ${{job.CI_SAY_HI_TO}}"
When this job runs, the message hello, Sally
is printed to job log.
The definition of the echo step is:
spec:
inputs:
message:
type: string
---
exec:
command:
- bash
- -c
- echo '${{inputs.message}}'
Use CI/CD Steps
Configure a GitLab CI/CD job to use CI Steps with the run
keyword. You cannot use before_script
,
after_script
, or script
in a job when you are running CI/CD Steps.
The run
keyword accepts a list of steps to run. Steps are run one at a time in the order they are defined in the list.
Each list item has a name
and either step
, script
, or action
.
Name must consist only of alpha-numeric characters and underscores, and must not start with a number.
Run a step
Run a step by providing the step location using the step
keyword.
Inputs and environment variables can be passed to the step, and these can contain expressions that interpolate values.
Steps run in the directory defined by the CI_BUILDS_DIR
predefined variable.
For example, the echo step loaded from the Git repository gitlab.com/components/echo
receives the environment variable USER: Fred
and the input message: hello Sally
:
job:
variables:
CI_SAY_HI_TO: "Sally"
run:
- name: say_hi
step: gitlab.com/components/echo@v1.0.0
env:
USER: "Fred"
inputs:
message: "hello ${{job.CI_SAY_HI_TO}}"
Run a script
Run a script in a shell with the script
keyword. Environment variables passed to scripts
using env
are set in the shell. Script steps run in the directory defined by the CI_BUILDS_DIR
predefined variable.
For example, the following script prints the GitLab user to the job log:
my-job:
run:
- name: say_hi
script: echo hello ${{job.GITLAB_USER_LOGIN}}
Script steps always use the bash
shell. Follow issue 109
to track when shell fallback is supported.
Run a GitHub action
Run GitHub actions with the action
keyword. Inputs and environment variables are passed directly to the
action, and action outputs are returned as step outputs. Action steps run in the directory
defined by the CI_PROJECT_DIR
predefined variable.
Running actions requires the dind
service. For more information, see
Use Docker to build Docker images.
For example, the following step uses action
to make yq
available:
my-job:
run:
- name: say_hi_again
action: mikefarah/yq@master
inputs:
cmd: echo ["hi ${{job.GITLAB_USER_LOGIN}} again!"] | yq .[0]
Known issues
Actions running in GitLab do not support uploading artifacts directly.
Artifacts must be written to the file system and cache instead, and selected with the
existing artifacts
keyword and cache
keyword.
Step location
Steps are loaded from a relative path on the file system, GitLab.com repositories, or any other Git source.
Load a step from the file system
Load a step from the file system using a relative path that starts with a full-stop .
.
The folder referenced by the path must contain a step.yml
step definition file.
Path separators must always use forward-slashes /
, regardless of operating system.
For example:
- name: my-step
step: ./path/to/my-step
Load a step from a Git repository
Load a step from a Git repository by supplying the URL and revision (commit, branch, or tag) of the repository.
You can also specify the relative directory of the step inside the repository.
If the URL is specified without a directory, then step.yml
is loaded from the root folder of the repository.
For example:
-
Specify the step with a branch:
job: run: - name: my_echo_step step: gitlab.com/gitlab-org/ci-cd/runner-tools/echo-step@main
-
Specify the step with a tag:
job: run: - name: my_echo_step step: gitlab.com/gitlab-org/ci-cd/runner-tools/echo-step@v1.0.0
-
Specify the step with a Git rev and directory in a repository:
job: run: - name: specifying_a_revision_and_directory_within_the_repository step: git: url: gitlab.com/gitlab-org/ci-cd/runner-tools/echo-step dir: reverse rev: main
Steps can’t reference Git repositories using annotated tags. Follow issue 123 to track when annotated tags are supported.
Expressions
Expressions are a mini-language enclosed in double curly-braces ${{ }}
. Expressions are evaluated
just prior to step execution in the job environment and can be used in:
- Input values
- Environment variable values
- Step location URL
- The executable command
- The executable work directory
- Outputs in a sequence of steps
- The
script
step - The
action
step
Expressions can reference the following variables:
Variable | Example | Description |
---|---|---|
env
| ${{env.HOME}}
| Access to environment variables set on the execution environment or in previous steps. |
export_file
| echo name=FRED >${{export_file}}
| The path to the export file. Write to this file to export environment variables for use by subsequent running steps. |
inputs
| ${{inputs.message}}
| Access inputs to the step. |
job
| ${{job.GITLAB_USER_NAME}}
| Access GitLab CI/CD job variables, limited to those starting with CI_ , DOCKER_ or GITLAB_ .
|
output_file
| echo name=Fred >${{output_file}}
| The path to the output file. Write to this file to set output variables from the step. |
step_dir
| work_dir: ${{step_dir}}
| The folder to where the step has been downloaded. Use to refer to files in the step, or to set the work directory of an executable step. |
steps.[step-name].outputs
| ${{steps.my-step.outputs.name}}
| Access to outputs from previously executed steps. Choose the specific step using the step name. |
work_dir
| ${{work_dir}}
| The work directory of an executing step. |
Expressions are different from template interpolation which uses double square-brackets ($[[ ]]
)
and are evaluated during job generation.
Expressions only have access to CI/CD job variables with names starting with CI_
, DOCKER_
,
or GITLAB_
. Follow epic 15073
to track when steps can access all CI/CD job variables.
Using prior step outputs
Step inputs can reference outputs from prior steps by referencing the step name and output variable name.
For example, if the gitlab.com/components/random-string
step defined an output variable called random_value
:
job:
run:
- name: generate_rand
step: gitlab.com/components/random
- name: echo_random
step: gitlab.com/components/echo
inputs:
message: "The random value is: ${{steps.generate_rand.random_value}}"
Environment variables
Steps can set environment variables, export
environment variables, and environment variables can be passed in when using step
, script
, or action
.
Environment variable precedence, from highest to lowest precedence, are variables set:
- By using
env
keyword in thestep.yml
. - By using the
env
keyword passed to a step in a sequence of steps. - By using the
env
keyword for all steps in a sequence. - Where a previously run step has written to
${{export_file}}
. - By the Runner.
- By the container.
Create your own step
Create your own step by performing the following tasks:
- Create a GitLab project, a Git repository, or a directory on a file system that is accessible when the CI/CD job runs.
- Create a
step.yml
file and place it in the root folder of the project, repository, or directory. - Define the specification for the step in the
step.yml
. - Define the definition for the step in the
step.yml
. - Add any files that your step uses to the project, repository, or directory.
After the step is created, you can use the step in a job.
The step specification
The step specification is the first of two documents contained in the step step.yml
.
The specification defines inputs and outputs that the step receives and returns.
Specify inputs
Input names can only use alpha-numeric characters and underscores, and must not start with a number. Inputs must have a type, and they can optionally specify a default value. An input with no default value is a required input, it must be specified when using the step.
Inputs must be one of the following types.
Type | Example | Description |
---|---|---|
array
| ["a","b"]
| A list of un-typed items. |
boolean
| true
| True or false. |
number
| 56.77
| 64 bit float. |
string
| "brown cow"
| Text. |
struct
| {"k1":"v1","k2":"v2"}
| Structured content. |
For example, to specify that the step accepts an optional input called greeting
of type string
:
spec:
inputs:
greeting:
type: string
default: "hello, world"
---
To provide the input when using the step:
run:
- name: my_step
step: ./my-step
inputs:
greeting: "hello, another world"
Specify outputs
Similar to inputs, output names can only use alpha-numeric characters and underscores, and must not start with a number. Outputs must have a type, and they can optionally specify a default value. The default value is returned when the step doesn’t return the output.
Outputs must be one of the following types.
Type | Example | Description |
---|---|---|
array
| ["a","b"]
| A list of un-typed items. |
boolean
| true
| True or false. |
number
| 56.77
| 64 bit float. |
string
| "brown cow"
| Text. |
struct
| {"k1":"v1","k2":"v2"}
| Structured content. |
For example, to specify that the step returns an output called value
of type number
:
spec:
outputs:
value:
type: number
---
To use the output when using the step:
run:
- name: random_generator
step: ./random-generator
- name: echo_number
step: ./echo
inputs:
message: "Random number generated was ${{step.random-generator.outputs.value}}"
Specify delegated outputs
Instead of specifying output names and types, outputs can be entirely delegated to a sub-step.
The outputs returned by the sub-step are returned by your step. The delegate
keyword
in the step definition determines which sub-step outputs are returned by the step.
For example, the following step returns outputs returned by the random-generator
.
spec:
outputs: delegate
---
steps:
- name: random_generator
step: ./random-generator
delegate: random-generator
Specify no inputs or outputs
A step might not require any inputs or return any outputs. This could be when a step
only writes to disk, sets an environment variable, or prints to STDOUT. In this case,
spec:
is empty:
spec:
---
The step definition
Steps can:
- Set environment variables
- Execute a command
- Run a sequence of other steps.
Set environment variables
Set environment variables by using the env
keyword. Environment variable names can only use
alpha-numeric characters and underscores, and must not start with a number.
Environment variables are made available either to the executable command or to all of the steps if running a sequence of steps. For example:
spec:
---
env:
FIRST_NAME: Sally
LAST_NAME: Seashells
steps:
# omitted for brevity
Steps only have access to a subset of environment variables from the runner environment. Follow epic 15073 to track when steps can access all environment variables.
Execute a command
A step declares it executes a command by using the exec
keyword. The command must be specified,
but the working directory (work_dir
) is optional. Environment variables set by the step
are available to the running process.
For example, the following step prints the step directory to the job log:
spec:
---
exec:
work_dir: ${{step_dir}}
command:
- bash
- -c
- "echo ${PWD}"
go
, it should first install it.Return an output
Executable steps return an output by adding a line to the ${{output_file}}
in the format name=value
,
where the value is a JSON representation of the output type. The type of value written by the step
must match the type of the output in the step specification.
For example, to return the output named car
with string
value range rover
:
spec:
outputs:
car:
type: string
---
exec:
command:
- bash
- -c
- echo car=\"range rover\" >>${{output_file}}
Export an environment variable
Executable steps export an environment variable by adding a line to the ${{export_file}}
in the format name=value
. Double quotation marks are not required around the value.
For example, to set the variable GOPATH
to value /go
:
spec:
---
exec:
command:
- bash
- -c
- echo GOPATH=/go >${{export_file}}
Run a sequence of steps
A step declares it runs a sequence of steps using the steps
keyword. Steps run one at a time
in the order they are defined in the list. This syntax is the same as the run
keyword.
Steps must have a name consisting only of alpha-numeric characters and underscores, and must not start with a number.
For example, this step installs Go, then runs a second step that expects Go to already have been installed:
spec:
---
steps:
- name: install_go
step: ./go-steps/install-go
inputs:
version: "1.22"
- name: format_go_code
step: ./go-steps/go-fmt
inputs:
code: path/to/go-code
Return an output
Outputs are returned from a sequence of steps by using the outputs
keyword.
The type of value in the output must match the type of the output in the step specification.
For example, the following step returns the installed Java version as an output.
This assumes the install_java
step returns an output named java_version
.
spec:
outputs:
java_version:
type: string
---
steps:
- name: install_java
step: ./common/install-java
outputs:
java_version: "the java version is ${{steps.install_java.outputs.java_version}}"
Alternatively, all outputs of a sub-step can be returned using the delegate
keyword.
For example:
spec:
outputs: delegate
---
steps:
- name: install_java
step: ./common/install-java
delegate: install_java