Dispatch Pipeline Configuration Reference

Pipeline

The Pipeline object is the top-level object in a Dispatchfile.

Tasks

Tasks define a set of steps (containers) to run sequentially within a pod; these do the work of the pipeline.

If the timeout field is set on a task, and then:

• the PipelineRun fails or times out before the task is scheduled, then the task will not be started.
• the PipelineRun times out after the task is started, but before it completes, then the task will continue executing until it succeeds, fails or exceeds its own timeout duration. In this scenario, the PipelineRun will still be marked as failed, due to timeout, even though all its tasks may have succeeded individually.

Input variables

Input variables can be accessed when listed in the inputs of a task. Two types of inputs are supported:

• If an input is a resource, then its parameters can be accessed at $(inputs.resources.NAME.PARAM), where NAME is the resource name and PARAM is the parameter name.
• If an input is a task, then its results can be accessed at $(inputs.tasks.TASKNAME.STEPNAME), where TASKNAME is the name of the task and STEPNAME is the name of the step in the task. The variable will be equal to the standard output of the referenced step.

Output variables

Output variables function like input variables, except they are for outputs, rather than inputs. Only resources are supported as outputs. An output’s parameters can be accessed at $(outputs.resources.NAME.PARAM), where NAME is the resource name and PARAM is the parameter name.

Metadata

A metadata object contains labels and annotations:

| labels | String map | Labels to add | no | {} | | annotations | String map | Annotations to add | no | {} |

Resources

Resources define Git repositories, images, and other artifacts that are consumed or produced by a task. A resource can only be output by at most one task. Any task taking the resource as input will be run after the output task.

Types of Resources

In theory, all resource types supported by Tekton are supported by Dispatch; however, Git, Image, and Storage resources are the most frequently used resource types.

Git

The Git resource is used as an input to tasks and clones a Git repository into the task.

Parameters:

Image

An Image resource refers to an image that has been or should be built by a task. When used as a task output, the Image resource tells the task where to push the built image to. When used as a task input, the Image resource references the image URL and digest of a previously built image.

Parameters:

Storage

A Storage resource is used for storing built artifacts to pass between built tasks. For example, a build task may build a Go binary and another task may use the binary as a part of a Docker build. Artifacts can be stored in any S3-compatible API, however, a local Minio instance is provisioned by default with a bucket called artifacts.

Parameters:

Actions

Actions define which tasks to run for which events.

Conditions

A condition specifies the requirements for an action to be considered active. Exactly one of git, cron, or image must be set. Fields push, tag, pull_request, release are also supported but are DEPRECATED.

GitConditions

Describes various kinds of conditions that are activated by events from scm repositories. Only one of the following must be set.

PushConditions

A push condition is activated when commits are pushed to any matched branch with any matched file changes.

The current behavior of push conditions is:

1. If no branches or paths are specified, then a push to any branch will trigger the condition.
2. If branches are specified, then it will only trigger on any matched branch. If paths are specified, it will only trigger if any changed file matches the paths.
3. You can specify positive glob patterns (e.g., “release/*”) or negative glob patterns (e.g., “!debug/*”) to match a branch or path. A branch or path matches the globs if it matches at least one positive glob if there is any, and does not match any negative glob.

TagConditions

A tag condition is activated when a tag is pushed to the repository.

The current behavior of tag conditions is:

1. If no names are specified, then any tag pushed to the repository will trigger the condition.
2. If names are specified, then it will only trigger on specified tag names.
3. You can specify positive glob patterns (e.g., “release/*”) or negative glob patterns (e.g., “!debug/*”) to match a tag. A tag matches the globs if it matches at least one positive glob if there is any, and does not match any negative glob.

PullRequestConditions

A pull request condition is activated when a comment or push is made on a pull request.

The current behavior of pull request conditions is:

1. If no branches and no chatops are specified, then the action will trigger on any pull request push.
2. If branches are specified, then it will trigger when a pull request is made where the merge target is in the list of branches. If paths are specified, it will only trigger if any changed file matches the paths.
3. If chatops are specified, then it will only trigger when a comment starting with a slash (/) is made to a pull request, and the word after the slash is in the list of chatops. Chatops can be specified in conjunction with branches and/or paths.
4. All the labels need to be matched. Label matching is not regex based and supports exact string matching only except for negative matching (by using ! prefix).

GitReleaseConditions

A release condition is activated when a release is published in the repository. Currently, this is only supported for GitHub repositories.

The current behavior of tag conditions is:

1. If no tag is specified, then any release published in the repository will trigger the condition.
2. If tags are specified, then it will only trigger on specified tags.
3. You can specify positive glob patterns (e.g., “release/*”) or negative glob patterns (e.g., “!debug/*”) to match a tag. A tag matches the globs if it matches at least one positive glob if there is any, and does not match any negative glob.

CronConditions

A cron condition is activated when the schedule embedded is activated. Unlike other conditions, CronConditions are only activated from the default revision (specified during repository creation) of Dispatchfile.

GitCronConfig

A GitCronConfig specifies the configuration (revision of the git repository to use for pipelines) to use when the associated cron condition is triggered.

ImageConditions

Describes various kinds of conditions that are activated by events from registries (Only docker registry is supported currently, more will be added soon). Only one of the following must be set.

ImagePushConditions

A push condition is activated when an image is pushed in the repository. Currently, this is only supported for GitHub repositories.

Context variables

Dispatch adds a number of context variables to your build. These variables are replaced at runtime after parsing the configuration file.

• $(context.build.name): the most relevant identifier for the build - either branch, tag, pull request, or the user that triggered it.
• $(context.git.url): the URL to the git repository to clone.
• $(context.git.commit): the git commit identifier to clone.
• $(context.git.branch): the git branch the pipeline was triggered for.
• $(context.git.tag): the git tag (if any) the pipeline was triggered for.
• $(context.chatop.command): the ChatOp command that triggered the pipeline.

Generated Pipeline naming convention

A PipelineRun generated from SCM webhook / cron event has the following convention:

Total length of the PipelineRun name is capped at 64 characters out of which 5 characters are exclusively reserved for a random suffix. Extra characters are right trimmed.