Buildkite

https://buildkite.com/docs
Admin
Buildkite is a CI/CD platform designed for fast, scalable, and flexible software development. It...
Tokens:1,175,546
Snippets:6,081
Trust Score:10
Update:1 year ago
Show doc for...
Tokens:
Raw
### Clone Node.js Example Package Project using Git

Source: https://buildkite.com/docs/package-registries/getting-started

Clones the 'nodejs-example-package' repository from GitHub to your local machine. This requires Git to be installed and accessible in your terminal.

```bash
git clone git@github.com:buildkite/nodejs-example-package.git
```

--------------------------------

### Run Node.js Example Package Locally using npm

Source: https://buildkite.com/docs/package-registries/getting-started

Executes the main script of the Node.js example package using npm. This command assumes you are inside the cloned 'nodejs-example-package' directory and have Node.js and npm installed.

```bash
npm run main
```

--------------------------------

### Install RSpec Testing Framework

Source: https://buildkite.com/docs/test-engine/getting-started

Installs the RSpec testing framework for Ruby projects. This is a prerequisite for running the example Ruby test suite.

```bash
gem install rspec
```

--------------------------------

### Clone Ruby Example Test Suite Project

Source: https://buildkite.com/docs/test-engine/getting-started

Clones the example Ruby test suite project from GitHub. This repository contains a sample project to demonstrate Test Engine integration.

```bash
git clone git@github.com:buildkite/ruby-example-test-suite.git
cd ruby-example-test-suite
```

--------------------------------

### Manual Buildkite Agent Setup (Bash)

Source: https://buildkite.com/docs/agent/v2/installation

This snippet demonstrates the manual installation steps for the Buildkite Agent using Bash. It involves creating necessary directories, copying the agent binary and bootstrap script, and starting the agent. This method is useful for systems not covered by specific installers.

```bash
mkdir ~/.buildkite-agent ~/.buildkite-agent/bin ~/.buildkite-agent/builds
cp buildkite-agent ~/.buildkite-agent/bin
cp bootstrap.sh ~/.buildkite-agent/bootstrap.sh
```

```bash
buildkite-agent start --help
```

--------------------------------

### Starting the Buildkite Agent (Bash)

Source: https://buildkite.com/docs/agent/v3/installation

This command demonstrates how to start the Buildkite agent after a manual installation. It also includes a help flag to show available options.

```bash
buildkite-agent start --help
```

--------------------------------

### Configure npm for Buildkite Registry

Source: https://buildkite.com/docs/package-registries/getting-started

This command configures your npm settings to allow publishing to a specific Buildkite JavaScript registry. It sets the authentication token and registry URL in your `.npmrc` file. This configuration is typically a one-time setup.

```bash
npm set "//packages.buildkite.com/{org.slug}/{registry.slug}/npm/:_authToken" registry-write-token
```

--------------------------------

### Start Buildkite Agent

Source: https://buildkite.com/docs/agent/v2/linux

This command starts the Buildkite Agent after it has been installed. The agent will then be ready to pick up build jobs. This command should be run from the user's home directory where the agent is installed.

```shell
~/.buildkite-agent/bin/buildkite-agent start
```

--------------------------------

### Install Buildkite Test Collector Gem

Source: https://buildkite.com/docs/test-engine/getting-started

Installs the `buildkite-test_collector` gem, which is necessary for integrating your Ruby project's RSpec tests with Buildkite Test Engine.

```bash
gem install buildkite-test_collector
```

--------------------------------

### Install Buildkite CLI on Debian/Ubuntu

Source: https://buildkite.com/docs/platform/cli/installation

Installs the Buildkite CLI on Debian-based systems like Ubuntu. It first ensures necessary packages (curl, gpg) are installed, then adds the Buildkite repository signing key and source list, and finally installs the 'bk' package.

```shell
sudo apt update && sudo apt install curl gpg -y
curl -fsSL "https://packages.buildkite.com/buildkite/cli-deb/gpgkey" | sudo gpg --dearmor -o /etc/apt/keyrings/buildkite_cli-deb-archive-keyring.gpg
echo -e "deb [signed-by=/etc/apt/keyrings/buildkite_cli-deb-archive-keyring.gpg] https://packages.buildkite.com/buildkite/cli-deb/any/ any main\ndeb-src [signed-by=/etc/apt/keyrings/buildkite_cli-deb-archive-keyring.gpg] https://packages.buildkite.com/buildkite/cli-deb/any/ any main" | sudo tee /etc/apt/sources.list.d/buildkite-buildkite-cli-deb.list
sudo apt update && sudo apt install -y bk
```

--------------------------------

### Install Buildkite CLI on Windows

Source: https://buildkite.com/docs/platform/cli/installation

Installs the Buildkite CLI on Windows by downloading the latest release from GitHub, extracting the files, and running 'bk.exe' from the command prompt. This method is suitable for direct execution without a package manager.

```powershell
# Download the latest release from https://github.com/buildkite/cli/releases
# Extract the files to a folder of your choice
# Run bk.exe from a command prompt
```

--------------------------------

### Manual Buildkite Agent Installation Setup (Bash)

Source: https://buildkite.com/docs/agent/v3/installation

This snippet shows the commands to create necessary directories and copy the Buildkite agent binary and bootstrap script for a manual installation. It assumes the user has already downloaded the binary and bootstrap script.

```bash
mkdir ~/.buildkite-agent ~/.buildkite-agent/bin ~/.buildkite-agent/builds
cp buildkite-agent ~/.buildkite-agent/bin
cp bootstrap.sh ~/.buildkite-agent/bootstrap.sh
```

--------------------------------

### Start Buildkite Agent on FreeBSD

Source: https://buildkite.com/docs/agent/v3/freebsd

Starts the Buildkite Agent process on a FreeBSD system. This command should be run after the agent has been installed and configured with a valid agent token.

```shell
buildkite-agent start
```

--------------------------------

### Example Pipeline Start YAML | YAML

Source: https://buildkite.com/docs/agent/v3/cli-pipeline

