================
CODE SNIPPETS
================
TITLE: Run Node.js Example Package
DESCRIPTION: Executes the main script of the Node.js example package using npm. This command verifies that the package runs successfully and should output 'Hello world!'.

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

LANGUAGE: bash
CODE:
```
npm run main
```

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

TITLE: Clone Node.js Example Package Project
DESCRIPTION: Clones the example Node.js package repository from GitHub using Git. This is the first step in local testing and packaging.

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

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

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

TITLE: Install RSpec Testing Framework
DESCRIPTION: Installs the RSpec testing framework required for the Ruby example project. This command is run in a terminal or command prompt after Ruby has been installed.

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

LANGUAGE: bash
CODE:
```
gem install rspec
```

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

TITLE: Clone Ruby Example Test Suite Project
DESCRIPTION: Clones the example Ruby project used for demonstrating Buildkite Test Engine. This command is executed in a terminal or command prompt.

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

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

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

TITLE: Starting the Buildkite Agent
DESCRIPTION: This command demonstrates how to start the Buildkite Agent after manual installation. It includes a --help flag to display available options for the start command.

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

LANGUAGE: shell
CODE:
```
buildkite-agent start --help
```

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

TITLE: Buildkite Agent Start Command Example
DESCRIPTION: An example of starting a Buildkite agent using the '--token' flag to provide the agent's authentication token.

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

LANGUAGE: bash
CODE:
```
$ buildkite-agent start --token xxx
```

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

TITLE: Install Buildkite Test Collector Gem
DESCRIPTION: Installs the 'buildkite-test_collector' gem, which is necessary for integrating Buildkite's test collection capabilities into a Ruby project.

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

LANGUAGE: bash
CODE:
```
gem install buildkite-test_collector
```

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

TITLE: Install Buildkite CLI on Debian/Ubuntu
DESCRIPTION: Installs the Buildkite CLI on Debian and Ubuntu systems. Requires curl and gpg to be installed first, then configures the APT registry and installs the 'bk' package.

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

LANGUAGE: bash
CODE:
```
sudo apt update && sudo apt install curl gpg -y
```

LANGUAGE: bash
CODE:
```
curl -fsSL "https://packages.buildkite.com/buildkite/cli-deb/gpgkey" | sudo gpg --dearmor -o /etc/apt/keyrings/buildkite_cli-deb-archive-keyring.gpg
```

LANGUAGE: bash
CODE:
```
echo -e "deb [signed-by=/etc/apt/keyrings/buildkite_cli-deb-archive-keyring.gpg] https://packages.buildkite.com/buildkite/cli-deb/any/ any main
deb-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
```

LANGUAGE: bash
CODE:
```
sudo apt update && sudo apt install -y bk
```

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

TITLE: Start Buildkite Agent
DESCRIPTION: Starts the Buildkite agent process from its installation directory.

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

LANGUAGE: shell
CODE:
```
~/.buildkite-agent/bin/buildkite-agent start
```

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

TITLE: Start Buildkite Agent on Windows
DESCRIPTION: Command to start the Buildkite Agent service after installation and configuration on a Windows machine.

SOURCE: https://buildkite.com/docs/agent/v2/windows

LANGUAGE: bash
CODE:
```
buildkite-agent start
```

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

TITLE: Example of Generating Token using Bash
DESCRIPTION: Illustrates how to use Bash to configure a `pre-checkout` agent hook for generating a JWT and exchanging it for a GitHub App installation access token, as described in GitHub's documentation.

SOURCE: https://buildkite.com/docs/pipelines/source-control/github

LANGUAGE: bash
CODE:
```
The example that follows will be using Bash to configure a `pre-checkout` agent hook.
```

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

TITLE: Start and Enable Buildkite Agent (Bash)
DESCRIPTION: Enables the Buildkite agent to start automatically on system boot and starts the agent service immediately. This uses `systemd` for modern Ubuntu versions.

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

LANGUAGE: bash
CODE:
```
# Ubuntu 15.04+ (systemd)
sudo systemctl enable buildkite-agent && sudo systemctl start buildkite-agent
```

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

TITLE: Start Buildkite Agent (Upstart - Bash)
DESCRIPTION: Starts the Buildkite agent service using the `upstart` init system, typically for older Ubuntu versions. This command assumes the agent service has already been configured.

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

LANGUAGE: bash
CODE:
```
# Older Ubuntu (upstart)
sudo service buildkite-agent start
```

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

TITLE: Publish Node.js Package
DESCRIPTION: Commands to package and publish a Node.js project to a configured registry. Assumes the project is in the current directory.

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

LANGUAGE: bash
CODE:
```
npm pack
npm publish
```

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

