https://github.com/buildkite/buildkite-sdk
A multi-language SDK for Buildkite! 🪁 Available in JavaScript, TypeScript, Python, Go, and Ruby.
https://github.com/buildkite/buildkite-sdk
buildkite cicd
Last synced: about 1 month ago
JSON representation
A multi-language SDK for Buildkite! 🪁 Available in JavaScript, TypeScript, Python, Go, and Ruby.
- Host: GitHub
- URL: https://github.com/buildkite/buildkite-sdk
- Owner: buildkite
- License: mit
- Created: 2024-10-11T23:19:12.000Z (8 months ago)
- Default Branch: main
- Last Pushed: 2025-05-05T16:00:05.000Z (about 1 month ago)
- Last Synced: 2025-05-05T17:25:28.724Z (about 1 month ago)
- Topics: buildkite, cicd
- Language: Python
- Homepage: https://buildkite.com/docs
- Size: 323 KB
- Stars: 19
- Watchers: 14
- Forks: 4
- Open Issues: 4
-
Metadata Files:
- Readme: README.md
- License: LICENSE
Awesome Lists containing this project
README
# buildkite-sdk
[](https://buildkite.com/buildkite/pipeline-sdk)
A multi-language SDK for [Buildkite](https://buildkite.com)! 🪁
Consumes the [Buildkite pipeline schema](https://github.com/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](http://buildkite.com/docs/pipelines/configure/dynamic-pipelines/sdk) page of the Buildkite Docs.
## Development
### Prerequisites
To work on the SDK, you'll need current versions of the following tools:
- [Node.js](https://nodejs.org/en/download), [Python](https://www.python.org/downloads/), [Go](https://go.dev/doc/install), [Ruby](https://www.ruby-lang.org/en/documentation/installation/)
- For Python: [uv](https://docs.astral.sh/uv/), [Black](https://black.readthedocs.io/en/stable/)
- For Ruby: [Bundler](https://bundler.io/)
See `mise.toml` for details. (We also recommend [Mise](https://mise.jdx.dev/) for tool-version management.) If you're on a Mac, and you use [Homebrew](https://brew.sh/), you can run `brew bundle` and `mise install` to get all you need:
```bash
brew bundle
mise install
```
If you hit any rough edges during development, please file an issue. Thanks!
### Useful commands
```bash
# 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
```
### Upgrading nx
We manage this repository with [Nx](https://nx.dev/). To upgrade the Nx workspace to the latest version, use `nx migrate`. From the root of the project, run:
```bash
npx nx migrate latest
```
See the [nx guide](https://nx.dev/features/automate-updating-dependencies) for details.
## Publishing new versions
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.)
1. Update the `VERSION_FROM` and `VERSION_TO` values in the `release:all` task in [`./project.json`](./project.json).
1. 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:
```bash
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:
```bash
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
```
1. 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
### Required environment variables
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.