Configuration - Khanh Docs

The Buildkite provider allows you to manage CI/CD pipelines, clusters, teams, and agents in your Buildkite organization.

Provider Configuration#

Required Settings#

Parameter	Description	Environment Variable
`apiToken`	Buildkite API access token	`BUILDKITE_API_TOKEN`
`organization`	Buildkite organization slug	`BUILDKITE_ORGANIZATION_SLUG`

Environment Variables#

export BUILDKITE_API_TOKEN="bkua_your_api_token_here"export BUILDKITE_ORGANIZATION_SLUG="your-org-slug"

Pulumi Configuration#

pulumi config set buildkite:apiToken "bkua_your_api_token_here" --secretpulumi config set buildkite:organization "your-org-slug"

Provider Instance#

import * as pulumi from "@pulumi/pulumi";import * as buildkite from "pulumi-buildkite";const provider = new buildkite.Provider("buildkite-provider", {    apiToken: "bkua_your_api_token_here",    organization: "your-org-slug",});const pipeline = new buildkite.Pipeline("example", {    name: "Example Pipeline",    repository: "https://github.com/myorg/myapp.git",    defaultBranch: "main",    steps: `steps:\n  - command: "echo hello"`,}, { provider });

Getting Your API Token#

Log in to Buildkite
Go to Personal Settings → API Access Tokens
Click New API Access Token
Give it a descriptive name (e.g., "Pulumi Provider")
Select the required scopes:
- read_pipelines and write_pipelines for pipeline management
- read_builds and write_builds for build management
- read_agents for agent information
- read_teams and write_teams for team management
Click Create API Access Token
Copy the token and store it securely

Required Scopes#

Operation	Required Scopes
Manage pipelines	`read_pipelines`, `write_pipelines`
Manage teams	`read_teams`, `write_teams`
Manage agents	`read_agents`
Manage clusters	`read_clusters`, `write_clusters`
Read organization	`read_organizations`
GraphQL API access	`graphql`

Multi-Environment Setup#

import * as pulumi from "@pulumi/pulumi";import * as buildkite from "pulumi-buildkite";const stack = pulumi.getStack();const config = new pulumi.Config("buildkite");// Use stack-specific configurationconst provider = new buildkite.Provider("buildkite", {    apiToken: config.requireSecret("apiToken"),    organization: config.require("organization"),});

Best Practices#

Store Tokens Securely#

# Always use --secret for API tokenspulumi config set buildkite:apiToken "bkua_..." --secret

Use Least Privilege#

Create API tokens with only the scopes needed for your use case. Avoid using tokens with full access when only pipeline management is needed.

Separate Tokens per Environment#

Use different API tokens for different Pulumi stacks to maintain environment isolation:

# Staging stackpulumi stack select stagingpulumi config set buildkite:apiToken "bkua_staging_token" --secret# Production stackpulumi stack select productionpulumi config set buildkite:apiToken "bkua_production_token" --secret