Pipeline Steps

Pipeline steps define the actual payloads that are run during job executions. Each pipeline step is run in a defined container image. Components may specify an arbitrary graph of steps. Some traits add steps to build jobs as well (see traits documentation).

Each build step must be given a unique name (per job). By default, an executable named .ci/<step_name> is expected in the main repository’s work tree. It is run inside a container with a specifiable container image with a defined set of environment variables.

The resulting exit code is used to determine whether or not the step execution has succeeded. A zero exit code is interpreted as success, wheras non-zero exit codes are interpreted as failures.

Accessing the path to a repository in your build step should be done using given environment variables as described in Environment Variables from repositories.

• all job steps are executed in parallel by default

• dependendencies between steps may be declared

• job steps may publish changes to repositories

Attributes

name	required?	default	type	explanation
depends	no	set()	set	step names this step declares a dependency towards
trait_depends	no	set()	set	names of traits this step declares a dependency towards. This will result in a dependency towards all steps defined by these traits
execute	no	step name	str	The executable (with optional additional arguments) to run. The executable path is calculated relative to <main_repo>/.ci. Has two forms: scalar value (str in most cases) –> no shell-escaping is done list of scalar values -> used verbatim as ARGV
escape_argv	no	True	str	defines whether or not ARGV (execute attr) should be escaped setting to False will allow for e.g. environment-variable expansion
notifications_cfg	no	default	str	Configures build notification policies (see notifications trait)
image	no	None	str	the container image reference to use for the executing container. If not set, the default image will be used.
registry	no	None	str	The container image registry cfg_name. Required when retrieving container images from a non-default image registry that requires authentication.
inputs	no	{}	dict	a mapping of inputs produced by other build steps: { input_name: output_name } input_name is converted to UPPER_CASE and exposed to the step as an environment variable containing the relative path to the output.
output_dir	no	None	str	exposes a writable directory to the job. The directory is specified via environment variable named as the given value + _PATH (converted to UPPER-case and snake_case). Any files placed into this directory are passed to subsequent steps declaring the output as input. The unchanged value configured is used as input name. e.g.: output_dir: out results in env var OUT_PATH.
publish_to	no	{}	list	has two forms: list of logical repository names to which commits created by this step should be published. a dictionary: <name: options> The second form currently accepts exactly one argument: force_push (bool) and is used to specify that a force-push should be done. The step executable must only commit the changes in the repository’s worktree without pushing them. Example: steps: foo: publish_to: my_repo: force_push: true
vars	no	{}	str	pairs of {env_var_name: <python expression>} the specified python expressions are evaluated during pipeline replication. An instance of the current pipeline_model is accessible through the pipeline_descriptor symbol. The evaluation result is exposed to this build step via the specified environment variable.
cache_paths	no	[]	str	Warning EXPERIMENTAL - this attr might be removed or changed a list of paths (relative to initial PWD) that should be cached.
privilege_mode	no	unprivileged	PrivilegeMode	privilege mode for step. Use carefully when running potentially untrusted code.
timeout	no	None	str	go-style time interval (e.g.: ‘1h30m’) after which the step will be interrupted and fail.
retries	no	None	str	positive integer specifying the maximum amount of failures until the step is counted as failed
on_abort	no	None	str	The executable (with optional additional arguments) to run in case the job is aborted. The executable path is calculated relative to <main_repo>/.ci. Just like execute this has two forms: scalar value (str in most cases) –> no shell-escaping is done list of scalar values -> used verbatim as ARGV The resulting on_abort step will use the same container image reference as the job that defines it. Also, it will have the same in- and outputs available and access to the same env-vars. Note on_abort-steps themselves cannot be aborted. Beware.

privilege_mode Enumeration Values

• privileged

• unprivileged

Examples

steps:
  first_step: ~     # execute .ci/first_step

  custom_executable:
    execute:
      "my_script"   # execute .ci/my_script

  custom_image:
    image: 'alpine:3.6'

  executable_with_args:
    execute:
    - "another_executable"  # .ci/another_executable
    - "--with-an-option"
    - "args may contain whitespace characters"

  build_and_expose_output:
    output_dir: 'build_result_dir' # may be used e.g. by publish trait

  publish_commits:
    depends:
    - build_and_expose_output  # run only after build_and_expose_output finished
    publish_to:
    - source    # 'source' is the default name for the main repository

  force_push:
    publish_to:
      another_repo:
        force_push: true # use with caution!

  define_env_vars:
    vars:
      AN_ENV_VAR: '"my_important_value"'         # assign my_important_value to AN_ENV_VAR
      ANOTHER: 'pipeline_descriptor.get("name")' # assign pipeline name to ANOTHER