Buildkite SDK for Python

0.10.0 · active · verified Tue Apr 14

The `buildkite-sdk` is an open-source, multi-language Software Development Kit (SDK) that simplifies scripting the generation of pipeline steps for dynamic Buildkite pipelines in native languages like Python. It consumes the Buildkite pipeline schema to provide type-safe programmatic pipeline creation and serialization to YAML or JSON. The current version is 0.10.0 and it maintains a synchronized release cadence across all supported languages (Python, JavaScript/TypeScript, Go, Ruby, C#).

Warnings

breaking As the SDK generates types directly from the Buildkite pipeline schema, major schema changes in Buildkite's platform can introduce breaking changes in the SDK's generated classes and methods. Consult the changelog for specific version upgrade details.
Fix: Review the official documentation and changelog for migration guides when upgrading, particularly for changes in pipeline step definitions or schema structures.
gotcha The `buildkite-sdk` is specifically designed for *generating* Buildkite pipeline YAML or JSON for dynamic pipelines, not for direct interaction with the Buildkite API (e.g., fetching build statuses, creating builds). For direct API interaction, the `pybuildkite` library (a separate project) is typically used.
Fix: Ensure you are using the correct library for your task: `buildkite-sdk` for programmatic pipeline definition, `pybuildkite` for API client operations.
gotcha The Buildkite SDK is currently considered a 'preview' feature. While functional, this status suggests that its API or behavior might be subject to change in future releases, and users are encouraged to report any issues via GitHub.
Fix: Be aware of the preview status and consider locking to specific minor versions to control updates. Actively monitor the GitHub repository and changelog for announcements regarding stability and API changes.
gotcha The generated pipeline YAML/JSON from the `buildkite-sdk` is not directly sent to Buildkite by the SDK itself. It must be uploaded by a `buildkite-agent` running within a Buildkite build. This is typically done by piping the script's output: `python your_script.py | buildkite-agent pipeline upload`.
Fix: Integrate the Python script that uses the SDK into your Buildkite pipeline definition, ensuring its output is piped to `buildkite-agent pipeline upload` within a command step.

Install

pip install buildkite-sdk Using pip
uv add buildkite-sdk Using uv (preferred for development)

Imports

Pipeline
```
from buildkite_sdk import Pipeline
```

Quickstart

This quickstart demonstrates how to create a simple Buildkite pipeline programmatically using the `buildkite-sdk`. It defines two command steps and then prints the resulting pipeline in YAML format. The output can then be uploaded to Buildkite via the `buildkite-agent pipeline upload` command.

from buildkite_sdk import Pipeline
from buildkite_sdk.schema import CommandStep

# Create a new pipeline
pipeline = Pipeline()

# Add a simple command step
pipeline.add_step(CommandStep(command="echo 'Hello from Buildkite SDK!'"))

# Add another step with more detail
pipeline.add_step(
    CommandStep(
        label=":python: Run Python Tests",
        command="pip install -r requirements.txt && pytest",
        agents={
            "queue": "default"
        }
    )
)

# Output the generated pipeline in YAML format
print(pipeline.to_yaml())

# To upload this to Buildkite, you would typically pipe the output:
# python your_script.py | buildkite-agent pipeline upload

view raw JSON →