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 givenstep
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 intoFailure 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
ordockerBuild
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 Dockerimage
. If any of the commands exit with code other than0
, 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 than0
. If empty, the defaultcommand
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
andregistry
.
-
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 Dockerimage
.-
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
andfailure 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 thefailureHandlers
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 usingfromSecret
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 bothvalue
andfromSecret
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.
-