TITLE: Start and enable Buildkite Agent service
DESCRIPTION: Enables the Buildkite Agent service to start automatically on boot and starts the service immediately. This ensures the agent is running and ready to accept jobs.

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

LANGUAGE: shell
CODE:
```
sudo systemctl enable buildkite-agent && sudo systemctl start buildkite-agent
```

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

TITLE: Starting Buildkite Agent with Custom Configuration
DESCRIPTION: Demonstrates how to start the Buildkite Agent while specifying a custom configuration directory using an environment variable. This allows for more flexible agent setup and management.

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

LANGUAGE: shell
CODE:
```
BUILDKITE_AGENT_CONFIG="/etc/buildkite-agent/custom-config-files-dir" buildkite-agent start
```

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

TITLE: Start Buildkite Agents with Specific Queues
DESCRIPTION: This demonstrates how to start Buildkite agents and assign them to specific queues using the `--tags` option. This allows for routing jobs to agents configured for particular tasks, such as testing or deployment.

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

LANGUAGE: bash
CODE:
```
buildkite-agent start --tags queue=test
# In another window, or tab
buildkite-agent start --tags queue=deploy
```

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

TITLE: Buildkite Agent Start with Environment Variable
DESCRIPTION: An example of starting the Buildkite Agent using an environment variable to set meta-data, including the queue and hostname.

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

LANGUAGE: shell
CODE:
```
BUILDKITE_AGENT_META_DATA="queue=deploy,host=$(hostname)" buildkite-agent start
```

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

TITLE: Start Buildkite Agent (Debian 7.x - upstart)
DESCRIPTION: Starts the Buildkite agent service for Debian 7.x using upstart.

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

LANGUAGE: bash
CODE:
```
# For Debian 7.x (using upstart)
sudo service buildkite-agent start
```

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

TITLE: Generate JWT and Exchange for Installation Access Token (Bash Example)
DESCRIPTION: This example shows how to configure a `pre-checkout` agent hook using Bash to generate a JSON Web Token (JWT) and exchange it for a GitHub App installation access token. This process involves using the private key and installation ID.

SOURCE: https://buildkite.com/docs/integrations/github

LANGUAGE: bash
CODE:
```
# Example placeholder for generating JWT and token
# Actual implementation would involve tools like openssl or specific libraries
# and API calls to GitHub.

# Retrieve private key from Buildkite secret
PRIVATE_KEY=$(buildkite-agent secret get my-github-app-private-key)

# GitHub App details
APP_ID="YOUR_APP_ID"
INSTALLATION_ID="YOUR_INSTALLATION_ID"

# Generate JWT (this is a simplified representation)
# In a real scenario, you would use a tool or library to create the JWT payload
# with claims like iss (issuer), exp (expiration), iat (issued at), and jti (JWT ID).
# The JWT would then be signed using the private key.

# Placeholder for JWT generation command
# JWT=$(generate_jwt --app-id $APP_ID --private-key "$PRIVATE_KEY" --installation-id $INSTALLATION_ID)

# Exchange JWT for an installation access token (using curl)
# curl -X POST -H "Accept: application/vnd.github.v3+json" \
#      "https://api.github.com/app/installations/$INSTALLATION_ID/access_tokens" \
#      -d "{"token": \"$JWT\"}"

# The response would contain the installation access token
# STORE THE TOKEN SECURELY AND USE IT FOR API CALLS
```

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

TITLE: Configure Buildkite Agent to Start on Login (macOS)
DESCRIPTION: Sets up the Buildkite Agent to automatically start when the system logs in. This involves downloading a launchd configuration, setting the correct user, creating a log directory, and loading the agent.

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

LANGUAGE: bash
CODE:
```
# 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
```

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

TITLE: Install Buildkite CLI on Red Hat/CentOS
DESCRIPTION: Installs the Buildkite CLI on Red Hat and CentOS systems by configuring the yum/dnf repository and installing the 'bk' package.

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

LANGUAGE: bash
CODE:
```
echo -e "[cli-rpm]
name=Buildkite CLI
baseurl=https://packages.buildkite.com/buildkite/cli-rpm/rpm_any/rpm_any/$basearch
enabled=1
repo_gpgcheck=1
gpgcheck=0
gpgkey=https://packages.buildkite.com/buildkite/cli-rpm/gpgkey
priority=1" | sudo tee /etc/yum.repos.d/cli-rpm.repo
```

LANGUAGE: bash
CODE:
```
sudo dnf install -y bk
```

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

TITLE: Buildkite Agent Tagging Example
DESCRIPTION: Demonstrates how to set Buildkite agent tags using an environment variable when starting the agent. This example includes queue information and the agent's hostname.

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

LANGUAGE: shell
CODE:
```
BUILDKITE_AGENT_TAGS="queue=deploy,host=$(hostname)" buildkite-agent start
```

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

