warming

Create a warm, fuzzy feeling on your runners by ensuring caches are prepopulated on launch.

Task configuration

id

• string

A unique identifier for this task.

name

• string
• Default: The task type

A human-readable name used to identify this task. If none is set, then the task type is used.

artifact_paths

• string[]
• Read only

List of paths or glob pattens used to save artifacts resulting from the task run.

info

To prevent the archiving of Workflows system files, a task run never archives anything stored in the /etc/aspect directory.

cci

• cci CircleCIConfiguration
• Optional

Properties relating to CircleCI for the task

env

• Map<string, string>

Environment variables to set on this task. Overrides those set globally

icon

• string
• Default: 'peacock'

The emoji icon used in the tasks label

queue

• string
• Optional

The queue / runner pool that this task runs on. By default, takes the value of the top level 'queue' property in the Workflows configuration.

timeout_in_minutes

• number
• Default: 180

The amount of time in minutes that this step times out after. Timed out steps cause the build to fail.

without

• boolean
• Default: false

Setting this excludes this task from being created when using additional workspace overrides.

bazel

Configuration properties for the bazel invocation for this task.

auto_add_bazelrc_file

• boolean
• Default: true

If true, automatically add the bazelrc file to the invocation when Workflows detects the file next to the configuration file.

If setting this at the root or workspace level, the file is resolved relative to the current workspace.

auto_bazelrc_file

• string
• Default: 'bazelrc'

Name of the default bazelrc file to add to the invocation. This file should be located next to this configuration file, and will be added automatically if it exists, unless auto_add_bazelrc_file is set to false.

bazel_debug_assistance

• boolean
• Default: false

If true, Workflows enables a number of flags and archive extra files that can help debug a number of Bazel issues on CI.

flags

• string[]
• Read only

List of Bazel flags to be applied to each invocation.

Important note for warming tasks:
Do not use --sandbox_debug in the warming task flags configuration.
This will cause some unexpected permissions errors in the course of the warming run.

startup_flags

• string[]
• Read only

List of Bazel startup flags to be applied to each invocation..

rcfiles

• string[]
• Read only

A set of bazelrc files set on each task.

hooks

• Optional

Task hooks allow execution of extra commands or scripts at different points within a task's lifecycle. For example, they can be used for setting up test databases before a test task runs, and then performing cleanup after.

id

• string
• Optional

Identifies a hook uniquely with the configuration. Hooks with the same ID override subsequent definitions of the same hook.

command

• string

Script that should be run when this hook triggers. This can be a single command, or a path to a script.

soft_fail

• boolean
• Default: false

When true, errors from executing the hooks command are ignored, otherwise they are propagated as the tasks exit code.

type

• enum

Type of hook this represents, i.e., when in the lifecycle of a task should this hook execute.

Possible hook types are:

• AFTER_TASK = "after_task": Hook is run after the task runs.
• BEFORE_TASK = "before_task": Hook is run before the task runs.

build

Adds an invocation of a bazel build command.

targets

• string[]
• Read only
• Default = BuildTaskConfiguration.DEFAULT_TARGETS

List of Bazel targets invoked as part of this invocation.

when

• Optional

An optional conditional statement that will be evaluated. When the condition evaluates to a truthy value, then the hook command is executed, otherwise it is skipped.

When no conditions are defined, the command is executed unconditionally.

There must only be one property defined on a single condition, and the terminal must always define an "equals".

Context keys and variables

Conditions can contain placeholders variables, in the form ${VARIABLE}.

Context keys that can be resolved during a conditional expression evaluation. In addition to the values below, the condition has access to environment variables.

WORKFLOWS_TASK_RESULT

The result of the task that ran before the evaluation of the expression.

Can resolve to 'success' or 'error'.

WORKFLOWS_TASK_TYPE

The type of task that the condition is running against.

WORKFLOWS_TASK_ID

The ID of the task the condition is running against.

WORKFLOWS_BRANCH

The branch name that the current build is running on. Is a mirror of the underlying CI hosts env var of the same information.

WORKFLOWS_TAG

The git tag name that the current build is running on, if triggered by a tag. Is a mirror of the underlying CI hosts env var of the same information.

Examples

Condition on the task running being successful

equals:
 - "${WORKFLOWS_TASK_RESULT}"
 - "success"

Condition on a branch name being "main" or "hotfix"

or:
 - equals:
    - "${WORKFLOWS_BRANCH_NAME}"
    - "main"
 - equals:
    - "${WORKFLOWS_BRANCH_NAME}"
    - "hotfix"

Conditions can also be negated

not:
 equals:
   - "${WORKFLOWS_BRANCH_NAME}"
   - "main"

and

If set, the given conditions must all evaluate truthy for this condition to pass.

not

If set, the result of the given condition is negated.

or

If set, at least one of the given conditions must evaluate truthy for this condition to pass.

equals

The main "condition" which will evaluate truthy if both sides of the expression are equal.

note

Types are not considered when evaluating equality, and values are coerced to strings.

lt

• [string,string]
• Optional

A less than condition that evaluates true if the right hand side value is less than the left hand side.

note

Types are not considered when evaluating equality, and values are coerced to numbers.

lte

• [string,string]
• Optional

A less than or equals condition that evaluates true if the right hand side value is less than or equal to the left hand side.

note

Types are not considered when evaluating equality, and values are coerced to numbers.

gt

• [string,string]
• Optional

A greater than condition that evaluates true if the right hand side value is greater than the left hand side.

note

Types are not considered when evaluating equality, and values are coerced to numbers.

gte

• [string,string]
• Optional

A greater than condition that evaluates true if the right hand side value is greater than or equal to the left hand side.

note

Types are not considered when evaluating equality, and values are coerced to numbers.

starts_with

• [string,string]
• Optional

A condition that evaluates true if the left hand side value starts with the right hand side value.

note

This expression does not consider case.

ends_with

• [string,string]
• Optional

A condition that evaluates true if the left hand side value ends with the right hand side value.

note

This expression does not consider case.

contains

• [string, string]

A condition that evaluates true if the left hand side value contains the right hand side value.

is

• string

A condition that evaluates a single value and returns true if the value is considered truthy.

Examples of truthy values:

• true (boolean)
• "string".length > 0
• n > 0

The value may also be a placeholder that will be resolved before evaluation, such as an env var reference or context var.

matches

• [string, string]

A condition accepts a regular expression on the left hand side, and checks if it matches against the right hand side value, in which case it returns true.

always

A condition that when set always evaluates true.

never

A condition that when set never evaluates true.

branches

• [string]

A condition that attempts to match any of the strings against the current branch name.

This de-sugars into a list of matches conditions that are evaluated with an or.

tags

• [string]

A condition that attempts to match any of the strings against the git tag that triggered this build.

This de-sugars into a list of matches conditions that are evaluated with an or.

task

A condition that matches against the current task context. When multiple conditions are set, they are or'd together.

• types: List of task types that are or'd together. The condition will be true if the current task type is contained within this list.

• primary: If true, the conditional evaluates true if the current task type is a primary type. A "primary" task is one of the following types:

  • build
  • buildifier
  • configure
  • delivery
  • format
  • gazelle
  • lint
  • test
  • warming

• secondary: If true, the conditional evaluates true if the current task type is a secondary type. A "secondary" task is one of the following types:

  • checkout
  • bazel_health_probe
  • finalization