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:

container run step
container build step
failure handler
service

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

when: When¶

Defines a set of conditions to determine if a step should run for a given Git event. This attribute is optional - if not present, the step will run for every commit and every branch pushed to the repository.

For full reference see When

runtimeProfile: string¶: The name of a runtime profile that should be applied to the step. For more reference see runtime profiles section

containerRun: ContainerRun¶

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

For full reference see ContainerRun.

containerBuild: ContainerBuild¶

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

For full reference see ContainerBuild.

serviceRun: ServiceRun¶

Service run step is used for launching a Service type container at a specific moment of the pipeline run. It can be used, for example, to create a service out of an application created in one of the previous pipeline steps.

For full reference see ServiceRun.

waitForAccept: WaitForAccept¶

Wait for accept step is used for creating conditional builds. This type of step will pause the pipeline execution and wait for user action before continuing. It can be used, for example, to create pipelines that apply new infrastructure changes only after the user accepts them.

For full reference see WaitForAccept.

Important

The containerRun, containerBuild, serviceRun and waitForAccept fields are mutually exclusive - the step must be of a single type. If more than one field will be set, the pipeline will fail during validation.

ContainerRun: Object¶

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

ContainerBuild: 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.

tags: list(string)¶: Tags 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.

buildArgs: list(BuildArg)¶: A list of build-time arguments.

ServiceRun: Object¶

Creates a Service and exits - the service itself, however, will run until the pipeline finishes.

Note

The status of this step reflects the status of creating the service object, but not the status of the service itself.

name: string: The name of the service.

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 string containing the script that will be executed inside the service container. 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.

WaitForAccept: Object¶

Pauses the pipeline and waits for user acceptance before continuing. Can be set to an empty object {} (which will cause the pipeline to wait indefinitely for user interaction), or a timeout parameter can be set, to ensure that the pipeline will fail after a certain period of inactivity.

timeout: integer¶: Number of seconds that the step will wait for user acceptance. When this timeout is exceeded, the step will fail. If not set or set to 0, the step will wait for user acceptance indefinitely.

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

BuildArg: Object¶

The BuildArg object represents a build-time parameter that will be set during the build. Equivalent to --build-arg parameter in the docker build command.

name: The name of the build argument

value: The value of the build argument

When: Object¶

This object defines the conditions determining if the pipeline step should be run for a specific Git event or not.

event: list¶: A list of event types that the step should run for. Supported values are commit and tag. Optional - if not provided, commit is assumed.

branch: list¶: A list of branch names that the step should run for. Optional - if not provided, the step will run for all branches.

skipBranch: list¶: A list of branch names that the step should not run for. Optional - if not provided, the step will run for all branches defined by the branch attribute. In case the branch attribute is also not provided, the step will run for all branches.

Important

The branch and skipBranch attributes will have effect only if the event attribute contains commit or is empty.

tag: list¶: A list of tag names that the steps should run for. Optional - if not provided, the step will run for all tags.

skipTag: list¶: A list of tag names that the step should not run for. Optional - if not provided, the step will run for all tags defined by the tag attribute. In case the tag attribute is also not provided, the step will run for all tags.

Important

The tag and skipTag attributes will have effect only if the event attribute contains tag.

Note

The branch, skipBranch, tag and skipTag fields support basic string globbing in their list values. This means that you can use * as a wildcard to match multiple values. For example - if you enter feature-* in the branch list, the step will run for all branches with names starting with feature-