TITLE: Start Buildkite Agent (Debian 8.x - systemd)
DESCRIPTION: Enables the Buildkite agent service to start on boot and starts the service for Debian 8.x using systemd.

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

LANGUAGE: bash
CODE:
```
# For Debian 8.x (systemd)
sudo systemctl enable buildkite-agent && sudo systemctl start buildkite-agent
```

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

TITLE: Configure Multiple Buildkite Agents with --spawn (launchd plist)
DESCRIPTION: This code snippet shows how to configure a launchd plist to start multiple Buildkite agents with a shared configuration using the '--spawn' flag. This is useful when all agents require the same settings. The example specifies starting five agents.

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

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

```

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

TITLE: Start Buildkite Agent (Debian 7.x - sysvinit)
DESCRIPTION: Starts the Buildkite agent service for older Debian systems using sysvinit.

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

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

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

TITLE: Install Buildkite Agent as a Service using NSSM (GUI)
DESCRIPTION: Opens the NSSM (Non-Sucking Service Manager) GUI to manually install and configure the Buildkite Agent as a Windows service. This allows the agent to run in the background and start automatically with the system.

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

LANGUAGE: bash
CODE:
```
nssm install buildkite-agent
```

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

TITLE: Install Buildkite CLI on macOS
DESCRIPTION: Installs the Buildkite CLI on macOS using Homebrew. This command adds the Buildkite tap and installs the 'bk@3' package.

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

LANGUAGE: bash
CODE:
```
brew install buildkite/buildkite/bk@3
```

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

TITLE: Enable and Start Buildkite Agent Service
DESCRIPTION: Enables the Buildkite Agent service to start automatically on boot and then starts the service immediately. It also tails the system logs for the agent.

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

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

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

TITLE: Buildkite Agent Start Command Usage
DESCRIPTION: Demonstrates the basic usage of the `buildkite-agent start` command and its primary function of initiating an agent. It outlines the command structure and the general process of job execution.

SOURCE: https://buildkite.com/docs/agent/v2/agent-meta-data

LANGUAGE: bash
CODE:
```
buildkite-agent start --token xxx
```

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

TITLE: Install Node.js and Dependencies for Linting in Buildkite
DESCRIPTION: This code installs Node.js and its dependencies for a linting step. It uses `curl` to fetch the NodeSource setup script and `apt` to install Node.js, followed by `npm ci` for dependency installation and `npm run lint` for executing the linting process. This setup is required for each step due to Buildkite's fresh workspace behavior.

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

LANGUAGE: yaml
CODE:
```
  - 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
```

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

TITLE: Manual Buildkite Agent Installation Steps
DESCRIPTION: This snippet details the manual installation process for the Buildkite Agent. It involves creating necessary directories and copying the agent binary and bootstrap script into place.

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

LANGUAGE: shell
CODE:
```
mkdir ~/.buildkite-agent ~/.buildkite-agent/bin ~/.buildkite-agent/builds
cp buildkite-agent ~/.buildkite-agent/bin
cp bootstrap.sh ~/.buildkite-agent/bootstrap.sh
```

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

TITLE: Pipeline YAML Configuration Example
DESCRIPTION: An example of a simple Buildkite pipeline defined in YAML format. This specific configuration includes an environment variable and a single command step.

SOURCE: https://buildkite.com/docs/api/pipelines

LANGUAGE: yaml
CODE:
```
env:
 "FOO": "bar"
steps:
 - command: "script/release.sh"
   name: "Build :package:"
```

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

TITLE: Example Buildkite Plugin Configuration (YAML)
DESCRIPTION: Demonstrates how to configure the File Counter Buildkite plugin in a pipeline.yml file, specifying the plugin and its 'pattern' option.

SOURCE: https://buildkite.com/docs/pipelines/integrations/plugins/writing

LANGUAGE: yaml
CODE:
```
# File Counter Buildkite Plugin

Annotates the build with a file count.

## Example

Add the following to your `pipeline.yml`:

```yaml
steps:
  - command: ls
    plugins:
      - a-github-user/file-counter#v1.0.0:
          pattern: '*.md'
```

## Configuration

### `pattern` (Required, string)

The file name pattern, for example `*.ts`. Supports any pattern supported by [find -name](http://man7.org/linux/man-pages/man1/find.1.html).
```

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

TITLE: Create a Build (Example)
DESCRIPTION: This example demonstrates how to make a POST request to the Buildkite API to create a new build. It includes essential parameters like commit and branch, and optional ones like message and environment variables.

SOURCE: https://buildkite.com/docs/api/builds

LANGUAGE: bash
CODE:
```
curl -X POST "https://api.buildkite.com/v2/organizations/my-org/pipelines/my-pipeline/builds" \
  -H "Authorization: Bearer YOUR_ACCESS_TOKEN" \
  -H "Content-Type: application/json" \
  -d $$'{
    "commit": "HEAD",
    "branch": "main",
    "message": "Testing all the things :rocket:",
    "env": {
      "MY_VARIABLE": "my_value"
    },
    "author": {
      "name": "Jane Doe",
      "email": "jane@example.com"
    }
  }'