An example of a Buildkite pipeline YAML file, specifically the 'start' stage. It includes the required `---` separator to denote the beginning of a new pipeline when combined with others. This file defines a single step with a label and a command to execute.

```yaml
---
steps:
  - label: "Start of the build"
    command: ./scripts/build-start.sh
```

--------------------------------

### Buildkite Agent Configuration File Example

Source: https://buildkite.com/docs/agent/v2/configuration

An example of a Buildkite Agent configuration file, demonstrating how to set various agent properties directly. This format is commonly used for static agent setup.

```sh
token="24db61df8338027652b24aadf82dd483b016eef98fcd332815"
name="my-app-%random"
meta-data="ci=true,docker=true"
git-clean-flags="-fdqx"
debug=true
```

--------------------------------

### Configure Buildkite Agent to Start on Login (Linux Script Method)

Source: https://buildkite.com/docs/agent/v2/osx

Installs the Buildkite Agent using a launchd configuration file for macOS, setting it to run as the current user and start on login. It also creates the log directory and starts the agent service.

```bash
# Download the launchd config to /Library/LaunchDaemons/
curl -o ~/Library/LaunchAgents/com.buildkite.buildkite-agent.plist https://raw.githubusercontent.com/buildkite/agent/main/templates/launchd_local_with_gui.plist

# Set buildkite-agent to be run as the current user (a full user, created using System Prefs)
sed -i '' "s/your-build-user/$(whoami)/g" ~/Library/LaunchAgents/com.buildkite.buildkite-agent.plist

# Create the agent's log directory with the correct permissions
mkdir -p ~/.buildkite-agent/log && sudo chmod 775 ~/.buildkite-agent/log

# Start the agent
launchctl load ~/Library/LaunchAgents/com.buildkite.buildkite-agent.plist

# Check the logs
tail -f ~/.buildkite-agent/log/buildkite-agent.log
```

--------------------------------

### Enable and Start Buildkite Agent Service on Debian

Source: https://buildkite.com/docs/agent/v3/debian

This command enables the Buildkite agent service to start on boot and then starts the service immediately. It uses `systemctl` for managing the systemd service. This is crucial for the agent to run automatically.

```shell
sudo systemctl enable buildkite-agent && sudo systemctl start buildkite-agent
```

--------------------------------

### Example Job Details Response

Source: https://buildkite.com/docs/apis/agent-api/stacks

An example JSON response for the 'Get a Job' API, detailing a specific job's environment variables and the command to be executed.

```json
{
  "id": "01234567-89ab-cdef-0123-456789abcdef",
  "env": {
    "BUILDKITE_JOB_ID": "01234567-89ab-cdef-0123-456789abcdef",
    "BUILDKITE_BUILD_NUMBER": "123"
  },
  "command": "echo Hello 👋"
}
```

--------------------------------

### Start and Tail Buildkite Agent (systemd)

Source: https://buildkite.com/docs/agent/v2/redhat

Enables the Buildkite Agent service to start on boot and starts the service immediately. It then tails the system messages to monitor the agent's logs.

```shell
# For distributions with systemctl
sudo systemctl enable buildkite-agent && sudo systemctl start buildkite-agent
sudo tail -f /var/log/messages
```

--------------------------------

### Start and Monitor Buildkite Agent

Source: https://buildkite.com/docs/agent/v3/redhat

Enables the Buildkite Agent service to start on boot and then starts the service immediately. It also tails the system messages log to monitor the agent's activity.

```shell
sudo systemctl enable buildkite-agent && sudo systemctl start buildkite-agent
sudo tail -f /var/log/messages
```

--------------------------------

### Buildkite Agent CLI Help

Source: https://buildkite.com/docs/agent/v2

Displays the usage information and available commands for the Buildkite agent command-line interface. This includes commands for starting the agent, managing artifacts, setting and getting meta-data, and handling pipelines.

```shell
$ buildkite-agent --help
Usage:

  buildkite-agent <command> [arguments...]

Available commands are:

  start       Starts a Buildkite agent
  artifact    Upload/download artifacts from Buildkite jobs
  meta-data   Get/set data from Buildkite jobs
  pipeline   Make changes to the pipeline of the currently running build
  help, h     Shows a list of commands or help for one command

Use "buildkite-agent <command> --help" for more information about a command.
```

--------------------------------

### Enable and Start Buildkite Agents (systemctl)

Source: https://buildkite.com/docs/agent/v2/debian

Enables and starts multiple Buildkite agent services using systemctl. This is typically used on systems with systemd as their init system. It ensures the agents start on boot and then manually starts them.

```shell
sudo systemctl enable buildkite-agent@1 && sudo systemctl start buildkite-agent@1
sudo systemctl enable buildkite-agent@2 && sudo systemctl start buildkite-agent@2
```

--------------------------------

### Start and Enable Buildkite Agent Service

Source: https://buildkite.com/docs/agent/v2/ubuntu

Commands to enable and start the Buildkite agent service. Differentiates between systemd (Ubuntu 15.04+) and upstart (older Ubuntu) init systems.

```shell
# Ubuntu 15.04+ (systemd)
sudo systemctl enable buildkite-agent && sudo systemctl start buildkite-agent

# Older Ubuntu (upstart)
sudo service buildkite-agent start
```

--------------------------------

### Install Buildkite Agent on FreeBSD

Source: https://buildkite.com/docs/agent/v3/freebsd

Installs the Buildkite Agent package on FreeBSD using the pkg package manager. This is the primary step for getting the agent running on the system.

```shell
pkg install buildkite-agent
```

--------------------------------

### Buildkite Agent Configuration File Example

Source: https://buildkite.com/docs/agent/v3/cli_start

A snippet showing how to define agent tags directly within the `buildkite-agent.cfg` configuration file. This is one of the methods for setting agent metadata.

```ini
tags="docker=true,ruby2=true"
```

--------------------------------

### Start Buildkite Agents with Specific Queues

Source: https://buildkite.com/docs/pipelines/tutorials/parallel-builds

