buildkite-sdk

A multi-language SDK for Buildkite! 🪁

Consumes the Buildkite pipeline schema and generates and publishes packages for TypeScript or JavaScript, Python, Go, and Ruby.

Installing and using the SDKs

Learn more about how to set up the Buildkite SDK for each langauge, and use it to work with your Buildkite pipelines, from the Buildkite SDK page of the Buildkite Docs.

Upgrading to v0.4.0

In v0.4.0 we introduced type generation from Buildkite's Pipeline Schema. You can find a list of breaking changes here.

Development

Prerequisites

To work on the SDK, you'll need current versions of the following tools:

• Node.js, Python, Go, Ruby
• For Python: uv, Black
• For Ruby: Bundler

See mise.toml for details. (We also recommend Mise for tool-version management.) If you're on a Mac, and you use Homebrew, you can run brew bundle and mise install to get all you need:

brew bundle
mise install

If you hit any rough edges during development, please file an issue. Thanks!

Useful commands

# Install all project dependencies.
npm install

# Test all SDKs and apps.
npm test

# Build all SDKs (and write them to ./dist/sdks).
npm run build

# Build all SDK docs (and write them to ./dist/docs).
npm run docs

# Serve the docs locally (which builds them implicitly).
npm run docs:serve

# Run all apps (which writes JSON and YAML pipelines to ./out).
npm run apps

# Watch all projects for changes (which rebuilds the docs and SDKs and re-runs all apps).
npm run watch

# Launch web servers for all docsets and watch all projects for changes. (Requires reload.)
npm run dev

# Format all SDK code.
npm run format

# Publish the docs to AWS.
npm run docs:publish

# Clear away build and test artifacts.
npm run clean

Regenerating types after a schema change

This SDK generates types from the Buildkite pipeline schema. When changes are made to the pipeline-schema repository, you can regenerate the types by running:

# Regenerate the types for all languages.
npm run types

# Regenerate the types for a specific language.
npm run types-ts
npm run types-py
npm run types-go

The type generator automatically fetches the latest schema from the main branch of the pipeline-schema repository. Generated types are then written to:

• sdk/typescript/src/types/
• sdk/python/src/buildkite_sdk/schema.py
• sdk/go/sdk/buildkite/

Note that the type-generator binary (a Go program at internal/gen/type-gen) is automatically built when you run npm run types. If you need to rebuild that binary manually, run npx nx gen:build.

Upgrading nx

We manage this repository with Nx. To upgrade the Nx workspace to the latest version, use nx migrate. From the root of the project, run:

npx nx migrate latest

See the nx guide for details.

Publishing new versions

Each SDK has its own version and sdk/<language>/v<version> tag. Always use release:create; do not run nx release directly. The local command creates the release commit and tags. Buildkite publishes the packages.

1. Prepare the repository.

   Start from the latest main, then confirm the working tree is clean:

   git switch main
   git pull --ff-only
   git status --short

   The status command must produce no output. release:create refreshes origin/main and the SDK release tags before it starts. Local SDK release tags that were never pushed are discarded. A real release stops unless HEAD matches origin/main, or if a local tag conflicts with the remote.

2. Preview the release and choose a bump.

   Bump	Preview	Create
   Patch	npx nx release:create --dry-run	npx nx release:create
   Minor	npx nx release:create --dry-run --bump=minor	npx nx release:create --bump=minor
   Major	npx nx release:create --dry-run --bump=major	npx nx release:create --bump=major

   The helper selects every SDK changed since its own latest tag. One bump applies to every SDK selected by that run. Confirm the preview lists only the SDKs you intend to release before continuing.

   A change to sdk/<language>/project.json alone is ignored. To make a deliberate packaging release for such a change, add --force to both the preview and create commands.

3. Create the release.

   Run exactly one command from the Create column above, using the same bump you previewed. For every selected SDK, the command:

   • Updates its version file (Go has no version file)
   • Updates its CHANGELOG.md
   • Creates one release commit
   • Creates an sdk/<language>/v<version> tag

   It does not push or publish anything.

4. Review the release commit and tags.

   git show --stat
   git tag --points-at HEAD

   Confirm the commit contains only release changes and that there is one tag for each SDK shown in the preview. If anything is wrong, do not push it. Discard the generated release with git reset --hard origin/main. The next release:create run removes its unpushed SDK tags.

5. Push the commit and tags.

   git push --atomic --follow-tags origin main

   The atomic push prevents release tags from landing if main moved after the release was created.

6. Publish from Buildkite.

   Get the release commit SHA:

   git rev-parse HEAD

   Manually trigger the SDK Release Pipeline against that exact commit. The pipeline refreshes tags from origin, checks each registry first, skips versions already published, and publishes only versions missing from their registry. A publish step turns red instead of publishing if its tag is missing or does not point at the build commit. Other SDKs can continue independently.

7. Create the GitHub Releases.

   After Buildkite succeeds, create one GitHub Release for each SDK published. Select its sdk/<language>/v<version> tag and use that SDK's new CHANGELOG.md entry as the release body.

Version sources

SDK	Version lives in
TypeScript	sdk/typescript/package.json
Python	sdk/python/pyproject.toml
Ruby	sdk/ruby/lib/buildkite/version.rb
C#	sdk/csharp/src/Buildkite.Sdk/Buildkite.Sdk.csproj
Go	the sdk/go/v* git tag, no file

TypeScript uses Nx's built-in npm support. The other four are handled by tools/release/version-actions.ts, wired up per SDK in the release block of nx.json.

Docs

The SDK language docs are managed by a Pulumi Program in infra and manually deployed after every release.

Required environment variables

The local release:create command does not need registry credentials. The Buildkite SDK Release Pipeline supplies these variables when publishing:

• NPM_TOKEN for publishing to npm (with npm publish)
• PYPI_TOKEN for publishing to PyPI (with uv publish)
• GEM_HOST_API_KEY for publishing to RubyGems (with gem push)
• NUGET_API_KEY for publishing to NuGet (with dotnet nuget push)

See each SDK's publish target in sdk/<language>/project.json for details. There is no aggregate publish target: publishing happens only through the release pipeline, one SDK at a time.