buildkite-agent-release

name	buildkite-agent-release
description	Prepare for a Buildkite Agent Release.

Buildkite Agent Release

When to Use This Skill

Use this skill when you need to:

• Prepare a release for Buildkite Agent.

Instructions

1. Double check the current commit is up to date with latest in main branch.

2. Ask user to decide if this is a minor version bump or patch version bump.

Find the latest Buildkite Agent version using gh: gh release view --repo buildkite/agent --json tagName,publishedAt

Ask user to decide whether it's a minor version bump or patch version bump.

3. Update the agent version file

Edit the version/VERSION to update the value to the new version number. Use the bare semver (e.g. 3.75.0), not a v-prefixed tag (e.g. not v3.75.0).

4. Preview the auto-generated release notes

Generate the same notes GitHub will publish at release time, so they can be reviewed in the PR description:

mkdir -p tmp
gh api -X POST repos/buildkite/agent/releases/generate-notes \
  -f tag_name=v3.75.0 \
  -f target_commitish=main \
  --jq .body > tmp/release-notes.md

This is a read-only API call — it does not create a release or tag. GitHub auto-detects the previous stable release and applies the categorisation from .github/release.yml. The tmp/ directory is gitignored, so the file won't be committed.

Inspect tmp/release-notes.md. If any PRs are mis-categorised (e.g. landed under 🏠 Internal because they had no labels), fix the labels on those PRs and re-run the command.

5. Create the release PR

• Create a new branch for the release (e.g. release/v3.75.0).
• Commit the version/VERSION change.
• Push the branch and open a PR using gh pr create against main:
  • Title: release: v3.75.0 (matching the convention from previous release PRs).
  • Body: contents of tmp/release-notes.md from the previous step.
  • Label: release — required so the PR-labels workflow passes, and so the release PR itself is excluded from its own auto-generated notes (configured in .github/release.yml).
  • Example: gh pr create --title "release: v3.75.0" --body-file tmp/release-notes.md --label release.

The PR body is for human review only; the actual release notes are regenerated by gh release create --generate-notes in .buildkite/steps/github-release.sh when the release pipeline runs, so they will reflect any label fixes made between PR creation and release.

6. Done

• No manual GitHub release editing is required, but the user may want to review the auto-generated notes after the release publishes.