### 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 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
```

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

### 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 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
```

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

### 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/"}
}
```

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

### 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
```

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

### 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
```

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

### 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
```

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

### 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"
```

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

### 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
```

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

### 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

```

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

### 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
```

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

### 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
```

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

### 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"

```

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

### 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.
```

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

### 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
```

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

### 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
  }
}
```

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

### 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
```

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

### 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"
            }
          }
        ]
      }
    }
  }
}
```
```

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

### 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 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`"
```

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

### 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

```

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

### 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!"

```

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

### 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
```

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

### Buildkite Hosted Queue Configuration Example (Linux)

Source: https://buildkite.com/docs/clusters/manage-queues

An example JSON snippet showing the `hostedAgents` configuration for a Buildkite hosted queue using a Linux instance shape.

```json
"hostedAgents": {
  "instanceShape": "LINUX_AMD64_2X4"
}
```

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

### Starting agent with a hostname tag

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

This command starts a Buildkite agent and applies a tag with the system's hostname. This is a prerequisite for enabling node affinity.

```bash
buildkite-agent start --tags "hostname=`hostname`"

```

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

### 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
```

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

### Execute RSpec tests with Test Engine data

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

This command executes the RSpec test runner and sends its execution data to Buildkite Test Engine. It requires a Buildkite Analytics token and allows for a custom message to describe the test run. The output confirms the test execution and can be viewed in the Test Engine UI.

```bash
BUILDKITE_ANALYTICS_TOKEN=<api-token-value> BUILDKITE_ANALYTICS_MESSAGE="My first test run" rspec
```

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

### 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: ~
```

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

### Pipeline YAML with Group

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

An example of a Buildkite pipeline YAML file defining a group named 'Setup' with nested steps. This is used to demonstrate group merging behavior.

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

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

### Example Resource Class Configurations (YAML)

Source: https://buildkite.com/docs/agent/v3/agent-stack-k8s/container-resource-limits

Provides example configurations for different Resource Classes in the Buildkite Agent Stack for Kubernetes controller's values YAML. These examples illustrate setting CPU, memory, and GPU resources, as well as node selectors for specific hardware.

```yaml
# values.yaml
config:
  resource-classes:
    xs:
      resource:
        requests:
          cpu: "100m"
          memory: "128Mi"
        limits:
          cpu: "200m"
          memory: "256Mi"
    gpu:
      resource:
        requests:
          nvidia.com/gpu: "1"
          cpu: "1000m"
          memory: "2Gi"
        limits:
          nvidia.com/gpu: "1"
          cpu: "2000m"
          memory: "4Gi"
      nodeSelector:
        accelerator: "nvidia-tesla-k80"
    spot:
      nodeSelector:
        node-type: "spot"
        instance-type: "large"
```

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

### 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.
```

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

### Install buildkite-sdk Gem

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

This code snippet shows how to install the buildkite-sdk gem using the RubyGems package manager. This is the initial step required to use the SDK in a Ruby project.

```bash
gem install buildkite-sdk
```

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

### 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
              }
            }
          }
        }
      }
    }
  }
}
```

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

### Automated Buildkite Agent Install with PowerShell

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

Installs the latest Buildkite Agent using a PowerShell script. Requires administrative privileges. Sets the agent token as an environment variable and bypasses execution policy for the current process. Downloads and executes the installation script from GitHub.

```powershell
PS> $env:buildkiteAgentToken = "<your_token>"
PS> Set-ExecutionPolicy Bypass -Scope Process -Force
iex ((New-Object System.Net.WebClient).DownloadString('https://raw.githubusercontent.com/buildkite/agent/main/install.ps1'))
```

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

### 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
```

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

### Example Buildkite Pipeline YAML Output

Source: https://buildkite.com/docs/pipelines/migration/tool

This is an example of the YAML output generated by the Buildkite migration tool when converting a CircleCI configuration. It shows the structure of a Buildkite pipeline definition.

```yaml
---
steps:
- commands:
  - "# No need for checkout, the agent takes care of that"
  - pip install -r requirements/dev.txt
  plugins:
  - docker#v5.7.0:
      image: circleci/python:3.6.2-stretch-browsers
  agents:
    executor_type: docker
  key: build

```

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

### 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!"
```

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

### Get All Builds for a Pipeline using GraphQL

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

Retrieves a list of all builds for a specified pipeline, including each build's ID, number, and URL. It supports pagination with a `first` argument to limit the number of results. Requires the organization slug and pipeline slug.

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

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

