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.

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.

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!

# 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 to npm, PyPi pkg.go.dev, and RubyGems.
npm run publish

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

# Clear away build and test artifacts.
npm run clean

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.

All SDKs version on the same cadence. To publish a new version (of all SDKs), follow these steps:

1. Commit all pending changes. We want the release commit to be "clean" (i.e., to consist only of changes related to the release itself.)

2. Update the VERSION_FROM and VERSION_TO values in the release:all task in ./project.json.

3. Leaving that single change uncommitted, make sure you've exported a GitHub access token (as GITHUB_TOKEN -- see below) with push access to main branch of the repository, then run the release script:

   npm run release

   This script:

   • Updates the version numbers in all affected files
   • Rebuilds all SDKs
   • Commits all changes (e.g., to version files, lockfiles, and anything else under ./sdk)
   • Adds two new tags to mark the release (v0.0.0 and sdk/go/v0.0.0)
   • Pushes the commit and tags to GitHub, triggering the publish task
   • Creates a new GitHub release

   If for some reason the Buildkite publish job doesn't finish successfully, you can run some or all publish tasks from your local machine by exporting the applicable environment variables (again, see below), then running:

   npm run clean
   npm run build
   npm run publish                # To publish all packages
   npx nx publish sdk/typescript  # To publish only the Node.js package
   npx nx publish sdk/python      # To publish only the Python package
   npx nx publish sdk/go          # To publish only the Go package
   npx nx publish sdk/ruby        # To publish only the Ruby package

4. Once the publish job completes, verify the releases at their respective URLs:

   • https://github.com/buildkite/buildkite-sdk/releases
   • https://www.npmjs.com/package/@buildkite/buildkite-sdk
   • https://pypi.org/project/buildkite-sdk/
   • https://pkg.go.dev/github.com/buildkite/buildkite-sdk/sdk/go (this usually takes a minute or two)
   • https://rubygems.org/gems/buildkite-sdk

The following environment variables are required for releasing and publishing:

• GITHUB_TOKEN for creating GitHub releases (with @octokit/rest)
• NPM_TOKEN for publishing to npm (with npm publish)
• PYPI_TOKEN fror publishing to PyPI (with uv publish)
• GEM_HOST_API_KEY for publishing to RubyGems (with gem push)

See the publish:all and release:all tasks in ./project.json for details.