task: execute a task

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.

For example, 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.

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. For example, 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

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.

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}