Metadata

YAML keys for metadata block

The metadata key is intended to be used during the compile phase to signal how to treat the YAML document.

---
# This document is displaying all the available keys
# in their default state for the compile process.
metadata:
  template: false
  clone: true

Keys

KeyRequiredTypeDescription
templateYboolEnables compiling the pipeline as a template.
cloneNboolEnables injecting the default clone process.
render_inlineNboolEnables rendering without explicitly calling within the pipeline.
auto_cancelN(see below)Auto canceling settings for pipelines.

Usage

The template: key

---
metadata:
  # Enables compiling the pipeline as a template. This value
  # is defaulted during the compile phase to "false" if not
  # explicitly provided by the user.
  template: true

The clone: key

---
metadata:
  # Enables injecting the default clone process
  clone: true

The environment: key

---
metadata:
  # By default, the below is populated into every pipeline with
  # services, steps, and secrets. But, when the block exists the
  # configuration specified is used during compile phase.
  environment: [steps, services, secrets]

The render_inline: key

---
metadata:
  # By default, the below is populated into every pipeline with
  # false. But, when set to "true" a user can render a template
  # in the resulting pipeline without referencing it in stages
  # or steps.
  render_inline: false

The auto_cancel key

KeyDefaultTypeDescription
pendingTrueboolPending builds will be auto canceled if qualifying build is triggered
runningFalseboolCurrently running builds will be auto canceled if qualifying build is triggered
default_branchFalseboolPushes to the default branch will also be auto canceled if a qualifying build is triggered.

A qualifying build is defined as either:

  • a push build with the same branch as another running/pending push build
  • a pull request build with the same head ref as another running/pending pull request build

These builds most often happen when a user pushes a commit to a branch and quickly pushes another commit, both of which kick off new builds. Using the auto_cancel block can help free up build space and eliminate pointless builds.

By default, auto canceling is disabled altogether. However, if running or default_branch are specified, pending has a default value of true unless specified otherwise.

---
# pending & running will auto cancel, but not pushes to the default branch.
metadata:
  auto_cancel:
    running: true
---
# running builds will auto cancel even if they are targeting the default branch, but pending builds will not.
metadata:
  auto_cancel:
    pending: false
    default_branch: true
    running: true