This demonstrates how to start Buildkite agents and assign them to specific queues using the '--tags' option. Running the command multiple times with different queue tags allows for dedicated agents for different types of tasks, improving build organization and resource allocation.

```bash
buildkite-agent start --tags queue=test

# In another window, or tab
buildkite-agent start --tags queue=deploy
```

--------------------------------

### Install Buildkite CLI on macOS

Source: https://buildkite.com/docs/platform/cli/installation

Installs the Buildkite CLI on macOS using the Homebrew package manager. It adds the official Buildkite Homebrew tap and then installs the specific 'bk@3' formula.

```shell
brew install buildkite/buildkite/bk@3
```

--------------------------------

### Install Buildkite CLI on Red Hat/CentOS

Source: https://buildkite.com/docs/platform/cli/installation

Installs the Buildkite CLI on Red Hat-based systems like CentOS using dnf or yum. It configures the repository by creating a .repo file with the necessary details and then installs the 'bk' package.

```shell
echo -e "[cli-rpm]\nname=Buildkite CLI\nbaseurl=https://packages.buildkite.com/buildkite/cli-rpm/rpm_any/rpm_any/$basearch\nenabled=1\nrepo_gpgcheck=1\ngpgcheck=0\ngpgkey=https://packages.buildkite.com/buildkite/cli-rpm/gpgkey\npriority=1" | sudo tee /etc/yum.repos.d/cli-rpm.repo
sudo dnf install -y bk
```

--------------------------------

### Start and Enable Buildkite Agent (systemd) - Shell

Source: https://buildkite.com/docs/agent/v2/debian

Enables the Buildkite agent service to start on boot and starts the service immediately for Debian 8.x (which uses systemd).

```shell
# For Debian 8.x (systemd)
sudo systemctl enable buildkite-agent && sudo systemctl start buildkite-agent
```

--------------------------------

### Node.js Installation and Dependency Setup in Buildkite Step (YAML)

Source: https://buildkite.com/docs/pipelines/migration/from-jenkins

Installs Node.js and project dependencies within a Buildkite pipeline step. It uses `curl` to fetch and install Node.js, then navigates to the app directory and runs `npm ci` for dependency installation, followed by `npm run lint` to execute linting. This setup is necessary for each step due to Buildkite's fresh workspace execution model.

```yaml
  - label: ":eslint\: Lint"
    id: lint
    commands:
      - curl -fsSL https://deb.nodesource.com/setup_{{matrix.node_version}}.x | bash
      - sudo apt install nodejs
      - cd app && npm ci
      - npm run lint
```

--------------------------------

### Resolved node affinity example

Source: https://buildkite.com/docs/agent/v3/cli_start

This example shows the pipeline step after Buildkite resolves the '$BUILDKITE_AGENT_META_DATA_HOSTNAME' variable to the actual hostname of the agent that uploaded the pipeline.

```yaml
steps:
  - command: echo "I will stick!"
    agents:
      hostname: "agents-computer-hostname"
  - command: echo "I might not"

```

--------------------------------

### Start Buildkite Agent (upstart) - Shell

Source: https://buildkite.com/docs/agent/v2/debian

Starts the Buildkite agent service using the upstart init system, typically found on older Debian versions like Debian 7.x.

```shell
# For Debian 7.x (using upstart)
sudo service buildkite-agent start
```

--------------------------------

### Run RSpec Tests

Source: https://buildkite.com/docs/test-engine/getting-started

Executes the RSpec tests within the cloned Ruby project. This command verifies that the RSpec test runner is functioning correctly.

```bash
rspec
```

--------------------------------

### Install Test Engine Client on Debian

Source: https://buildkite.com/docs/test-engine/bktec/installing-the-client

Installs the Test Engine Client on Debian-based systems using apt. It first ensures curl and gpg are installed, then adds the Buildkite repository signing key and source list, and finally installs the 'bktec' package.

```shell
apt update && apt install curl gpg -y
curl -fsSL "https://packages.buildkite.com/buildkite/test-engine-client-deb/gpgkey" | gpg --dearmor -o /etc/apt/keyrings/buildkite_test-engine-client-deb-archive-keyring.gpg
echo -e "deb [signed-by=/etc/apt/keyrings/buildkite_test-engine-client-deb-archive-keyring.gpg] https://packages.buildkite.com/buildkite/test-engine-client-deb/any/ any main\ndeb-src [signed-by=/etc/apt/keyrings/buildkite_test-engine-client-deb-archive-keyring.gpg] https://packages.buildkite.com/buildkite/test-engine-client-deb/any/ any main" > /etc/apt/sources.list.d/buildkite-buildkite-test-engine-client-deb.list
apt update && apt install bktec
```

--------------------------------

### Add publishConfig to package.json

Source: https://buildkite.com/docs/package-registries/getting-started

This JSON snippet shows how to add the `publishConfig` field to your Node.js project's `package.json` file. This field specifies the registry endpoint for publishing packages.

```json
{
  "name": "nodejs-example-package",
  "version": "1.0.1",
  "description": "An example Node.js package for Buildkite Package Registries",
  "main": "index.js",
  "scripts": {
    "main": "node index.js"
  },
  "author": "A Person",
  "license": "MIT",
  "publishConfig": {"registry": "https://packages.buildkite.com/{org.slug}/{registry.slug}/npm/"}
}
```

--------------------------------

### Start and Tail Buildkite Agent (non-systemd)

Source: https://buildkite.com/docs/agent/v2/redhat

Starts the Buildkite Agent service using the older init.d system and tails the agent-specific log file. This is for systems that do not use systemd, like older versions of Amazon Linux.

```shell
# For distributions without systemctl (such as Amazon Linux)
sudo service buildkite-agent start
sudo tail -f /var/log/buildkite-agent.log
```

--------------------------------

### Targeting agents with specific tags

Source: https://buildkite.com/docs/agent/v3/cli_start

This example demonstrates how to target Buildkite agents running with a specific tag and value, like 'postgres' with version '1.9.4', in your pipeline configuration.

