Task Context#

The taskgraph.transforms.task_context transform can be used to substitute values into any field in a task with data that is not known until taskgraph runs.

This data can be provided in a few ways, as described below.

Usage#

from-parameters#

Context can be pulled from parameters that are provided to taskgraph.

First, add the transform to the transforms key in your kind.yml file:

transforms:
  - taskgraph.transforms.task_context
  # ...

Then create a task-context section in your task definition, e.g:

tasks:
  build:
    description: my description {foo}
    task-context:
      from-parameters:
        foo: foo
      substitution-fields:
        - description

When taskgraph is run the value of foo in the parameters it is provided will be substituted into the description. For example, if the following parameters are used:

foo: with some extra

…the description will end up with a value of “my description with some extra”.

When using from-parameters you may also provide an ordered list of keys to look for in the parameters, with the first one found being used. For example, with the this kind:

tasks:
  build:
    description: my description {foo}
    task-context:
      from-parameters:
        foo:
          - foo
          - default
      substitution-fields:
        - description

…the description will bring in the value foo from the parameters if present, or default otherwise.

from-file#

Context may also be provided from a defined yaml file. The provided file should usually only contain top level keys and values (eg: nested objects will not be interpolated - they will be substituted as text representations of the object).

For example, with this kind definition:

tasks:
  build:
    description: my description {foo}
    task-context:
      from-file: some_file.yaml
      substitution-fields:
        - description

And this in some_file.yaml:

foo: from a file

…description will end up with “my description from a file”.

from-object#

You may also specify context as direct keys and values in the task-context configuration in from-object . This can be useful in kinds that define most of their contents in task-defaults, but have some values that may differ for various concrete tasks in the kind.

For example:

task-defaults:
  description: my description {extra_desc}
  task-context:
    substitution-fields:
      - description

tasks:
  build1:
    task-context:
      from-object:
        extra_desc: build1
  build2:
    task-context:
      from-object:
        extra_desc: build2

This will give build1 and build2 descriptions with their extra_desc included while allowing them to share the rest of their task definition.

Precedence#

If the same key is found in multiple places the order of precedence is as follows: from-parameters, from-object keys, from-file.

That is to say: parameters will always override anything else.

Task Context

Contents