{"id":5754,"library":"buildkite-sdk","title":"Buildkite SDK for Python","description":"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#).","status":"active","version":"0.10.0","language":"en","source_language":"en","source_url":"https://github.com/buildkite/buildkite-sdk","tags":["buildkite","ci/cd","pipeline-as-code","dynamic-pipelines","automation"],"install":[{"cmd":"pip install buildkite-sdk","lang":"bash","label":"Using pip"},{"cmd":"uv add buildkite-sdk","lang":"bash","label":"Using uv (preferred for development)"}],"dependencies":[],"imports":[{"symbol":"Pipeline","correct":"from buildkite_sdk import Pipeline"}],"quickstart":{"code":"from buildkite_sdk import Pipeline\nfrom buildkite_sdk.schema import CommandStep\n\n# Create a new pipeline\npipeline = Pipeline()\n\n# Add a simple command step\npipeline.add_step(CommandStep(command=\"echo 'Hello from Buildkite SDK!'\"))\n\n# Add another step with more detail\npipeline.add_step(\n    CommandStep(\n        label=\":python: Run Python Tests\",\n        command=\"pip install -r requirements.txt && pytest\",\n        agents={\n            \"queue\": \"default\"\n        }\n    )\n)\n\n# Output the generated pipeline in YAML format\nprint(pipeline.to_yaml())\n\n# To upload this to Buildkite, you would typically pipe the output:\n# python your_script.py | buildkite-agent pipeline upload","lang":"python","description":"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."},"warnings":[{"fix":"Review the official documentation and changelog for migration guides when upgrading, particularly for changes in pipeline step definitions or schema structures.","message":"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.","severity":"breaking","affected_versions":"All versions, especially major/minor releases where schema changes occur (e.g., v0.4.0 introduced breaking changes related to type generation)."},{"fix":"Ensure you are using the correct library for your task: `buildkite-sdk` for programmatic pipeline definition, `pybuildkite` for API client operations.","message":"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.","severity":"gotcha","affected_versions":"All versions"},{"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.","message":"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.","severity":"gotcha","affected_versions":"All current versions (0.x.x)"},{"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.","message":"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`.","severity":"gotcha","affected_versions":"All versions"}],"env_vars":null,"last_verified":"2026-04-14T00:00:00.000Z","next_check":"2026-07-13T00:00:00.000Z"}