```yaml
steps:
  - command: "script.sh"
    agents:
      postgres: "1.9.4"

```

--------------------------------

### Install Test Engine Client on macOS

Source: https://buildkite.com/docs/test-engine/bktec/installing-the-client

Installs the Test Engine Client on macOS using Homebrew. It first taps the Buildkite Homebrew formulae and then installs the 'bktec' package.

```shell
brew tap buildkite/buildkite && brew install buildkite/buildkite/bktec
```

--------------------------------

### Get Total Build Run Time

Source: https://buildkite.com/docs/apis/graphql/cookbooks/builds

Retrieves the total run time for a specific build, including its start and finish times.

```APIDOC
## Get the total build run time

To get the total run time for a build, you can use the following query.

### Method
GET (or POST with query in body)

### Endpoint
`/v2/graphql`

### Parameters
#### Query Parameters
- **query** (String) - The GraphQL query string.

### Request Body (for POST)
```json
{
  "query": "query GetTotalBuildRunTime {\n  build(slug: \"organization-slug/pipeline-slug/build-number\") {\n    pipeline {\n      name\n    }\n    url\n    startedAt\n    finishedAt\n  }\n}"
}
```

### Request Example
```graphql
query GetTotalBuildRunTime {
  build(slug: "organization-slug/pipeline-slug/build-number") {
    pipeline {
      name
    }
    url
    startedAt
    finishedAt
  }
}
```

### Response
#### Success Response (200)
- **data** (Object)
  - **build** (Object)
    - **pipeline** (Object)
      - **name** (String) - The name of the pipeline.
    - **url** (String) - The URL of the build.
    - **startedAt** (DateTime) - The timestamp when the build started.
    - **finishedAt** (DateTime) - The timestamp when the build finished.
```

--------------------------------

### Buildkite Agent Start with Experiments

Source: https://buildkite.com/docs/agent

Demonstrates how to start the Buildkite agent while enabling experimental features using the `--experiment` flag. Multiple experiments can be specified. This allows users to test upcoming functionalities at their own risk.

```bash
buildkite-agent start --experiment experiment1 --experiment experiment2

```

--------------------------------

### Get Total Build Run Time (GraphQL)

Source: https://buildkite.com/docs/apis/graphql/cookbooks/builds

Retrieves the start and finish times for a specific build to calculate its total run time. Requires the build's full slug.

```graphql
query GetTotalBuildRunTime {
  build(slug: "organization-slug/pipeline-slug/build-number") {
    pipeline {
      name
    }
    url
    startedAt
    finishedAt
  }
}
```

--------------------------------

### Manage Buildkite Agent with Upstart (Debian 7.x)

Source: https://buildkite.com/docs/agent/v2/debian

Manages Buildkite agent services on Debian 7.x using upstart. This involves copying the default configuration, starting a specific agent instance, and following its logs.

```shell
sudo cp /etc/init/buildkite-agent.conf /etc/init/buildkite-agent-2.conf
sudo service buildkite-agent-2 start
sudo tail -f /var/log/upstart/buildkite-agent-2.log
```

--------------------------------

### Install Buildkite SDK (Go)

Source: https://buildkite.com/docs/pipelines/configure/dynamic-pipelines/sdk

Command to install the Buildkite SDK for Go projects.

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

--------------------------------

### NSSM Service Management Commands

Source: https://buildkite.com/docs/agent/v3/windows

Commands to manage the Buildkite Agent Windows service created with NSSM. Includes checking the service status, stopping, and starting the service. Demonstrates expected output for status checks.

```shell
nssm status buildkite-agent
# Expected output: SERVICE_STOPPED
nssm start buildkite-agent
# Expected output: buildkite-agent: START: The operation completed successfully.
nssm status buildkite-agent
```

--------------------------------

### Basic Buildkite Command Step Example

Source: https://buildkite.com/docs/pipelines/defining-steps

This YAML defines a simple Buildkite pipeline with one command step that executes `echo "Hello!"`. This step will print 'Hello!' to the build log. Ensure this YAML is placed within a `pipeline.yml` file in your repository.

```yaml
steps:
  - label: "Example Test"
    command: echo "Hello!"

```

--------------------------------

### Configure Multiple Buildkite Agents with launchd --spawn

Source: https://buildkite.com/docs/agent/v3/macos

This snippet shows how to configure a launchd service to start multiple Buildkite agents with the same configuration using the `--spawn` flag. It specifies the path to the buildkite-agent executable and the number of agents to spawn. This is useful when identical configurations are needed for each agent.

```xml
<key>ProgramArguments</key>
<array>
  <string>/Users/your-build-user/.buildkite-agent/bin/buildkite-agent</string>
  <string>start</string>
  <string>--spawn=5</string>
</array>
```

--------------------------------

### Get Team Pipeline Response Example - JSON

Source: https://buildkite.com/docs/apis/rest-api/teams/pipelines

Example JSON response for the 'Get a Team Pipeline' endpoint, detailing a single team pipeline association with its access level, creation timestamp, pipeline ID, and URL.

```json
{
  "access_level": "read_only",
  "created_at": "2023-12-12T21:57:40.306Z",
  "pipeline_id": "018c5ad7-28f1-45d4-867e-b59fa04511b2",
  "pipeline_url": "http://api.buildkite.com/v2/organizations/acme-inc/pipelines/test-pipeline"
}
```

--------------------------------

### Run Test Engine Client with Docker

Source: https://buildkite.com/docs/test-engine/bktec/installing-the-client

Provides two methods for using the Test Engine Client with Docker. The first runs the client directly from the official Docker image. The second demonstrates how to copy the 'bktec' binary into your own Docker image.

```shell
docker run buildkite/test-engine-client
```

```dockerfile
COPY --from=buildkite/test-engine-client /usr/local/bin/bktec /usr/local/bin/bktec
```

--------------------------------

### Configure Library Example Plugin in Buildkite Pipeline

Source: https://buildkite.com/docs/pipelines/integrations/plugins/using