```

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

TITLE: Buildkite Agent Start Command
DESCRIPTION: This section describes how to start the Buildkite Agent manually and register it with Buildkite. It includes the usage, a description of the bootstrap script, and common options.

SOURCE: https://buildkite.com/docs/agent/v2/agent-meta-data

LANGUAGE: APIDOC
CODE:
```
## buildkite-agent start

### Description
Used to manually start an agent and register it with Buildkite. The agent's bootstrap-script is called to check out code and run the build script.

### Method
CLI Command

### Endpoint
N/A

### Parameters
#### Command Options
- **--config** (string) - Optional - Path to a configuration file.
- **--token** (string) - Required - Your account agent token.
- **--name** (string) - Optional - The name of the agent.
- **--priority** (integer) - Optional - The priority of the agent (higher priorities are assigned work first).
- **--meta-data** (string array) - Optional - Meta-data for the agent (default is "queue=default"). Can be specified multiple times.
- **--meta-data-ec2** (boolean) - Optional - Include the host's EC2 meta-data (instance-id, instance-type, and ami-id) as meta-data.
- **--meta-data-ec2-tags** (boolean) - Optional - Include the host's EC2 tags as meta-data.
- **--git-clean-flags** (string) - Optional - Change flags used during Git clean.
- **--git-clone-flags** (string) - Optional - Change flags used during Git clone.
- **--bootstrap-script** (string) - Optional - Path to the bootstrap script.
- **--build-path** (string) - Optional - Path to where the builds will run from.
- **--hooks-path** (string) - Optional - Directory where the hook scripts are found.
- **--no-pty** (boolean) - Optional - Do not run jobs within a pseudo terminal.
- **--no-automatic-ssh-fingerprint-verification** (boolean) - Optional - Don't automatically verify SSH fingerprints.
- **--no-command-eval** (boolean) - Optional - Don't allow this agent to run arbitrary console commands.
- **--endpoint** (string) - Optional - The Agent API endpoint.
- **--no-color** (boolean) - Optional - Don't show colors in logging.
- **--debug** (boolean) - Optional - Enable debug mode.
- **--debug-http** (boolean) - Optional - Enable HTTP debug mode, which dumps all request and response bodies to the log.

### Request Example
```bash
buildkite-agent start --token xxx --name "my-agent" --meta-data "queue=docker" --meta-data "version=1.0"
```

### Response
N/A (This is a CLI command that starts a background process)

```

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

TITLE: Start and Monitor Buildkite Agent (systemd)
DESCRIPTION: Enables the Buildkite Agent to start on boot and starts the agent service. It also tails the system messages log to monitor agent activity.

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

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

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

TITLE: Configure Buildkite Agent for Login (Linux Script)
DESCRIPTION: Sets up the Buildkite Agent to start automatically on login for macOS installations using the Linux installer script. This involves downloading a launchd configuration, setting user permissions, creating log directories, and loading the service.

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

LANGUAGE: shell
CODE:
```
# 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
```

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

TITLE: Buildkite Agent Start Command
DESCRIPTION: This section details the usage and options for the `buildkite-agent start` command, used to manually start an agent and register it with Buildkite.

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

LANGUAGE: APIDOC
CODE:
```
## POST /websites/buildkite

### Description
Manually start an agent and register it with Buildkite.

### Method
POST

### Endpoint
/websites/buildkite

### Parameters
#### Query Parameters
- **token** (string) - Required - Your account agent token
- **name** (string) - Optional - The name of the agent
- **priority** (string) - Optional - The priority of the agent (higher priorities are assigned work first)
- **meta-data** (string) - Optional - Meta-data for the agent (default is "queue=default")
- **meta-data-ec2** (boolean) - Optional - Include the host's EC2 meta-data (instance-id, instance-type, and ami-id) as meta-data
- **meta-data-ec2-tags** (boolean) - Optional - Include the host's EC2 tags as meta-data
- **git-clean-flags** (string) - Optional - Change flags used during Git clean
- **git-clone-flags** (string) - Optional - Change flags used during Git clone
- **bootstrap-script** (string) - Optional - Path to the bootstrap script
- **build-path** (string) - Optional - Path to where the builds will run from
- **hooks-path** (string) - Optional - Directory where the hook scripts are found
- **no-pty** (boolean) - Optional - Do not run jobs within a pseudo terminal
- **no-automatic-ssh-fingerprint-verification** (boolean) - Optional - Don't automatically verify SSH fingerprints
- **no-command-eval** (boolean) - Optional - Don't allow this agent to run arbitrary console commands
- **endpoint** (string) - Optional - The Agent API endpoint
- **no-color** (boolean) - Optional - Don't show colors in logging
- **debug** (boolean) - Optional - Enable debug mode
- **debug-http** (boolean) - Optional - Enable HTTP debug mode, which dumps all request and response bodies to the log