### Starting Buildkite Agent with Custom Configuration Directory

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

Demonstrates how to start the Buildkite Agent using a custom configuration directory. This is achieved by setting the BUILDKITE_AGENT_CONFIG environment variable before executing the buildkite-agent start command.

```bash
BUILDKITE_AGENT_CONFIG="/etc/buildkite-agent/custom-config-files-dir" buildkite-agent start
```

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

### Install Buildkite Agent Service with NSSM (Automated Install)

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

Installs the Buildkite Agent as a Windows service using the NSSM (Non-Sucking Service Manager) tool. Assumes the agent was installed via the PowerShell script and uses default paths. Configures the application parameters, stdout, and stderr log files.

```shell
# These commands assume you installed the agent using PowerShell
# Your paths may be different if you did a manual installation
nssm install buildkite-agent "C:\buildkite-agent\bin\buildkite-agent.exe" "start"
nssm set buildkite-agent AppParameters "start --queue=windows"
nssm set buildkite-agent AppStdout "C:\buildkite-agent\buildkite-agent.log"
nssm set buildkite-agent AppStderr "C:\buildkite-agent\buildkite-agent.log"
```

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

### 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
}
```

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

### Install Prerequisites and Configure FreeBSD for Buildkite Agent

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

Installs necessary packages (bash, git) and configures the FreeBSD system to use bash as the default shell for the Buildkite Agent. It also mounts fdescfs, creates a symbolic link for bash, and optionally changes the user's default shell.

```shell
sudo pkg install bash git
sudo sh -c 'echo "fdesc /dev/fd fdescfs rw 0 0" >> /etc/fstab'
sudo mount -a

# The agent requires a version of bash to be available at: /bin/bash
sudo ln -s /usr/local/bin/bash /bin/bash

# If you want change your default shell to bash
sudo chsh -s /usr/local/bin/bash `whoami`

# You now switch to bash
bash
```

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

### Install Buildkite Agent on Ubuntu

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

Commands to add the Buildkite PGP key, configure the apt source list, update package lists, and install the Buildkite agent package. Requires root privileges.

```shell
wget -O- https://keys.openpgp.org/vks/v1/by-fingerprint/32A37959C2FA5C3C99EFBC32A79206696452D198 | sudo tee /usr/share/keyrings/buildkite-agent-archive-keyring.gpg
echo "deb [signed-by=/usr/share/keyrings/buildkite-agent-archive-keyring.gpg] https://apt.buildkite.com/buildkite-agent stable main" | sudo tee /etc/apt/sources.list.d/buildkite-agent.list
sudo apt-get update && sudo apt-get install -y buildkite-agent
```

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

### 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());
```

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

### Buildkite Pipeline Optional Properties (Object Examples)

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

Shows examples of object-based configurations for pipelines, such as setting environment variables or provider-specific settings.

```json
{
  "env": {
    "KEY": "value"
  }
}
```

```json
{
  "provider_settings": {
    "publish_commit_status": true,
    "build_pull_request_forks": true
  }
}
```

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

### Environment Hook Example (Windows Batch)

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

A Windows Batch script example for an environment hook, demonstrating how to set environment variables on a Windows agent. This hook sets a GitHub API key, similar to the bash example, but uses Windows Batch syntax. The file should have a .bat extension.

```batch
@ECHO OFF
ECHO "--- \:house_with_garden\: Setting up the environment"
SET GITHUB_RELEASE_ACCESS_KEY='xxx'
```

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

### Example Scheduled Jobs Response

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

An example JSON response for the 'List Scheduled Jobs' API, showing a list of jobs with their metadata, pagination information, and cluster queue status.

```json
{
  "jobs": [
    {
      "id": "01234567-89ab-cdef-0123-456789abcdef",
      "scheduled_at": "2023-10-01T12:00:00.000Z",
      "priority": 1,
      "agent_query_rules": ["test=a"],
      "pipeline_slug": "my-pipeline",
      "pipeline_id": "pipeline-uuid",
      "build_number": 123,
      "build_branch": "main",
      "build_id": "build-uuid",
      "step_key": "test"
    }
  ],
  "page_info": {
    "has_next_page": false,
    "end_cursor": null
  },
  "cluster_queue": {
    "id": "queue-id",
    "dispatch_paused": false
  }
}
```

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

### 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
```