• Step workflow
• Use CI/CD Steps
  • Run a step
  • Run a script
  • Run a GitHub action
    • Known issues
  • Step location
    • Load a step from the file system
    • Load a step from a Git repository
  • Expressions
  • Using prior step outputs
  • Environment variables
• Create your own step
  • The step specification
    • Specify inputs
    • Specify outputs
    • Specify delegated outputs
    • Specify no inputs or outputs
  • The step definition
    • Set environment variables
    • Execute a command
      • Return an output
      • Export an environment variable
    • Run a sequence of steps
      • Return an output

CI/CD steps

Steps are reusable units of a job that when composed together replace thescriptused 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 theSet up steps tutorial. To start creating your own steps, seeCreating your own step.

This experimental feature is still in active development and might have breaking changes at any time. Review thechangelog for full details on any breaking changes.

CI/CD steps are different thanCI/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 thescriptin 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 repositories, or in any other Git source.

Additionally, steps:

• Run in a Docker container created by the Steps team, you can review theDockerfile. Followepic 15073to track when steps will run inside the environment defined by the CI/CD job.
• Are specific to Linux. Followepic 15074 to track when steps supports multiple operating systems.

For example, this job uses therunCI/CD keyword to run a step:

job:
variables:
CI_SAY_HI_TO:"Sally "
run:
-name:say_hi
step:gitlab /gitlab-org/ci-cd/runner-tools/[email protected]
inputs:
message:"hello,${{job.CI_SAY_HI_TO}} "

When this job runs, the messagehello, Sallyis 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 therunkeyword. You cannot usebefore_script, after_script,orscriptin a job when you are running CI/CD Steps.

Therunkeyword 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 anameand eitherstep,script,oraction.

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 thestep locationusing thestepkeyword.

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 theCI_BUILDS_DIRpredefined variable.

For example, the echo step loaded from the Git repositorygitlab /components/echo receives the environment variableUSER: Fredand the inputmessage: hello Sally:

job:
variables:
CI_SAY_HI_TO:"Sally "
run:
-name:say_hi
step:gitlab /components/[email protected]
env:
USER:"Fred "
inputs:
message:"hello${{job.CI_SAY_HI_TO}} "

Run a script

Run a script in a shell with thescriptkeyword. Environment variables passed to scripts usingenvare set in the shell. Script steps run in the directory defined by theCI_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 thebashshell. Followissue 109 to track when shell fallback is supported.

Run a GitHub action

Run GitHub actions with theactionkeyword. 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 theCI_PROJECT_DIRpredefined variable.

Running actions requires thedindservice. For more information, see Use Docker to build Docker images.

For example, the following step usesactionto makeyqavailable:

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 existingartifactskeywordandcachekeyword.

Step location

Steps are loaded from a relative path on the file system, GitLab 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 astep.ymlstep 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, thenstep.ymlis loaded from the root folder of the repository.

For example:

• Specify the step with a branch:

  job:
  run:
  -name:my_echo_step
  step:gitlab /gitlab-org/ci-cd/runner-tools/echo-step@main
  

• Specify the step with a tag:

  job:
  run:
  -name:my_echo_step
  step:gitlab /gitlab-org/ci-cd/runner-tools/[email protected]
  

• 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 /gitlab-org/ci-cd/runner-tools/echo-step
  dir:reverse
  rev:main
  

Steps can’t reference Git repositories using annotated tags. Followissue 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
• Thescriptstep
• Theactionstep

Expressions can reference the following variables:

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 withCI_,DOCKER_, orGITLAB_.Followepic 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 thegitlab /components/random-stringstep defined an output variable calledrandom_value:

job:
run:
-name:generate_rand
step:gitlab /components/random
-name:echo_random
step:gitlab /components/echo
inputs:
message:"Therandomvalueis:${{steps.generate_rand.random_value}} "

Environment variables

Steps cansetenvironment variables,export environment variables, and environment variables can be passed in when usingstep,script,oraction.

Environment variable precedence, from highest to lowest precedence, are variables set:

1. By usingenvkeyword in thestep.yml.
2. By using theenvkeyword passed to a step in a sequence of steps.
3. By using theenvkeyword for all steps in a sequence.
4. Where a previously run step has written to${{export_file}}.
5. By the Runner.
6. By the container.

Create your own step

Create your own step by performing the following tasks:

1. Create a GitLab project, a Git repository, or a directory on a file system that is accessible when the CI/CD job runs.
2. Create astep.ymlfile and place it in the root folder of the project, repository, or directory.
3. Define thespecificationfor the step in thestep.yml.
4. Define thedefinitionfor the step in thestep.yml.
5. Add any files that your step uses to the project, repository, or directory.

After the step is created, you canuse the step in a job.

The step specification

The step specification is the first of two documents contained in the stepstep.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.

For example, to specify that the step accepts an optional input calledgreetingof typestring:

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,anotherworld "

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.

For example, to specify that the step returns an output calledvalueof typenumber:

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:"Randomnumbergeneratedwas${{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. Thedelegatekeyword in the step definition determines which sub-step outputs are returned by the step.

For example, the following step returns outputs returned by therandom-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 theenvkeyword. 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. Followepic 15073to track when steps can access all environment variables.

Execute a command

A step declares it executes a command by using theexeckeyword. 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} "

Return an output

Executable steps return an output by adding a line to the${{output_file}}in the formatname=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 namedcarwithstringvaluerange 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 formatname=value.Double quotation marks are not required around the value.

For example, to set the variableGOPATHto 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 thestepskeyword. Steps run one at a time in the order they are defined in the list. This syntax is the same as therunkeyword.

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 theoutputskeyword. 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 theinstall_javastep returns an output namedjava_version.

spec:
outputs:
java_version:
type:string
---
steps:
-name:install_java
step:./common/install-java
outputs:
java_version:"thejavaversionis${{steps.install_java.outputs.java_version}} "

Alternatively, all outputs of a sub-step can be returned using thedelegatekeyword. For example:

spec:
outputs:delegate
---
steps:
-name:install_java
step:./common/install-java
delegate:install_java