buildkite-agent-runtime

What this skill does

# Buildkite Agent Runtime

The `buildkite-agent` binary provides subcommands for interacting with Buildkite from within running job steps — creating annotations, uploading artifacts, sharing state between jobs, generating dynamic pipelines, requesting OIDC tokens, and more. This skill covers the command syntax, flags, and patterns for every in-job subcommand.

## Quick Start

A step that runs tests, annotates failures, uploads coverage, and stores a result flag for downstream jobs:

```yaml
steps:
  - label: ":test_tube: Tests"
    command: |
      if ! make test 2>&1 | tee test-output.txt; then
        buildkite-agent annotate --style "error" --context "test-failures" < test-output.txt
        buildkite-agent meta-data set "tests-passed" "false"
        exit 1
      fi
      buildkite-agent annotate "All tests passed :white_check_mark:" --style "success" --context "test-results"
      buildkite-agent artifact upload "coverage/**/*"
      buildkite-agent meta-data set "tests-passed" "true"
```

A downstream step reading that state:

```yaml
  - label: ":rocket: Deploy"
    command: |
      PASSED=$(buildkite-agent meta-data get "tests-passed")
      if [[ "$PASSED" != "true" ]]; then
        echo "Tests did not pass, skipping deploy"
        exit 0
      fi
      scripts/deploy.sh
    depends_on: "test-step"
```

## Annotations

Surface build results directly on the build page. Annotations support Markdown and HTML.

### Creating annotations

```bash
# Simple text annotation
buildkite-agent annotate "Deploy completed successfully" --style "success" --context "deploy"

# Pipe from a file
buildkite-agent annotate --style "error" --context "test-failures" < test-output.md
```

### Key flags

| Flag | Short | Default | Description |
|------|-------|---------|-------------|
| `--style` | `-s` | `default` | Visual style: `default`, `info`, `warning`, `error`, `success` |
| `--context` | `-c` | random UUID | Unique ID — reusing a context replaces the annotation |
| `--append` | — | `false` | Append to existing annotation with same context instead of replacing |
| `--priority` | — | `3` | Display priority (1-10). Higher numbers appear first |
| `--job` | — | current job | Job ID to annotate (rarely needed) |

### Replacing vs appending

- **Same `--context` without `--append`** replaces the annotation; **with `--append`** appends below existing content.
- Always use a stable `--context` value so reruns update the same annotation instead of creating duplicates.

> For pipeline-level `notify:` configuration, see the **buildkite-pipelines** skill.

## Artifacts

Upload files as build artifacts, download them in later steps or other builds, and search by glob.

### Upload

```bash
# Upload a single file
buildkite-agent artifact upload "pkg/release.tar.gz"

# Upload with glob pattern
buildkite-agent artifact upload "dist/**/*"
```

### Download

```bash
# Download to current directory
buildkite-agent artifact download "pkg/release.tar.gz" .

# Download from a specific step
buildkite-agent artifact download "dist/*" . --step "build-step"
```

### Search

```bash
# List matching artifacts
buildkite-agent artifact search "pkg/*.tar.gz" --build "$BUILDKITE_BUILD_ID"
```

For complete flag tables, see `references/flag-reference.md`.

> For the declarative `artifact_paths:` YAML key, see the **buildkite-pipelines** skill. For `bk artifact` CLI commands, see the **buildkite-cli** skill.

## Meta-data

A build-wide key-value store for sharing state between jobs. Set a value in one job, read it in any other job in the same build.

### Set

```bash
buildkite-agent meta-data set "release-version" "1.4.2"
```

### Get

```bash
VERSION=$(buildkite-agent meta-data get "release-version")
```

Use `--default` to return a fallback value instead of a non-zero exit when the key is missing: `buildkite-agent meta-data get "deploy-env" --default "staging"`.

### Check existence

```bash
# Returns exit code 0 if exists, 100 if not
if buildkite-agent meta-data exists "release-version"; then
  echo "Version already set"
fi
```

### Common patterns

**Block step field values** are stored automatically as meta-data. Retrieve them by field key:

```bash
# After a block step with fields: [{key: "release-name", text: "Release Name"}]
RELEASE_NAME=$(buildkite-agent meta-data get "release-name")
```

## Pipeline Upload

Dynamically add steps to a running build. The core mechanism behind dynamic pipelines — generate YAML at runtime and upload it.

### Basic usage

```bash
# Upload a specific file
buildkite-agent pipeline upload .buildkite/deploy-steps.yml

# Pipe generated YAML from stdin
./scripts/generate-pipeline.sh | buildkite-agent pipeline upload
```

### Replace mode

By default, uploaded steps are **appended** after the current step. Use `--replace` to replace the entire remaining pipeline:

```bash
# Replace all remaining steps with the uploaded ones
buildkite-agent pipeline upload --replace .buildkite/new-pipeline.yml
```

### Key flags

| Flag | Default | Description |
|------|---------|-------------|
| `--replace` | `false` | Replace remaining pipeline steps instead of appending |
| `--no-interpolation` | `false` | Skip environment variable interpolation in the uploaded YAML |
| `--dry-run` | `false` | Validate and output the pipeline without uploading |

> For pipeline YAML syntax and step types, see the **buildkite-pipelines** skill.

## OIDC Tokens

Request short-lived OpenID Connect tokens from within a job step for authenticating to external services (cloud providers, package registries) without static credentials.

### Basic token request

```bash
# Request a token for a specific audience
TOKEN=$(buildkite-agent oidc request-token --audience "https://packages.buildkite.com/my-org/my-registry")
```

### Cloud provider authentication

```bash
# AWS — request token with STS audience
TOKEN=$(buildkite-agent oidc request-token --audience "sts.amazonaws.com")
```

### Key flags

| Flag | Default | Description |
|------|---------|-------------|
| `--audience` | Buildkite endpoint | Target service URL — must match the OIDC provider audience configuration |
| `--lifetime` | `600` | Token lifetime in seconds |
| `--claim` | — | Comma-separated optional claims to include (e.g., `organization_id,pipeline_id`) |
| `--aws-session-tag` | — | Comma-separated claims to map as AWS session tags |

> For end-to-end OIDC auth flows, cloud provider setup, and token claim details, see the **buildkite-secure-delivery** skill.

## Step Management

Read or modify step attributes at runtime. Useful for conditional logic within steps and build automation.

### Get step attributes

```bash
# Get current step's label
LABEL=$(buildkite-agent step get "label")

# Get another step's attribute by key
STATE=$(buildkite-agent step get "state" --step "deploy-step")

# Get the outcome of a step
OUTCOME=$(buildkite-agent step get "outcome" --step "test-step")
```

### Update step attributes

```bash
# Update current step's label dynamically
buildkite-agent step update "label" ":rocket: Deploying v${VERSION}"

# Update another step
buildkite-agent step update "label" ":hourglass: Waiting..." --step "pending-step"
```

### Cancel a step

```bash
# Cancel a specific step by key
buildkite-agent step cancel --step "optional-step"
```

### Key flags

| Flag | Default | Description |
|------|---------|-------------|
| `--step` | current step | Step key or UUID to target |
| `--build` | current build | Build UUID (for cross-build operations) |
| `--format` | `string` | Output format for `get` |

### Available step attributes

| Attribute | Readable | Writable | Description |
|-----------|----------|----------|-------------|
| `label` | yes | yes | Step label displayed in UI |
| `state` | yes | no | Current state (`running`, `passed`, `failed`, etc.) |
| `outcome` | yes | no | Final outcome of the step |
| `key` | yes | no | Step key identifier |

## Distributed Locks

Coordinate parallel jobs within a build using distrib