Buildkite Resource Provider

The Buildkite Resource Provider lets you manage Buildkite resources.

The provider is built on https://github.com/buildkite/terraform-provider-buildkite.

Installing

[!IMPORTANT] The provider version v2.3.1 was built on the Terraform provider v0.25.1 which was a pre-release version. From v3.0.0 onwards this provider is compatible with the Terraform provider v1.x.x. Please note that backwards compatibility might not be given.

This package is available in many languages in the standard packaging formats.

Node.js (JavaScript/TypeScript)

To use from JavaScript or TypeScript in Node.js, install using either npm:

npm install @pulumiverse/buildkite

or yarn:

yarn add @pulumiverse/buildkite

Python

To use from Python, install using pip:

pip install pulumiverse-buildkite

Go

To use from Go, use go get to grab the latest version of the library:

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

.NET

To use from .NET, install using dotnet add package:

dotnet add package Pulumiverse.Buildkite

Java

To use from Java, add the following dependency to your project.

With Maven:

<dependency>
    <groupId>com.pulumiverse</groupId>
    <artifactId>buildkite</artifactId>
    <version>${VERSION}</version>
</dependency>

With Gradle:

implementation("com.pulumiverse:buildkite:${VERSION}")

Migrating from v2 to v3

v3.0.0 is a major upgrade that moves from the pre-release Terraform provider v0.25.x (used by v2.3.1 and earlier) to the stable Terraform provider v1.x. This changes the schema of the buildkite:Pipeline/pipeline:Pipeline resource, so upgrading an existing stack requires a one-time manual edit of the stack state. There is currently no automatic state mapper — see issue #118.

Symptom

After bumping the provider package to v3.x, the first pulumi preview/pulumi up fails while trying to read the previously saved state:

error: Unable to Read Previously Saved State for UpgradeResourceState: There was an error reading the saved resource state using the prior resource schema defined for version 0 upgrade.

Please report this to the provider developer:

AttributeName("provider_settings"): invalid JSON, expected "[", got "{"

Cause

The underlying Terraform provider changed the shape of provider_settings on the pipeline resource. In v2 (Terraform provider v0.25.x) it was modelled as an array ([]*providerSettingsModel); in v3 (Terraform provider v1.x) it is a single object (*providerSettingsModel). State written by v2 therefore cannot be read by v3 without adjustment. See also buildkite/terraform-provider-buildkite#501.

Migration steps

[!IMPORTANT] The version numbers and URNs shown below are placeholders. Substitute your actual source version and the v3 version you are upgrading to (the latest release is recommended). Back up the exported state file before editing so you can roll back if needed.

1. Upgrade the provider package for your language to v3.x (see Installing above).

2. Export the stack state to a file:

   pulumi stack export -s <stackName> > stateFile.json
   

3. Edit stateFile.json:

   a. Bump the provider version. Find the pulumi:providers:buildkite resource and update the version string from your 2.x.x version to the 3.x.x version you are upgrading to. The version appears in three places for this resource: the urn, inputs.version, and outputs.version. Leave the id (GUID) unchanged. This stops Pulumi from trying to load the now-uninstalled v2 plugin to read the old state.

   Before:

   {
       "urn": "urn:pulumi:<stack>::<project>::pulumi:providers:buildkite::default_2_2_0_...",
       "custom": true,
       "id": "4c1a2d5b-b292-4eec-ac4a-d4d08cd75be6",
       "type": "pulumi:providers:buildkite",
       "inputs": { "pluginDownloadURL": "...", "version": "2.2.0" },
       "outputs": { "pluginDownloadURL": "...", "version": "2.2.0" }
   }
   

   After (using the latest release as the target):

   {
       "urn": "urn:pulumi:<stack>::<project>::pulumi:providers:buildkite::default_3_4_0_...",
       "custom": true,
       "id": "4c1a2d5b-b292-4eec-ac4a-d4d08cd75be6",
       "type": "pulumi:providers:buildkite",
       "inputs": { "pluginDownloadURL": "...", "version": "3.4.0" },
       "outputs": { "pluginDownloadURL": "...", "version": "3.4.0" }
   }
   

   b. Fix providerSettings on every buildkite:Pipeline/pipeline:Pipeline resource. Replace the v2 array-style value with the equivalent v3 object.

   For a pipeline with no custom provider settings, the v2 state contains the default-tracking marker {"__defaults": []}; replace it with an empty object:

   {
       "urn": "urn:pulumi:<stack>::<project>::buildkite:Pipeline/pipeline:Pipeline::NAME_HERE",
       "type": "buildkite:Pipeline/pipeline:Pipeline",
       "inputs": {
           "providerSettings": {}
       }
   }
   

   [!NOTE] If a pipeline does configure provider settings (e.g. GitHub/GitLab options), its providerSettings will not be {"__defaults": []} — it will hold real keys. In that case keep those keys and only remove the stray __defaults entries so the value is a plain object matching the v3 schema, rather than blanking it to {}.

4. Re-import the edited state:

   pulumi stack import -s <stackName> --file stateFile.json
   

5. Run pulumi preview to confirm the state loads cleanly, then pulumi up as usual.

[!NOTE] There were additional breaking changes upstream (for example around teams), so you may see other diffs when moving to v3. Review your pulumi preview output carefully before applying.

Configuration

The following configuration points are available for the buildkite provider:

• buildkite:apiToken (required, environment: BUILDKITE_API_TOKEN) - A Buildkite API Access Token. Must have GraphQL access, as well as the write_pipelines, read_pipelines and write_suites scopes.
• buildkite:organization (required, environment: BUILDKITE_ORGANIZATION_SLUG) - The Buildkite organization slug.
• buildkite:graphqlUrl (optional, environment: BUILDKITE_GRAPHQL_URL) - The Buildkite GraphQL URL.
• buildkite:restUrl (optional, environment: BUILDKITE_REST_URL) - The Buildkite REST URL.

[!NOTE] The configuration keys are camelCase, e.g. buildkite:apiToken, not the snake_case names used by the underlying Terraform provider. Pulumi silently ignores unknown configuration keys, so setting buildkite:api_token results in requests being sent without a token and failing with 401 Unauthorized.

For example, to set the API token as a secret:

pulumi config set --secret buildkite:apiToken <your-token>

Example

Example for Typescript to create a resource:

import * as buildkite from '@pulumiverse/buildkite';

const args = {};
const vm = new buildkite.agent.AgentToken(
  'token',
  args,
);

Reference

For detailed reference documentation, please visit the upstream Terraform provider's documentation at: https://registry.terraform.io/providers/buildkite/buildkite/latest

Contributors

Thanks goes to these wonderful people (emoji key):

Daniel Mühlbachler-Pietrzykowski 🚧 💻 📖

Christopher Maier 💻 📖

Susan Evans 📖

Paul Stack 📖

This project follows the all-contributors specification. Contributions of any kind welcome!