buildkite.star¶

Edit Buildkite pipelines: plugin versions, agent queues and step defaults.

Edits are line-based, so comments, anchors and layout in pipeline files stay as they were. Images used through the docker and docker-compose plugins are image: lines, so docker.bump_image moves them too.

load("@fleet//buildkite.star", "pipelines", "plugins", "bump_plugin", "queues", "set_queue", "set_step_defaults")

Function	What it does
`pipelines`	Lists the repo's pipeline files.
`plugins`	Lists every plugin a pipeline uses, with its version.
`bump_plugin`	Moves a plugin to a new version in every pipeline.
`queues`	Lists the agent queues pipelines target.
`set_queue`	Points `agents: queue:` at a new queue in every pipeline.
`set_step_defaults`	Adds keys, such as `timeout_in_minutes`, to every command step that lacks them.

pipelines¶

pipelines(repo)

Lists the repo's pipeline files.

Arguments

Name	Description
`repo`	The repo passed to `change(repo)`.

Returns: The sorted paths of every YAML file under .buildkite, and of buildkite.yml or buildkite.yaml at the root.

Example

pipelines(repo)
# returns [".buildkite/deploy/pipeline.yaml", ".buildkite/pipeline.yml"]

Before

.buildkite/pipeline.yml

steps: []

.buildkite/deploy/pipeline.yaml

steps: []

ci/other.yml

steps: []

Source

plugins¶

plugins(repo)

Lists every plugin a pipeline uses, with its version.

Arguments

Name	Description
`repo`	The repo passed to `change(repo)`.

Returns: A sorted, de-duplicated list of name#ref strings, such as docker-compose#v4.14.0.

Example

plugins(repo)
# returns ["docker-compose#v4.14.0", "ecr#v2.7.0"]

Before

.buildkite/pipeline.yml

steps:
  - label: test
    plugins:
      - docker-compose#v4.14.0:
          run: app
      - "ecr#v2.7.0":
          login: true

Used in: buildkite-plugin-bump

Source

bump_plugin¶

bump_plugin(repo, plugin, to, from_ref = None)

Moves a plugin to a new version in every pipeline.

The plugin matches as written, such as docker-compose or acme/deploy; a full git URL works too. Plugins pinned to a commit SHA are left alone unless from_ref names it.

Arguments

Name	Description
`repo`	The repo passed to `change(repo)`.
`plugin`	The plugin name as pipelines write it.
`to`	The new version, such as `v5.4.1`.
`from_ref`	When set, only this exact version is replaced.

Returns: The list of paths that changed.

Example

bump_plugin(repo, "docker-compose", "v5.4.1")
# returns [".buildkite/pipeline.yml"]

BeforeAfter

.buildkite/pipeline.yml

steps:
  - label: test
    plugins:
      - docker-compose#v4.14.0:
          run: app

.buildkite/pipeline.yml

steps:
  - label: test
    plugins:
      - docker-compose#v5.4.1:
          run: app

Used in: buildkite-plugin-bump

Source

queues¶

queues(repo)

Lists the agent queues pipelines target.

Arguments

Name	Description
`repo`	The repo passed to `change(repo)`.

Returns: The sorted, de-duplicated queue names.

Example

queues(repo)
# returns ["default", "deploy"]

Before

.buildkite/pipeline.yml

agents:
  queue: default
steps:
  - command: make deploy
    agents: { queue: "deploy" }

Source

set_queue¶

set_queue(repo, queue, from_queue = None)

Points agents: queue: at a new queue in every pipeline.

Covers block (queue: x under agents:) and flow (agents: { queue: x }) forms. Pipelines that set no queue are left alone.

Arguments

Name	Description
`repo`	The repo passed to `change(repo)`.
`queue`	The new queue name.
`from_queue`	When set, only this queue is replaced, so steps on other queues stay where they are.

Returns: The list of paths that changed.

Example

set_queue(repo, "linux-small", from_queue = "default")
# returns [".buildkite/pipeline.yml"]

BeforeAfter

.buildkite/pipeline.yml

agents:
  queue: default  # shared runners
steps:
  - command: make test
  - command: make deploy
    agents: { queue: "deploy" }

.buildkite/pipeline.yml

agents:
  queue: linux-small  # shared runners
steps:
  - command: make test
  - command: make deploy
    agents: { queue: "deploy" }

Used in: buildkite-agents

Source

set_step_defaults¶

set_step_defaults(repo, values)

Adds keys, such as timeout_in_minutes, to every command step that lacks them.

A command step is a list item with a command or commands key, at any depth, so steps inside group steps count. Keys a step already sets are left as they are, so this never overrides a step's choice.

Arguments

Name	Description
`repo`	The repo passed to `change(repo)`.
`values`	A dict of step keys to scalar values, such as `{"timeout_in_minutes": 30}`.

Returns: The list of paths that changed.

Example

set_step_defaults(repo, {"timeout_in_minutes": 20})
# returns [".buildkite/pipeline.yml"]

BeforeAfter

.buildkite/pipeline.yml

steps:
  - label: test
    command: make test
  - label: e2e
    command: make e2e
    timeout_in_minutes: 60
  - wait

.buildkite/pipeline.yml

steps:
  - label: test
    command: make test
    timeout_in_minutes: 20
  - label: e2e
    command: make e2e
    timeout_in_minutes: 60
  - wait

Used in: buildkite-agents

Source