Shows a basic example of adding a plugin to a Buildkite pipeline step where the plugin requires no specific configuration, indicated by '~'. This highlights the simplest form of plugin integration.

```yml
steps:
  - label: ":books:"
    plugins:
      - library-example#v1.0.0: ~
```

--------------------------------

### Buildkite Agent Command-Line Help

Source: https://buildkite.com/docs/agent

Displays the usage and available commands for the Buildkite agent CLI. It outlines primary functions such as starting, stopping, annotating, artifact management, and environment processing. Use '--help' for specific command details.

```bash
$ buildkite-agent --help
Usage:

  buildkite-agent [command] [arguments...]

Available commands are:

  start      Starts a Buildkite agent
  annotate   Annotate the build page within the Buildkite UI with text from within a Buildkite job
  artifact   Upload/download artifacts from Buildkite jobs
  env        Process environment subcommands
  lock       Process lock subcommands
  meta-data  Get/set data from Buildkite jobs
  pipeline   Make changes to the pipeline of the currently running build
  bootstrap  Run a Buildkite job locally
  step       Retrieve and update the attributes of steps
  stop       Stop the agent
  redactor   Redact sensitive information from logs
  tool       Utility commands, intended for users and operators of the agent to run directly on their machines, and not as part of a Buildkite job
  secret     Interact with Pipelines Secrets
  help       Shows a list of commands or help for one command

Use "buildkite-agent [command] --help" for more information about a command.

```

--------------------------------

### Buildkite CLI Basic Usage

Source: https://buildkite.com/docs/platform/cli

Demonstrates the basic usage and available commands for the Buildkite CLI. It shows how to access help and lists commands for managing agents, builds, pipelines, and more. This is the entry point for interacting with Buildkite via the terminal.

```shell
$ bk
Work with Buildkite from the command line.

Usage:
  bk [command]

Examples:
$ bk build view

Available Commands:
  agent       Manage agents
  api         Interact with the Buildkite API
  build       Manage pipeline builds
  cluster     Manage organization clusters
  completion  Generate the autocompletion script for the specified shell
  configure   Configure Buildkite API token
  help        Help about any command
  init        Initialize a pipeline.yaml file
  job         Manage jobs within a build
  package     Manage packages
  pipeline    Manage pipelines
  use         Select an organization
  user        Invite users to the organization

Flags:
  -h, --help   help for bk

Use "bk [command] --help" for more information about a command.
```

--------------------------------

### Implement Buildkite Deployment Approval Gates with Block Steps

Source: https://buildkite.com/docs/pipelines/deployments/deployment-visibility-with-backstage

Utilize Buildkite's block steps to create manual approval gates for deployments, which are then visible in Backstage. The `prompt` defines the approval question, and `fields` allow users to provide necessary information, such as release notes, before proceeding.

```yaml
steps:
  - block: ":hand: Deployment Approval"
    prompt: "Deploy to production?"
    fields:
      - text: "Release notes"
        key: "release-notes"
        required: true
```

--------------------------------

### Get Builds with Specific State Between Dates for an Organization - GraphQL

Source: https://buildkite.com/docs/apis/graphql/cookbooks/builds

Retrieves builds with a specific state (e.g., `RUNNING`) that were started within a given date range across all pipelines in an organization. This helps in identifying builds that match certain criteria. Requires the organization slug and dates in ISO-8601 format.

```graphql
query {
  organization(slug: "organization-slug") {
    pipelines(first: 10) {
      edges {
        node {
          name
          slug
          builds(
            first: 10,
            createdAtFrom: "YYYY-MM-DDTHH:mm:ss",
            createdAtTo: "YYYY-MM-DDTHH:mm:ss",
            state: RUNNING
          ) {
            edges {
              node {
                id
                number
                message
                state
                url
              }
            }
          }
        }
      }
    }
  }
}
```

--------------------------------

### Example Pipeline Command with Specific Registry Details (Bash)

Source: https://buildkite.com/docs/package-registries/security/oidc

Provides a concrete example of the full pipeline command for registry authentication, replacing placeholders with specific organization ('my-organization') and registry ('my-registry') slugs. This demonstrates how to use the combined command in a practical scenario.

```bash
buildkite-agent oidc request-token --audience "https://packages.buildkite.com/my-organization/my-registry" --lifetime 300 | docker login packages.buildkite.com/my-organization/my-registry --username buildkite --password-stdin
```

--------------------------------

### Buildkite: Example Echo Command Step in pipeline.yml

Source: https://buildkite.com/docs/pipelines/configure/defining-steps

A simple example of a command step within a `pipeline.yml` file. This step will execute the `echo "Hello!"` command, outputting 'Hello!' to the build log. It demonstrates a basic executable step.

```yml
steps:
  - label: "Example Test"
    command: echo "Hello!"
```

--------------------------------

### Install and Configure Buildkite Agent using Linux Script on macOS

Source: https://buildkite.com/docs/agent/v3/macos

Installs the Buildkite Agent on macOS using the Linux installer script, suitable for users who do not use Homebrew. It includes downloading the launchd configuration, setting the correct user, creating log directories, and starting the agent.

```bash
# Download the launchd config to ~/Library/LaunchAgents/
curl -o ~/Library/LaunchAgents/com.buildkite.buildkite-agent.plist https://raw.githubusercontent.com/buildkite/agent/main/templates/launchd_local_with_gui.plist

# Set buildkite-agent to be run as the current user (a full user, created using System Prefs)
sed -i '' "s/your-build-user/$(whoami)/g" ~/Library/LaunchAgents/com.buildkite.buildkite-agent.plist

# Create the agent's log directory with the correct permissions
mkdir -p ~/.buildkite-agent/log && sudo chmod 775 ~/.buildkite-agent/log

# Start the agent
launchctl load ~/Library/LaunchAgents/com.buildkite.buildkite-agent.plist

# Check the logs
tail -f ~/.buildkite-agent/log/buildkite-agent.log
```

--------------------------------