### Request Example
```json
{
  "command": "buildkite-agent start --token xxx --name my-agent --meta-data 'docker=true'"
}
```

### Response
#### Success Response (200)
- **status** (string) - Indicates the success status of the agent start operation.

#### Response Example
```json
{
  "status": "Agent started successfully"
}
```
```

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

TITLE: Configure npm for Buildkite Registry
DESCRIPTION: Sets up npm configuration to authenticate and publish packages to a specific Buildkite JavaScript registry. This command modifies the .npmrc file.

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

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

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

TITLE: Install Buildkite SDK with npm
DESCRIPTION: Installs the Buildkite SDK package using npm. This is the first step before using the SDK in your project.

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

LANGUAGE: bash
CODE:
```
npm install @buildkite/buildkite-sdk
```

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

TITLE: Example hostedAgents instanceShape for Linux
DESCRIPTION: Example JSON snippet demonstrating the configuration of `hostedAgents.instanceShape` for a Linux-based Buildkite hosted agent.

SOURCE: https://buildkite.com/docs/pipelines/clusters/manage-queues

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

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

TITLE: Targeting Agents with Metadata in pipeline.yml
DESCRIPTION: An example of how to target specific Buildkite agents within a pipeline.yml file based on their metadata tags. This example targets agents with the 'postgres' metadata set to '1.9.4'.

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

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

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

TITLE: Example Buildkite Pipeline with Echo Step
DESCRIPTION: An example of a simple Buildkite pipeline configuration that includes a single command step. This step will echo 'Hello' to the build log. Commit and push this pipeline.yml to trigger a new build.

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

LANGUAGE: yaml
CODE:
```
steps:
  - label: "Echo Hello"
    command: echo 'Hello'

```

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

TITLE: Git Commands for Setup
DESCRIPTION: Standard Git commands to add, commit, and push changes after installing and configuring the Buildkite Test Collector.

SOURCE: https://buildkite.com/docs/test-engine/test-collection/javascript-collectors

LANGUAGE: bash
CODE:
```
git add .

git commit -m "Install and set up Buildkite Test Engine"

git push
```

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

TITLE: Add publishConfig to package.json
DESCRIPTION: Specifies the registry URL for publishing a Node.js package. This JSON snippet should be added to the package.json file.

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

LANGUAGE: json
CODE:
```
{
  "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/"}
}
```

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

TITLE: Buildkite Agent Pipeline Upload Examples
DESCRIPTION: Examples demonstrating how to upload pipeline configurations using the Buildkite Agent. This includes uploading a default configuration file, a specified custom file, and dynamically generating steps via standard input.

SOURCE: https://buildkite.com/docs/agent/v3/cli_pipeline

LANGUAGE: bash
CODE:
```
$ buildkite-agent pipeline upload
$ buildkite-agent pipeline upload my-custom-pipeline.yml
$ ./script/dynamic_step_generator | buildkite-agent pipeline upload

```

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

TITLE: Allowlist Repositories for Cloning
DESCRIPTION: Specifies a comma-separated list of regular expressions for repositories the agent is allowed to clone. Example: "^git@github.com:buildkite/.*".

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

LANGUAGE: bash
CODE:
```
--allowed-repositories value
# Environment variable: $BUILDKITE_ALLOWED_REPOSITORIES
```

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

TITLE: Buildkite Agent Configuration File Example
DESCRIPTION: An example of a Buildkite Agent configuration file, demonstrating how to set various parameters such as agent token, name, meta-data, Git clean flags, and debug mode.

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

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

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

TITLE: Allowlist Plugins
DESCRIPTION: Specifies a comma-separated list of regular expression patterns for plugins the agent is permitted to use. Example: "^buildkite-plugins/.*$".

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

LANGUAGE: bash
CODE:
```
--allowed-plugins value
# Environment variable: $BUILDKITE_ALLOWED_PLUGINS
```

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

TITLE: Start Multiple Buildkite Agents on One Machine
DESCRIPTION: This command starts multiple Buildkite agents on a single machine, allowing them to run jobs concurrently. The `--spawn` flag specifies the number of agents to start. Each agent can pick up and execute a job independently.

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

LANGUAGE: bash
CODE:
```
buildkite-agent start --spawn 5
```

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

TITLE: Run RSpec Tests
DESCRIPTION: Executes the RSpec tests within the cloned Ruby project. This command is used to verify that the RSpec test runner functions correctly.

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

LANGUAGE: bash
CODE:
```
rspec
```

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

TITLE: PowerShell Pipeline Example for Buildkite
DESCRIPTION: This snippet shows a pipeline definition using PowerShell for Buildkite. It mirrors the Bash example by uploading the pipeline definition and executing a script.

SOURCE: https://buildkite.com/docs/pipelines/getting-started

LANGUAGE: powershell
CODE:
```
pipeline {
  agent {
    queue "build"
  }
  steps {
    script {
      name "=script"
      command "Write-Host \"Hello from Buildkite!\""
    }
  }
}

