Terraform provider

The Buildkite provider for Terraform lets you manage your Buildkite organization's resources using Terraform infrastructure-as-code workflows. With this provider, you can define and version-control your pipelines, teams, clusters, and other Buildkite resources alongside your application infrastructure.

The Buildkite Terraform Provider is open source repository available on GitHub, is listed on the Terraform Registry, and supports Terraform 1.0 and later.

Managed resources

Once you have met the prerequisites (see Before you start) and have defined the Buildkite provider for your Terraform configuration, you can then use the Buildkite Terraform provider for the following supported resource types:

Pipelines: Create and configure pipelines, including their steps in a pipeline template, repository settings, repository webhooks (for GitHub or other repository providers), team access, and schedules. See Getting started with managing pipelines for more information.
Clusters and queues: Manage clusters, queues, agent tokens, default queues, cluster maintainers, and Buildkite secrets. See Manage clusters and queues for more information.
Teams: Create and manage teams and their members. See Manage teams for more information.
Organizations: Configure organization-level settings (such as two-factor authentication and restricting API access by IP address), and system banners. See Manage Buildkite organizations for more information.
Test suites: Set up Test Engine test suites and manage team access. See the buildkite_test_suite and buildkite_test_suite_team resources in the Terraform provider docs for details.
Package registries: Manage Package Registries resources. See the buildkite_registry resource in the Terraform provider docs for details.

Before you start

The Terraform provider requires the following Buildkite configuration values:

API access token: A Buildkite API access token (BUILDKITE_API_TOKEN) with write_pipelines and read_pipelines REST API scopes and GraphQL API access enabled. You can generate a token from your API Access Tokens page.

Note: You can also add the write_suites REST API scope to this token, although this is only required if you plan to manage Buildkite Test Engine test suites using the Terraform provider.
Buildkite organization slug: Your Buildkite organization slug, which you can find in your Buildkite URL: https://buildkite.com/<your-buildkite-org-slug>.

Define the Buildkite provider for your Terraform configuration

To start using the Buildkite Terraform provider to manage your pipelines in Terraform:

Define the Buildkite provider for your Terraform configuration, along with your Buildkite API access token configuration, as a file written in HashiCorp Configuration Language (HCL) (for example, provider.tf):
```
terraform {
  required_providers {
    buildkite = {
      source  = "buildkite/buildkite"
      version = "~> 1.0"
    }
  }
}

provider "buildkite" {
  api_token    = "BUILDKITE_API_TOKEN"
  organization = "your-buildkite-org-slug"
}
```
Warning: Avoid storing your Buildkite API access token directly in Terraform configuration files. Use an environment variable for BUILDKITE_API_TOKEN or manage it through a secrets manager instead, which is the recommended approach if you're using a Buildkite pipeline to orchestrate this process.

If you're running this process at the command line, and you wish to use your Terraform configuration to temporarily store your token's value for this procedure, you can do so by creating the following files, although ensure you delete them at the end of this procedure:
1. Configure the following additional HCL configuration file to define a variable for your API access token (for example, variables.tf):
```
variable "buildkite_api_token" {
  type      = string
  sensitive = true
}
```
2. Create the Terraform variable file to hold your API access token value (terraform.tfvars):
```
buildkite_api_token = "your-api-access-token-value"
```
3. Change the value of BUILDKITE_API_TOKEN to var.buildkite_api_token in your provider.tf file.
Initialize the provider:
```
terraform init
```

Next steps

You can now proceed to start managing your pipelines in Terraform.

You can also start managing your clusters and queues, teams and Buildkite organization's settings in Terraform too.

Further reference

For the full list of supported resources, data sources, and their configuration options, see the Buildkite provider documentation on the Terraform Registry.