### Quick NuGet Package Installation with Buildkite

Source: https://buildkite.com/docs/package-registries/ecosystems/nuget

Installs a NuGet package using a single command with a temporary read token. This method is suitable for rapid installations and relies on a token that expires after 5 minutes. The command requires specifying the package name, version, and a Buildkite-specific source URL.

```bash
dotnet add package package-name -v version.number \
  --source "https://buildkite:temporary-read-token-that-expires-after-5-minutes@packages.buildkite.com/{org.slug}/{registry.slug}/nuget/index.json"
```

--------------------------------

### Start Buildkite Agent (sysvinit) - Shell

Source: https://buildkite.com/docs/agent/v2/debian

Starts the Buildkite agent service using the traditional sysvinit system, also common on older Debian versions.

```shell
# For Debian 7.x (using sysvinit)
sudo /etc/init.d/buildkite-agent start
```

--------------------------------

### Install Test Engine Client on Red Hat

Source: https://buildkite.com/docs/test-engine/bktec/installing-the-client

Installs the Test Engine Client on Red Hat-based systems using dnf or yum. It configures the repository by creating a .repo file in /etc/yum.repos.d/ and then installs the 'bktec' package.

```shell
echo -e "[test-engine-client-rpm]\nname=Test Engine Client - rpm\nbaseurl=https://packages.buildkite.com/buildkite/test-engine-client-rpm/rpm_any/rpm_any/\$basearch\nenabled=1\nrepo_gpgcheck=1\ngpgcheck=0\ngpgkey=https://packages.buildkite.com/buildkite/test-engine-client-rpm/gpgkey\npriority=1" > /etc/yum.repos.d/test-engine-client-rpm.repo
dnf install -y bktec
```

--------------------------------

### Buildkite Plugin Configuration Example

Source: https://buildkite.com/docs/pipelines/configure/step-types/command-step

Demonstrates how to configure 'plugins' for a Buildkite step. This example shows the use of the 'docker-compose' plugin to run a service defined in 'docker-compose.yml'.

```YAML
steps:
  - label: "Run Docker Compose Service"
    command: "echo 'Starting service...'"
    plugins:
      - docker-compose#v1.0.0:
          run: app
```

--------------------------------

### Jenkins: Shared Workspace Example

Source: https://buildkite.com/docs/pipelines/migration/from-jenkins

Shows a Jenkins pipeline where stages share a common workspace. This allows artifacts, such as `node_modules` installed in an 'Install' stage, to be directly accessible in a subsequent 'Test' stage.

```groovy
// Jenkins: All stages share the same workspace.
stage('Install') {
    sh 'npm install' // Creates node_modules
}

stage('Test') {
    sh 'npm test'    // Uses the node_modules installed in the 'Install' stage
}
```

--------------------------------

### Get Single Test API Response Example (JSON)

Source: https://buildkite.com/docs/apis/rest-api/test-engine/tests

An example JSON response for retrieving a single test. Includes all details of the test, similar to the list response.

```json
{
  "id": "01867216-8478-7fde-a55a-0300f88bb49b",
  "url": "https://api.buildkite.com/v2/analytics/organizations/my_great_org/suites/my_suite_name/tests/01867216-8478-7fde-a55a-0300f88bb49b",
  "web_url": "https://buildkite.com/organizations/my_great_org/analytics/suites/my_suite_name/tests/01867216-8478-7fde-a55a-0300f88bb49b",
  "scope": "User#email",
  "name": "is correctly formatted",
  "location": "./spec/models/user_spec.rb:42",
  "file_name": "./spec/models/user_spec.rb"
}
```

--------------------------------

### Create and Configure Buildkite Pipeline using JavaScript

Source: https://buildkite.com/docs/sdk/typescript/index

Demonstrates how to use the Buildkite SDK to create a new pipeline, add a command step, and then output the pipeline configuration as JSON and YAML. Assumes the SDK is installed.

```javascript
const { Pipeline } = require("@buildkite/buildkite-sdk");  
  
const pipeline = new Pipeline();  
  
pipeline.addStep({
    command: "echo 'Hello, world!'",
});  
  
console.log(pipeline.toJSON());  
console.log(pipeline.toYAML());
```

--------------------------------

### Install Buildkite SDK (Python)

Source: https://buildkite.com/docs/pipelines/configure/dynamic-pipelines/sdk

Command to install the Buildkite SDK for Python projects using uv.

```bash
uv add buildkite-sdk
```

--------------------------------

### Install buildkite-sdk Gem

Source: https://buildkite.com/docs/sdk/ruby

This snippet shows how to install the buildkite-sdk gem using the RubyGems package manager.

```bash
gem install buildkite-sdk

```

--------------------------------

### Install Debian Package using APT

Source: https://buildkite.com/docs/package-registries/ecosystems/debian

Updates the apt package database and installs a specified package from the configured Buildkite Debian registry. This is the final step to get the package onto the system.

```bash
apt update && apt install package-name
```

--------------------------------

### Buildkite API - Get Artifact Response Example

Source: https://buildkite.com/docs/apis/rest-api/artifacts

Example JSON response for retrieving details of a specific Buildkite artifact. This object contains comprehensive metadata about the artifact, including its size, path, and state.

```json
{
  "id": "76365070-34d5-4104-8b91-952780f8029f",
  "job_id": "aae578fe-994c-44e6-84da-4102616928ba",
  "url": "https://api.buildkite.com/v2/organizations/my-great-org/pipelines/my-pipeline/builds/1/jobs/aae578fe-994c-44e6-84da-4102616928ba/artifacts/76365070-34d5-4104-8b91-952780f8029f",
  "download_url": "https://api.buildkite.com/v2/organizations/my-great-org/pipelines/my-pipeline/builds/1/jobs/aae578fe-994c-44e6-84da-4102616928ba/artifacts/76365070-34d5-4104-8b91-952780f8029f/download",
  "state": "finished",
  "path": "dist/app.tar.gz",
  "dirname": "dist",
  "filename": "app.tar.gz",
  "mime_type": "application/x-gzip",
  "file_size": 529371,
  "glob_path": null,
  "original_path": null,
  "sha1sum": "884c4ad3f2545c85c69d0d0ef50c5d4f5266f0b7"
}
```