```

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

TITLE: Download Artifacts with Buildkite Agent CLI
DESCRIPTION: Demonstrates how to download artifacts using the `buildkite-agent artifact download` command. It includes examples for handling ambiguous file names by specifying the step or build, and for including artifacts from retried jobs.

SOURCE: https://buildkite.com/docs/guides/artifacts

LANGUAGE: bash
CODE:
```
buildkite-agent artifact download --step "your-step-slug" "path/to/artifact.txt"
buildkite-agent artifact download --build "your-build-id" "path/to/artifact.txt"
buildkite-agent artifact download --include-retried-jobs "path/to/artifact.txt"
```

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

TITLE: Targeting Agents with Specific Metadata in pipeline.yml
DESCRIPTION: Provides an example of how to target specific Buildkite agents within a `pipeline.yml` file using agent query rules based on metadata. This example targets agents with the 'postgres' metadata set to '1.9.4'.

SOURCE: https://buildkite.com/docs/agent/v2/agent-meta-data

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

```

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

TITLE: Configure multiple Buildkite Agents (upstart)
DESCRIPTION: Sets up additional Buildkite agent instances on Debian 7.x by copying the upstart configuration file and starting the new service.

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

LANGUAGE: bash
CODE:
```
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
```

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

TITLE: EC2 Mac Setup: Homebrew Paths by Architecture
DESCRIPTION: Illustrates the different default Homebrew installation paths based on the EC2 Mac instance's CPU architecture (Apple Silicon vs. Intel). Crucial for UserData scripts.

SOURCE: https://buildkite.com/docs/agent/v3/aws/elastic-ci-stack/ec2-mac/setup

LANGUAGE: bash
CODE:
```
# Apple Silicon (ARM):
/opt/homebrew/bin

# Intel (x86):
/usr/local/bin
```

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

TITLE: Install Buildkite Agent as a Service using NSSM (Commands)
DESCRIPTION: Installs the Buildkite Agent as a Windows service using NSSM commands. It specifies the executable path, application parameters (including queue), and log file locations for standard output and error. Requires administrator privileges.

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

