Skip to main content
Version: 5.11.x

Configuration for Workflows

The root Workflows configuration.

Global Bazel configuration​

These properties apply to each Bazel based task. You can override them at the task or workspace level as required.

note

If Bazel rc files are listed here, they are applied to each workspace with a relative path, therefore they must be available in each workspace referenced.

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.

env​

  • Map <string, string>

A set of environment variables for each task. Can be overridden at the task level.

Global hooks configuration​

List of hooks that apply to all primary tasks by default. This list is combined with a list provided at the workspace and task level. Hooks are run sequentially, starting with hooks at the root level.

If an id is supplied for a hook, you can override it at the workspace and task level.

tip

To avoid repeating hooks, use YAML anchors (&) and aliases (*), for example:

tasks:
  - test:
      targets:
        - ...
      hooks: &hooks
        - type: before_task
          ...
  - warming:
      hooks: *hooks

A hook definition can take a when condition to allow for applying hooks to a particular task type, or the use of other conditional expressions. If you supply a custom when condition on a hook at the root level, the default behavior of running only on primary task types is dropped, and must be supplied on the custom condition.

For example, to run a hook on all primary tasks on the main branch:

hooks:
    - type: before_task
      command: docker login
      when:
        and:
          - task:
              primary: true
          - branches
              - main

If you don't supply a custom condition, the hook runs on all primary task types. A primary task is one of the following types:

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

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.

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

notifications​

  • Optional

The notifications issued on build pass/fail events. Suports Slack and GitHub annotations.

slack​

Enable Slack notifications.

caution

Only supported with CircleCI.

Sets up CircleCI's Slack notifications feature to send notifications on a build failure.

  • branches

    • string[]
    • Default: ['^main$', '^master$']

    A list of expressions used to determine if the branch being built should have notifications set for it. Treated as a regular expression, and wrapped with ^ and $ if required.

  • cci

  • channel

    • optional
    • string

    The channel that the notification should be sent to.

github​

Configures GitHub PR comment notifications to be sent with build status updates.

  • label

    • optional
    • string

    An optional label to include in GitHub PR comments. Useful to differentiate PR comments when you have different Workflows deployments building the same PR.

show_aspect_cli_commands​

  • optional
  • boolean
  • Default: true

When true, the comment may contain reproduction or fix commands specific to the Aspect CLI.

annotations​

  • optional
  • boolean
  • Default: true

When true, annotations will be added to GitHub pull requests.

suggestions​

  • optional
  • boolean
  • Default: true

When true, suggestions will be added to GitHub pull requests.

telemetry​

  • boolean
  • Default: false

Connection properties for the telemetry system. If set to false, build telemetry is disabled.

note

Workflows 5.10 and older named this property observability.

Configuration for telemetry:

  • branches

    • string[]

    • Default: ['^main$', '^master$']

      List of branches that metrics are explicitly tracked for. While build data is collected for all builds, Workflows only labels branches listed here.

      Treated as a regular expression and wrapped with ^ and $ if required.

  • metrics -boolean

    • Default: true

      Enable capture of metrics via Otel.

      note

      Added in Workflows 5.11.

  • traces

    • boolean

    • Default: true

      Enable capture of traces via Otel.

      note

      Added in Workflows 5.11.

tasks​

  • map: <string, TaskConfiguration>
  • Read only

Map of tasks that should be enabled for this workspace. By default, the tasks inherited from the root workspace, so it is not required to list them twice. Tasks listed here have their configuration merged with the root.

warming​

  • Optional
  • Deprecated

Enables warming for all workspaces.

Set options directly on the WarmingTaskConfiguration in the tasks map.

workspaces​

  • Map<string, WorkspaceConfiguration>

Map of nested workspaces to create additional tasks for. For example, if a nested Bazel workspace exists at examples/service within the repository, you could use the following configuration to create additional tasks.

Example​

workspaces:
    - examples/service
tasks:
    - test:

This property accepts both a list of workspace paths, or a map where the key is the workspace path, and the value is additional workspace options via WorkspaceConfiguration.

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.

Last updated on by Chris Chinchilla