--------------------------------

### Install Buildkite SDK (JavaScript/TypeScript)

Source: https://buildkite.com/docs/pipelines/configure/dynamic-pipelines/sdk

Command to install the Buildkite SDK for Node.js projects using npm.

```bash
npm install @buildkite/buildkite-sdk
```

--------------------------------

### Pipeline YAML Uploading Merged Group

Source: https://buildkite.com/docs/pipelines/group-step

An example of a Buildkite pipeline YAML file that uploads a new pipeline with a group named 'Setup'. When uploaded as a sub-pipeline, if the parent pipeline also has a 'Setup' group, they will merge.

```yaml
steps:
  - group: "Setup"
    steps:
      - command: "docker build"
```

--------------------------------

### Build Buildkite MCP Server from Source

Source: https://buildkite.com/docs/apis/mcp-server/local/installing

This command builds and installs the Buildkite MCP server from its Go source code. It requires Go version 1.24 or later to be installed. This method fetches the latest version of the server.

```bash
go install github.com/buildkite/buildkite-mcp-server/cmd/buildkite-mcp-server@latest
```

--------------------------------

### Get build info by ID

Source: https://buildkite.com/docs/apis/graphql/cookbooks/builds

Retrieve all available information for a specific build using its UUID.

```APIDOC
## Get build info by ID

### Description
Retrieve all available information for a specific build using its UUID.

### Method
GET (implied by GraphQL query)

### Endpoint
`/v2/graphql

### Parameters
#### Query Parameters
- **uuid** (String) - Required - The unique identifier (UUID) of the build.

### Request Example
```graphql
query GetBuilds {
  build(uuid: "a00000a-xxxx-xxxx-xxxx-a000000000a") {
    id
    number
    url
  }
}
```

### Response
#### Success Response (200)
- **build.id** (String) - The unique identifier of the build.
- **build.number** (Int) - The build number.
- **build.url** (String) - The URL to the build.

#### Response Example
```json
{
  "data": {
    "build": {
      "id": "gid://buildkite/Build/123456",
      "number": 15,
      "url": "https://buildkite.com/organizations/my-org/pipelines/my-pipeline/builds/15"
    }
  }
}
```
```

--------------------------------

### Get all builds for a pipeline

Source: https://buildkite.com/docs/apis/graphql/cookbooks/builds

Retrieve a list of all builds for a given pipeline, including their ID, number, and URL.

```APIDOC
## Get all builds for a pipeline

### Description
Retrieve a list of all builds for a given pipeline, including their ID, number, and URL.

### Method
GET (implied by GraphQL query)

### Endpoint
`/v2/graphql

### Parameters
#### Query Parameters
- **slug** (String) - Required - The pipeline slug in the format `organization-slug/pipeline-slug`.
- **first** (Int) - Optional - The number of builds to retrieve (default is 10).

### Request Example
```graphql
query GetBuilds {
  pipeline(slug: "organization-slug/pipeline-slug") {
    builds(first: 10) {
      edges {
        node {
          id
          number
          url
        }
      }
    }
  }
}
```

### Response
#### Success Response (200)
- **pipeline.builds.edges[].node.id** (String) - The unique identifier of the build.
- **pipeline.builds.edges[].node.number** (Int) - The build number.
- **pipeline.builds.edges[].node.url** (String) - The URL to the build.

#### Response Example
```json
{
  "data": {
    "pipeline": {
      "builds": {
        "edges": [
          {
            "node": {
              "id": "gid://buildkite/Build/123456",
              "number": 15,
              "url": "https://buildkite.com/organizations/my-org/pipelines/my-pipeline/builds/15"
            }
          },
          {
            "node": {
              "id": "gid://buildkite/Build/123455",
              "number": 14,
              "url": "https://buildkite.com/organizations/my-org/pipelines/my-pipeline/builds/14"
            }
          }
        ]
      }
    }
  }
}
```
```

--------------------------------

### Buildkite: Multi-Dimensional Matrix Configuration (matrix.setup)

Source: https://buildkite.com/docs/pipelines/build-matrix

This example showcases a more complex Buildkite build matrix using 'matrix.setup' for multi-dimensional configurations. It defines multiple dimensions (architecture, OS, test suite) which are then multiplied to generate a larger set of jobs. The 'agents.queue' attribute also demonstrates interpolation based on a matrix dimension.

```yaml
steps:
- label: "💥 Matrix Build"
  command: "echo {{matrix.os}} {{matrix.arch}} {{matrix.test}}"
  agents:
    queue: "builder-{{matrix.arch}}"
  matrix:
    setup:
      arch:
        - "amd64"
        - "arm64"
      os:
        - "windows"
        - "linux"
      test:
        - "A"
        - "B"
```

--------------------------------

### Start ssh-agent and Add Keys (Bash)

Source: https://buildkite.com/docs/agent/ssh-keys

This snippet demonstrates how to start an ssh-agent process, add multiple SSH keys (including those with pass-phrases), and export the SSH_AUTH_SOCK environment variable. This is a prerequisite for using multiple keys in Buildkite.

```bash
sudo su buildkite-agent
ssh-agent -a ~/.ssh/ssh-agent.sock
export SSH_AUTH_SOCK=/var/lib/buildkite-agent/.ssh/ssh-agent.sock
ssh-add ~/.ssh/id_rsa-pipeline-1
ssh-add ~/.ssh/id_rsa-pipeline-2

```

--------------------------------

### Uploading pipeline with node affinity

Source: https://buildkite.com/docs/agent/v3/cli_start

This command uploads a pipeline.yml file. When used in conjunction with agent hostname tagging, it prepares for node affinity.

```bash
buildkite-agent pipeline upload

```

--------------------------------

### Refactor Buildkite Pipeline with YAML Aliases