LANGUAGE: bash
CODE:
```
# 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"

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

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

TITLE: Buildkite Pipeline JSON Response Example
DESCRIPTION: An example of a JSON response representing a Buildkite pipeline, including its ID, URLs, name, repository settings, branching configurations, and build-related counts. It also shows provider-specific settings and a detailed steps configuration.

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

LANGUAGE: json
CODE:
```
{
  "id": "14e9501c-69fe-4cda-ae07-daea9ca3afd3",
  "graphql_id": "UGlwZWxpbmUtLS1lOTM4ZGQxYy03MDgwLTQ4ZmQtOGQyMC0yNmQ4M2E0ZjNkNDg=",
  "url": "https://api.buildkite.com/v2/organizations/acme-inc/pipelines/my-pipeline",
  "web_url": "https://buildkite.com/acme-inc/my-pipeline",
  "name": "My Pipeline",
  "description": null,
  "slug": "my-pipeline",
  "repository": "git@github.com:acme-inc/new-repo.git",
  "branch_configuration": "main",
  "default_branch": "main",
  "provider": {
    "id": "github",
    "webhook_url": "https://webhook.buildkite.com/deliver/xxx",
    "settings": {
      "publish_commit_status": true,
      "build_pull_requests": true,
      "build_pull_request_forks": false,
      "build_tags": false,
      "publish_commit_status_per_step": false,
      "repository": "acme-inc/new-repo",
      "trigger_mode": "code"
    }
  },
  "skip_queued_branch_builds": false,
  "skip_queued_branch_branch_builds_filter": null,
  "cancel_running_branch_builds": false,
  "cancel_running_branch_builds_filter": null,
  "builds_url": "https://api.buildkite.com/v2/organizations/acme-inc/pipelines/my-pipeline/builds",
  "badge_url": "https://badge.buildkite.com/58b3da999635d0ad2daae5f784e56d264343eb02526f129bfb.svg",
  "created_at": "2015-03-01 06:44:40 UTC",
  "archived_at": "2021-06-01 08:23:35 UTC",
  "configuration": "steps:\n  - command: \"new.sh\"\n    agents:\n    - \"something=true\"",
  "steps": [
    {
      "type": "script",
      "name": null,
      "command": "new.sh",
      "artifact_paths": null,
      "branch_configuration": null,
      "env": {},
      "timeout_in_minutes": null,
      "agent_query_rules": [
        "myqueue=true"
      ],
      "concurrency": null,
      "parallelism": null
    }
  ],
  "env": {
  },
  "scheduled_builds_count": 0,
  "running_builds_count": 0,
  "scheduled_jobs_count": 0,
  "running_jobs_count": 0,
  "waiting_jobs_count": 0,
  "visibility": "private"
}
```

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

TITLE: Start and Monitor Buildkite Agent (non-systemd)
DESCRIPTION: Starts the Buildkite Agent service on systems without systemd, such as older Amazon Linux versions. It then tails the agent's log file.

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

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

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

TITLE: Run RSpec tests with Buildkite Analytics Token and Message
DESCRIPTION: This RSpec command executes tests and sends execution data to Buildkite Test Engine. It requires the BUILDKITE_ANALYTICS_TOKEN and optionally uses BUILDKITE_ANALYTICS_MESSAGE to describe the test run. This is useful for CI/CD environments and manual builds.

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

LANGUAGE: shell
CODE:
```
BUILDKITE_ANALYTICS_TOKEN=<api-token-value> BUILDKITE_ANALYTICS_MESSAGE="My first test run" rspec
```

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

TITLE: Customizing Buildkite Commit Statuses in pipeline.yml
DESCRIPTION: This example demonstrates how to customize commit statuses in Buildkite using the `notify` attribute within a `pipeline.yml` file. This allows for more granular control over how build statuses are reported on GitHub, especially in monorepo setups.

SOURCE: https://buildkite.com/docs/pipelines/source-control/github

LANGUAGE: yaml
CODE:
```
steps:
  - label: ":pipeline: Build main branch"
    key: "main_build"
    command: "./build.sh"
    notify:
      - url: "${BUILDKITE_API_ACCESS_TOKEN}"
        method: "post"
        body: |
          {
            "commit": "${BUILDKITE_COMMIT}",
            "message": "Buildkite build finished.",
            "state": "${BUILDKITE_BUILD_STATE}",
            "branch": "${BUILDKITE_BRANCH}",
            "build_url": "${BUILDKITE_BUILD_URL}",
            "org": "${BUILDKITE_ORGANIZATION_SLUG}",
            "pipeline": "${BUILDKITE_PIPELINE_SLUG}",
            "commit_message": "${BUILDKITE_MESSAGE}",
            "author_name": "${BUILDKITE_AUTHOR}",
            "author_email": "${BUILDKITE_AUTHOR_EMAIL}",
            "label": "custom-build-status"
          }

```

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

TITLE: Multi-Language Project Analysis Setup (Buildkite YAML)
DESCRIPTION: Provides a Buildkite pipeline configuration for analyzing a multi-language project. It includes a setup step and a sonar-cloud analysis step that waits for the scanner and executes the analysis using properties files.

SOURCE: https://buildkite.com/docs/pipelines/integrations/security-and-compliance/sonar

LANGUAGE: yaml
CODE:
```
steps:
  - label: "📥 Setup"
    command: |
      echo "🏗️  Multi-Language SonarScanner Analysis"
      echo "🎯 Analyzing 20+ language samples..."
  - label: "🔍 SonarCloud Analysis"
    command: |
      # Wait for sonar-scanner availability (Elastic CI Stack for AWS)
      echo "⏳ Ensuring sonar-scanner is ready..."
      timeout 30 bash -c 'while [[ ! -x "/opt/sonar-scanner/bin/sonar-scanner" ]]; do sleep 5; done' || {
        echo "❌ Error: SonarScanner binary not ready after 30 seconds"
        echo "Check that SonarScanner is properly installed on your agents"
        exit 1
      }

      # Run analysis using properties file configuration
      /opt/sonar-scanner/bin/sonar-scanner
      echo "✅ Analysis completed successfully"
    plugins:
      - seek-oss/aws-sm#v2.3.3:
          env:
            SONAR_TOKEN: my-org/sonar-token
    # If using Docker
    #   - docker#v5.11.0:
    #       image: "sonarsource/sonar-scanner-cli:latest"
    #       environment:
    #         - "SONAR_TOKEN"
    #       propagate-environment: true
