task
step
Executes a Task, either from a file fetched via the preceding steps, or with inlined configuration.
If any task in the build plan fails, the build will complete with failure. By default, any subsequent steps will not be performed. You can perform additional steps after failure by adding a on_failure
or ensure
step hook.
When a task completes, the files in its declared outputs will be made avaliable to subsequent steps. This allows those subsequent steps to process the result of a task.
task: string
Required. A freeform name for the task that's being executed. Common examples would be unit
or integration
.
config: object
Required. The task config to execute. An alternative to file
.
file: string
Required. A dynamic alternative to config
.
file
points at a .yml
file containing the task config, which allows this to be tracked with your resources.
The first segment in the path should refer to another source from the plan, and the rest of the path is relative to that source.
For example, if in your plan you have the following get
step:
- get: something
And the something
resource provided a unit.yml
file, you would set file: something/unit.yml
.
privileged: boolean
Optional. Default false
. If set to true
, the task will run with full capabilities, as determined by the Garden backend the task runs on. For Linux-based backends it typically determines whether or not the container will run in a separate user namespace, and whether the root
user is "actual" root
(if set to true
) or a user namespaced root
(if set to false
, the default).
This is a gaping security hole; use wisely and only if necessary. This is not part of the task configuration to prevent privilege escalation via pull requests.
params: object
Optional. A map of task parameters to set, overriding those configured in config
or file
.
For example:
plan:
- get: my-repo
- task: integration
file: my-repo/ci/integration.yml
params:
REMOTE_SERVER: 10.20.30.40:8080
USERNAME: my-user
PASSWORD: my-pass
This is often used in combination with ((parameters))
in the pipeline.
For example:
plan:
- get: my-repo
- task: integration
file: my-repo/ci/integration.yml
params:
REMOTE_SERVER: 10.20.30.40:8080
USERNAME: ((integration-username))
PASSWORD: ((integration-password))
Looking into the task.yml
, a common pattern is to list the param in the task definition with no value. This indicates that you expect the pipeline to provide the value.
For example, in the task.yml
:
params:
FOO: fizzbuzz
BAR:
And in the pipeline.yml
:
params:
BAR: qux
If the pipeline used this task.yml
but did not set BAR
, the value of $BAR
would be set to the empty string in the task container.
image: string
Optional. Names an artifact source within the plan containing an image to use for the task. This overrides any image_resource
configuration present in the task configuration.
This is very useful when part of your pipeline involves building an image, possibly with dependencies pre-baked. You can then propagate that image through the rest of your pipeline, guaranteeing that the correct version (and thus a consistent set of dependencies) is used throughout your pipeline.
For example, here's a pipeline building an image in one job and propagating it to the next:
resources:
- name: my-project
type: git
source: {uri: https://github.com/my-user/my-project}
- name: my-task-image
type: docker-image
source: {repository: my-user/my-repo}
jobs:
- name: build-task-image
plan:
- get: my-project
- put: my-task-image
params: {build: my-project/ci/images/my-task}
- name: use-task-image
plan:
- get: my-task-image
passed: [build-task-image]
- get: my-project
passed: [build-task-image]
- task: use-task-image
image: my-task-image
file: my-project/ci/tasks/my-task.yml
This can also be used in the simpler case of explicitly keeping track of dependent images, in which case you just wouldn't have a job building it (build-task-image
in the above example).
input_mapping: object
Optional. A map from task input names to concrete names in the build plan. This allows a task with generic input names to be used multiple times in the same plan, mapping its inputs to specific resources within the plan.
For example:
plan:
- get: diego-release
- get: cf-release
- get: ci-scripts
- task: audit-diego-release
file: ci-scripts/audit-release.yml
input_mapping: {release-repo: diego-release}
- task: audit-cf-release
file: ci-scripts/audit-release.yml
input_mapping: {release-repo: cf-release}
output_mapping: object
Optional. A map from task output names to concrete names to register in the build plan. This allows a task with generic output names to be used multiple times in the same plan.
This is often used together with input_mapping
. For example:
plan:
- get: diego-release
- get: cf-release
- get: ci-scripts
- task: create-diego-release
file: ci-scripts/create-release.yml
input_mapping: {release-repo: diego-release}
output_mapping: {release-tarball: diego-release-tarball}
- task: create-cf-release
file: ci-scripts/create-release.yml
input_mapping: {release-repo: cf-release}
output_mapping: {release-tarball: cf-release-tarball}
Examples
Inputs & Outputs
The following plan pulls down a repo, makes a commit to it, and pushes the commit to another repo (the task must have an output called repo-with-commit
):
plan:
- get: my-repo
- task: commit
file: my-repo/commit.yml
- put: other-repo
params:
repository: repo-with-commit
Build Matrix with aggregate
The following plan fetches a single repository and executes multiple tasks, using the aggregate
step, in a build matrix style configuration:
plan:
- get: my-repo
- aggregate:
- task: go-1.3
file: my-repo/go-1.3.yml
- task: go-1.4
file: my-repo/ci/go-1.4.yml
Only if both tasks succeed will the build go green. See also aggregate
step.