Source: https://buildkite.com/docs/pipelines/migration/from-jenkins

This YAML snippet demonstrates the use of aliases to define common commands and matrix configurations in a Buildkite pipeline. The `&install` alias defines a multi-line script for Node.js setup and npm installation, while `&matrix` defines the Node.js versions for the build. These aliases are then referenced using `*install` and `*matrix` in subsequent steps, reducing code duplication and improving maintainability.

```yaml
common:
  install: &install |
    curl -fsSL https://deb.nodesource.com/setup_{{matrix.node_version}}.x | bash
    sudo apt install nodejs
    cd app && npm ci
  matrix: &matrix
    setup:
      node_version: [20, 22]

steps:
  - label: ":eslint\: Lint (Node {{matrix.node_version}})"
    id: lint
    matrix: *matrix
    commands:
      - *install
      - npm run lint

  - label: ":vitest\: Test (Node {{matrix.node_version}})"
    id: test
    matrix: *matrix
    commands:
      - *install
      - npm test
    artifact_paths:
      - app/coverage/**/* 

  - label: ":wrench\: Build (Node {{matrix.node_version}})"
    matrix: *matrix
    commands:
      - *install
      - npm run build
    depends_on: 
      - lint
      - test
    artifact_paths:
      - app/dist/**/* 

```

--------------------------------

### Start Buildkite Agent

Source: https://buildkite.com/docs/agent/v2/cli-start

Manually start a Buildkite agent and register it with Buildkite. The agent will run jobs within a pseudo-terminal (PTY) if available, executing a bootstrap script to check out code and run build scripts. Options allow customization of configuration, naming, priority, meta-data, and more.

```bash
buildkite-agent start --token xxx
```

--------------------------------

### Buildkite Pipeline with Group Merging (Label)

Source: https://buildkite.com/docs/pipelines/configure/step-types/group-step

Illustrates Buildkite group merging behavior when a pipeline is uploaded with a matching group label. This example shows how a new 'Setup' group with a specific label in an uploaded pipeline will merge with an existing 'Setup' group.

```yaml
steps:
  - group: "~"
    label: "Setup"
    steps:
      - commands:
        - "buildkite-agent pipeline upload"
        - echo "start"
```

```yaml
steps:
  - group: "~"
    label: "Setup"
    steps:
      - command: echo "proceed"
```

--------------------------------

### Enable Buildkite Agent Experiments via Command Line

Source: https://buildkite.com/docs/agent/v3

This snippet demonstrates how to enable one or more experimental features for the Buildkite agent using the `--experiment` flag with the `buildkite-agent start` command. Multiple experiments can be specified by repeating the flag.

```bash
buildkite-agent start --experiment experiment1 --experiment experiment2
```

--------------------------------

### Current User Response Example (JSON)

Source: https://buildkite.com/docs/apis/rest-api/user

This is an example of the JSON response received when successfully retrieving current user details from the Buildkite API. It includes fields like user ID, name, email, avatar URL, and creation date.

```json
{
  "id": "abc123-4567-8910-ứ",
  "graphql_id": "VXNlci0tLWU1N2ZiYTBmLWFiMTQtNGNjMC1iYjViLTY5NTc3NGZmYmZiZQ==",
  "name": "John Smith",
  "email": "john.smith@example.com",
  "avatar_url": "https://www.gravatar.com/avatar/abc123...",
  "created_at": "2012-03-04T56:07:08.910Z"
}
```

--------------------------------

### Get Organization GraphQL ID

Source: https://buildkite.com/docs/platform/sso/sso-setup-with-graphql

Retrieve the unique GraphQL ID for your Buildkite organization, which is required for SSO provider configuration.

```APIDOC
## GET Organization GraphQL ID

### Description
This query retrieves the unique GraphQL ID for a Buildkite organization based on its slug.

### Method
QUERY

### Endpoint
/graphql

### Parameters
#### Query Parameters
- **slug** (String) - Required - The unique slug of the Buildkite organization.

### Request Example
```graphql
query OrganizationId {
  organization(slug: "myorg") {
    id
  }
}
```

### Response
#### Success Response (200)
- **organization.id** (ID) - The GraphQL ID of the organization.
```

--------------------------------

### Add Labels for Differentiating Parallel Jobs

Source: https://buildkite.com/docs/pipelines/tutorials/parallel-builds

Updates a Buildkite pipeline step to include a label with a number that differentiates parallel build jobs at runtime. It uses the `%n` helper to display the job count starting from 0. Other available helpers are `%N` (starts at 1) and `%t` (total jobs).

```yaml
steps:
  - command: "tests.sh"
    label: "Test %n"
    parallelism: 5
```

--------------------------------

### Buildkite Matrix Expansion Example

Source: https://buildkite.com/docs/pipelines/configure/step-types/command-step

Provides an example of using the 'matrix' configuration to expand build steps. This allows defining multiple variations of a step based on an array of values, here used for different operating systems.

```YAML
steps:
  - label: "{{matrix}} build"
    command: "echo '.buildkite/steps/build-binary.sh {{matrix}}'"
    matrix:
      - "macOS"
      - "Linux"
```

--------------------------------

### Install Buildkite Agent on Linux

Source: https://buildkite.com/docs/agent/v2/linux

This script downloads and installs the correct Buildkite Agent binary for your system and architecture. It requires an agent token to be provided as an environment variable. Ensure you replace 'INSERT-YOUR-AGENT-TOKEN-HERE' with your actual token.

```shell
TOKEN="INSERT-YOUR-AGENT-TOKEN-HERE" bash -c "`curl -sL https://raw.githubusercontent.com/buildkite/agent/main/install.sh`"
```

--------------------------------

### Install Buildkite Backstage Plugin

Source: https://buildkite.com/docs/pipelines/integrations/other/backstage

Installs the Buildkite plugin for Backstage using yarn. This command is typically run from your project's plugins directory or from an external package.

```bash
yarn workspace app add @buildkite/backstage-plugin-buildkite
```
Tokens:
Raw