Pipeline structure

Pipeline root object

The root of pipeline yaml file consists of the following fields.

steps: list(Step)

List of Step objects.

For more information and examples on how steps work see steps section.

services: list(Service)

List of Service objects. Services will be created all at once, at the beginning of pipeline.

For more information and examples on how services work see services section.

failureHandlers: list(FailureHandler)

List of FailureHandler objects.

List of all failure handler objects available in the whole pipeline. They can be referenced by both Step or other global failure handlers.

For more information and examples on how failure handlers work see failure handlers section.

globals: object

Globals object contains settings that will be passed down to the relevant objects in the pipeline.

For more information and examples see globals section.

dockerSecret: string

Name of the docker secret used for communicating with docker registry.

This value will be passed to the following objects:

onFailure: list(FailureHandlerReference)

List of global failure handlers. Those failure handlers will be run after every failed step in the pipeline, no matter what type it was.

environment: list(EnvironmentVariable)

List of environment variables.

Those environment variables will be passed to every Docker run step in the pipeline.

Important

Failure handlers have access to all the environment variables of a given step injected into their spec, so they’re available in the failure handler as well.

files: list(File)

List of files that will be mounted in every Docker run step in the pipeline.

Important

Like environment variables, files from a given step are also mounted into Failure handlers.

Objects and types

Definitions of all objects and types used in the pipeline definition.

Step: Object

Step is an object in the pipeline representing a single execution unit.

For more information and examples of how steps work see steps section.

name

Name of the step. This name will be displayed in the UI.

onFailure: list(FailureHandlerReference)

List of FailureHandlerReference objects. All of failure handlers will be executed in the order declared in this list. If global failure handlers are also defined, they will be run after those specified here.

dockerRun: DockerRun

Docker run step is used for running various commands in a container.

For full reference see DockerRun.

dockerBuild: DockerBuild

Docker build step is used to build a Docker image and publish it to a specified Docker registry.

For full reference see DockerBuild.

Important

A step can be either a dockerRun or dockerBuild type - never both. If more than one field will be set, the pipeline will fail during validation.

DockerRun: Object

Docker run executes the script inside a Docker container running a Docker image. If any of the commands exit with code other than 0, the step will fail.

image: string

Docker image used to run your commands.

dockerSecret: string = ""

Name of the Docker secret used for communicating with Docker registry. Used for pulling image from private registries.

script: string

A string containing the script that will be executed. The shell is run with set -e so this script will fail if any of the commands exits with a code other than 0. If empty, the default command from the Docker image will be executed.

environment: list(EnvironmentVariable)

List of environment variables passed to the container.

files: list(File)

List of files that will be mounted in the container.

DockerBuild: Object

Build the Docker image and pushes it to registry.

registry: string = docker.io

Address of the Docker registry used to store images.

user: string

User used to login to the Docker registry.

imageName: string

Name of the image that will be built. This name is not the full image name, but only the name of a given image without a tag, user and registry.

tag: string

Tag of a Docker image that will be build.

contextPath: string = .

Path that will be used as context in the Docker build process. See docker help command for more information.

Important

The context will be set to ., but the current working directory is set to the workspace folder, so it will behave like the Docker command is run inside the source directory.

dockerfilePath: string = Dockerfile

Path to the Dockerfile file.

dockerSecret: string

Name of the Docker secret used for communicating with Docker registry. Used for pulling image from private registries.

Service: Object

Service runs an application specified by script inside a Docker image.

name: string

Name of the service that will be used in the UI and also for communicating with the service. This name will be added to /etc/hosts of every step and failure handler in the pipeline, so the service can be resolved using the name.

image: string

Docker image used to run the service.

dockerSecret: string

Name of the Docker secret used for communicating with Docker registry. Used for pulling image from private registries.

script: string = ""

A script or command that will be executed. If empty, the default command from the Docker image will be executed.

environment: list(EnvironmentVariable)

List of environment variables passed to the container.

FailureHandler: Object

Failure handler is an object representing a special kind of pipeline execution unit for handling errors in pipeline steps. Its definition is very similar to the docker run step.

name: string

Name of the failure handler. This name will be used by FailureHandlerReference

image: string

Docker image used to run the failure handler.

dockerSecret: string

Name of the Docker secret used for communicating with Docker registry. Used for pulling image from private registries.

script: string

A script or command that will be executed. If empty, the default command from the Docker image will be executed.

environment: list(EnvironmentVariable)

List of environment variables passed to the container.

files: list(File)

List of files that will be mounted in the container.

FailureHandlerReference: Object

Failure handler reference is an object representing reference to a defined failure handler.

handlerName

Name of the FailureHandler object to run. The failure handler must be defined in the failureHandlers list - else the pipeline will fail during validation.

EnvironmentVariable: Object

The environment variable object represents an environment variable within a container. You can provide a value inline through value or by referencing a secret by its name using fromSecret field.

name

The name of the environment variable that will be passed to the container.

value

Value for a given environment variable.

fromSecret

Name of a secret from which the value should be retrieved to inject to the container as an environment variable.

Note

Currently IceCI supports creating environment variables by explicitly entering their values in the pipeline yaml or by providing a secret name from which the value should be taken. Those options are exclusive for a given variable - you can’t have both value and fromSecret set at the same time - the pipeline validation will fail.

File: Object

The file object represents a file that’ll be mounted in a container from a secret. Unlike environment variables, file values cannot be provided inline - they have to reference a secret.

path

The absolute path that the file will be mounted in.

fromSecret

Name of a secret from which the value should be retrieved to mount into the container as a file.