Buildkite SDK

JavaScript and TypeScript (Node.js)

This section explains how to install and use the Buildkite SDK for JavaScript and TypeScript (Node.js-based) projects.

Installing

To install the Buildkite SDK for Node.js to your local development environment, run this command:

npm install @buildkite/buildkite-sdk

Using

The following code example demonstrates how to import the Buildkite SDK into a simple TypeScript script, which then generates a Buildkite Pipelines step for a simple command step that runs echo 'Hello, world!', and then outputs this step to either JSON or YAML format:

const { Pipeline } = require("@buildkite/buildkite-sdk");

const pipeline = new Pipeline();

pipeline.addStep({
    command: "echo 'Hello, world!'",
});

// JSON output
// console.log(pipeline.toJSON());
// YAML output
console.log(pipeline.toYAML());

When you're ready to upload your output JSON or YAML steps to Buildkite Pipelines, you can do so from a currently running pipeline step:

# For example, in your pipeline's Settings > Steps, and with ts-node installed to your agent:
steps:
  - label: ":pipeline: Run dynamic pipeline steps"
    command: ts-node .buildkite/dynamicPipeline.ts | buildkite-agent pipeline upload

API documentation

For more detailed API documentation on the Buildkite SDK for TypeScript, consult the Buildkite SDK's TypeScript API documentation.

Python

This section explains how to install and use the Buildkite SDK for Python projects.

Installing

To install the Buildkite SDK for Python (with uv) to your local development environment, run this command:

uv add buildkite-sdk

Using

The following code example demonstrates how to import the Buildkite SDK into a simple Python script, which then generates a Buildkite Pipelines step for a simple simple command step that runs echo 'Hello, world!', and then outputs this step to either JSON or YAML format:

from buildkite_sdk import Pipeline, CommandStep

pipeline = Pipeline()
pipeline.add_step(CommandStep(
    commands="echo 'Hello, world!'"
))

# JSON output
# print(pipeline.to_json())
# YAML output
print(pipeline.to_yaml())

When you're ready to upload your output JSON or YAML steps to Buildkite Pipelines, you can do so from a currently running pipeline step:

# For example, in your pipeline's Settings > Steps:
steps:
  - label: ":pipeline: Run dynamic pipeline steps"
    command: python3 .buildkite/dynamic_pipeline.py | buildkite-agent pipeline upload

API documentation

For more detailed API documentation on the Buildkite SDK for Python, consult the Buildkite SDK's Python API documentation.

Go

This section explains how to install and use the Buildkite SDK for Go projects.

Installing

To install the Buildkite SDK for Go to your local development environment, run this command:

go get github.com/buildkite/buildkite-sdk/sdk/go

Using

The following code example demonstrates how to import the Buildkite SDK into a simple Go script, which then generates a Buildkite Pipelines step for a simple command step that runs echo 'Hello, world!', and then outputs this step to either JSON or YAML format:

package main

import (
    "fmt"
    "github.com/buildkite/buildkite-sdk/sdk/go/sdk/buildkite"
)

func main() {
    pipeline := buildkite.Pipeline{}
    command := "echo 'Hello, world!"

    pipeline.AddCommandStep(buildkite.CommandStep{
        Command: &buildkite.CommandUnion{
            String: &command,
        },
    })

    // JSON output
    // fmt.Println(pipeline.ToJSON())
    // YAML output
    fmt.Println(pipeline.ToYAML())
}

When you're ready to upload your output JSON or YAML steps to Buildkite Pipelines, you can do so from a currently running pipeline step:

# For example, in your pipeline's Settings > Steps:
steps:
  - label: ":pipeline: Run dynamic pipeline steps"
    command: go run .buildkite/dynamic_pipeline.go | buildkite-agent pipeline upload

API documentation

For more detailed API documentation on the Buildkite SDK for Go, consult the Buildkite SDK's Go API documentation.

Ruby

This section explains how to install and use the Buildkite SDK for Ruby projects.

Installing

To install the Buildkite SDK for Ruby to your local development environment, run this command:

gem install buildkite-sdk

Using

The following code example demonstrates how to import the Buildkite SDK into a simple Ruby script, which then generates a Buildkite Pipelines step for a simple command step that runs echo 'Hello, world!', along with a label attribute, and then outputs this step to either JSON or YAML format:

require "buildkite"

pipeline = Buildkite::Pipeline.new

pipeline.add_step(
  label: "some-label",
  command: "echo 'Hello, World!'"
)

# JSON output
# puts pipeline.to_json
# YAML output
puts pipeline.to_yaml

When you're ready to upload your output JSON or YAML steps to Buildkite Pipelines, you can do so from a currently running pipeline step:

# For example, in your pipeline's Settings > Steps:
steps:
  - label: ":pipeline: Run dynamic pipeline steps"
    command: ruby .buildkite/dynamic_pipeline.rb | buildkite-agent pipeline upload

API documentation

For more detailed API documentation on the Buildkite SDK for Ruby, consult the Buildkite SDK's Ruby API documentation.

Developing the Buildkite SDK

Since the Buildkite SDK is open source, you can make your own contributions to this SDK. Learn more about how to do this from the Buildkite SDK's README.