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

pipeline = Pipeline()
pipeline.add_step({"command": "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{}

    pipeline.AddStep(buildkite.CommandStep{
        Command: &buildkite.CommandStepCommand{
            String: buildkite.Value("echo 'Hello, world!"),
        },
    })

    // JSON output
    // json, err := pipeline.ToJSON()
    // if err != nil {
    //     log.Fatalf("Failed to serialize JSON: %v", err)
    // }

    // fmt.Println(json)

    // YAML output
    yaml, err := pipeline.ToYAML()
    if err != nil {
        log.Fatalf("Failed to serialize YAML: %v", err)
    }

    fmt.Println(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: 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.

C Sharp

This section explains how to install and use the Buildkite SDK for C# (.NET) projects.

Installing

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

dotnet add package Buildkite.Sdk

Using

The following code example demonstrates how to import the Buildkite SDK into a simple C# script, which then generates a Buildkite pipeline with a build command step, a wait step, and a test command step, and then outputs these steps to either JSON or YAML format:

using Buildkite.Sdk;
using Buildkite.Sdk.Schema;

var pipeline = new Pipeline();

pipeline.AddStep(new CommandStep
{
    Label = ":hammer: Build",
    Command = "dotnet build"
});

pipeline.AddStep(new WaitStep());

pipeline.AddStep(new CommandStep
{
    Label = ":test_tube: Test",
    Command = "dotnet test"
});

// JSON output for `buildkite-agent pipeline upload`
// Console.WriteLine(pipeline.ToJson());
// YAML output for `buildkite-agent pipeline upload`
Console.WriteLine(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: dotnet run --project .buildkite/DynamicPipeline.csproj | buildkite-agent pipeline upload

Also included in this section are examples of how to use the Buildkite SDK for C# with other step types, including a more complex command step, a block step, wait step, trigger step, and group step, as well as environment variables.

Command steps

This code example demonstrates a more complex command step with additional options:

pipeline.AddStep(new CommandStep
{
    Label = ":dotnet: Build",
    Key = "build",
    Command = "dotnet build --configuration Release",
    Agents = new AgentsObject { ["queue"] = "linux" },
    TimeoutInMinutes = 30
});

Block steps

This code example demonstrates how to implement a block step:

pipeline.AddStep(new BlockStep
{
    Block = ":rocket: Deploy to Production?",
    Prompt = "Are you sure?"
});

Wait steps

This code example demonstrates how to implement a wait step:

pipeline.AddStep(new WaitStep());
pipeline.AddStep(new WaitStep { ContinueOnFailure = true });

Trigger steps

This code example demonstrates how to implement a trigger step:

pipeline.AddStep(new TriggerStep
{
    Trigger = "deploy-pipeline",
    Build = new TriggerBuild { Branch = "main" }
});

Group steps

This code example demonstrates how to implement a group step:

pipeline.AddStep(new GroupStep
{
    Group = ":test_tube: Tests",
    Steps = new List<IGroupStep>
    {
        new CommandStep { Label = "Unit", Command = "dotnet test" },
        new CommandStep { Label = "Integration", Command = "dotnet test --filter Integration" }
    }
});

Environment variables

This code example demonstrates how to access environment variables:

using Buildkite.Sdk;

var branch = EnvironmentVariable.Branch;
var commit = EnvironmentVariable.Commit;
var buildNumber = EnvironmentVariable.BuildNumber;

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.