```

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

TITLE: Buildkite API Response Example
DESCRIPTION: An example JSON response from the Buildkite API, showing details about a pipeline including URLs, creation timestamp, and counts of scheduled, running, and waiting builds and jobs.

SOURCE: https://buildkite.com/docs/api/builds

LANGUAGE: json
CODE:
```
{
    "builds_url": "https://api.buildkite.com/v2/organizations/my-great-org/pipelines/my-pipeline/builds",
    "badge_url": "https://badge.buildkite.com/58b3da999635d0ad2daae5f784e56d264343eb02526f129bfb.svg",
    "created_at": "2013-09-03 13:24:38 UTC",
    "scheduled_builds_count": 0,
    "running_builds_count": 0,
    "scheduled_jobs_count": 0,
    "running_jobs_count": 0,
    "waiting_jobs_count": 0
  }
}
```

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

TITLE: Configure a simple Buildkite plugin with minimal options
DESCRIPTION: Illustrates the basic configuration of a Buildkite plugin that requires no specific options. The 'library-example#v1.0.0' plugin is used with a '~' indicating no further configuration is needed for this simple case.

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

LANGUAGE: yaml
CODE:
```
steps:
  - label: ":books:"
    plugins:
      - library-example#v1.0.0: ~
```

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

TITLE: Install bktec on Debian
DESCRIPTION: Installs the Test Engine Client (bktec) on Debian-based systems. It first updates the package list and installs curl and gpg, then adds the Buildkite signing key and configures the APT repository before installing the bktec package.

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

LANGUAGE: bash
CODE:
```
apt update && apt install curl gpg -y
```

LANGUAGE: bash
CODE:
```
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
```

LANGUAGE: bash
CODE:
```
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
```

LANGUAGE: bash
CODE:
```
apt update && apt install bktec
```

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

TITLE: Download and Install Buildkite Agent
DESCRIPTION: Downloads and installs the Buildkite Agent using a script from GitHub. Requires an agent token to be provided.

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

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

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

TITLE: Example Binary Polyglot Hook (Go)
DESCRIPTION: Illustrates a binary polyglot hook compiled from Go. This hook is executed directly by the operating system. It requires the Go compiler to be installed on the agent and the binary to be compiled for the correct OS and architecture. Hooks must not have a file extension, except on Windows where it must be '.exe'.

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

LANGUAGE: go
CODE:
```
package main

import (
	"fmt"
	"os"
)

func main() {
	// Access environment variables set by Buildkite
	builtdkiteHookPhase := os.Getenv("BUILDKITE_HOOK_PHASE")
	builtdkiteHookPath := os.Getenv("BUILDKITE_HOOK_PATH")

	fmt.Printf("Running hook in phase: %s\n", builtdkiteHookPhase)
	fmt.Printf("Hook path: %s\n", builtdkiteHookPath)

	// Add your Go program logic here.
	fmt.Println("Go binary hook executed.")
}

```

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

TITLE: Packer Build Commands with Environment Variables
DESCRIPTION: Demonstrates how to execute Packer builds for different AMI variants using make commands. Shows how to override default AWS settings like region and profile, and specify instance types for ARM64 and AMD64 architectures.

SOURCE: https://buildkite.com/docs/quickstart/elastic-ci-stack-aws

LANGUAGE: bash
CODE:
```
# Build all AMI variants
make packer

# Build Amazon Linux 2023 (64-bit x86) AMI only
make packer-linux-amd64.output

# Build Amazon Linux 2023 (64-bit ARM, Graviton) AMI only
make packer-linux-arm64.output

# Build Windows Server 2019 (64-bit x86) AMI only
make packer-windows-amd64.output

# Example: Build AMD64 Linux image in eu-west-1 with specific instance type and profile
AMD64_INSTANCE_TYPE="t3.medium" \
AWS_REGION="eu-west-1" \
AWS_PROFILE="assets-profile" \
make packer-linux-amd64.output
```

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

TITLE: Example: Go Binary Hook
DESCRIPTION: This example illustrates a binary hook written in Go. Binary hooks are compiled executables and must be placed in the agent's hooks directory without a file extension (except for Windows, which requires '.exe'). The Go binary needs to be compiled for the correct OS and architecture.

SOURCE: https://buildkite.com/docs/agent/hooks

LANGUAGE: go
CODE:
```
package main

import (
	"fmt"
	"os"
)

func main() {
	phase := os.Getenv("BUILDKITE_HOOK_PHASE")
	if phase == ""
		phase = "unknown"

	fmt.Printf("Running Go binary hook for phase: %s\n", phase)

	// Add your Go-specific logic here
	sswitch phase {
	case "environment":
		fmt.Println("Setting up environment...")
		// Example: Modify environment variables using Buildkite's Job API (not shown here)
	case "post-checkout":
		fmt.Println("Post-checkout tasks...")
	default:
		fmt.Println("Unknown phase.")
	}
}

```