buildkite · dannymidnight · Feb 15, 2024 · Feb 15, 2024 · Feb 15, 2024 · Feb 15, 2024
diff --git a/.prettierrc b/.prettierrc
@@ -0,0 +1,4 @@
+overrides:
+  - files: "*.md"
+    options:
+      tabWidth: 4
diff --git a/package.json b/package.json
@@ -15,8 +15,8 @@
     "lint": "npx alex@10 -q --diff \"pages/**/*.erb\" \"pages/**/*.txt\"",
     "mdlint": "npx markdownlint-cli2@0.3 pages \"#pages/agent/v3/help/*\"",
     "prepare": "husky install",
-    "prettier-check": "prettier -c \"app/frontend/**/*.{js,scss}\"",
-    "prettier-fix": "prettier -w \"app/frontend/**/*.{js,scss}\""
+    "prettier-check": "prettier -c \"app/frontend/**/*.{js,scss}\" -w \"pages/**/*.md\"",
+    "prettier-fix": "prettier -w \"app/frontend/**/*.{js,scss}\" -w \"pages/**/*.md\""
   },
   "dependencies": {
     "@docsearch/js": "3",

@@ -1,13 +1,12 @@
 # The Buildkite Agent
 
->🚧 This page references the out-of-date Buildkite Agent v2.
+> 🚧 This page references the out-of-date Buildkite Agent v2.
 > For docs referencing the Buildkite Agent v3, <a href="/docs/agent/v3">see the latest version of this document</a>.
 
 <!--alex ignore easy-->
 
 The Buildkite agent is a small, reliable and cross-platform build runner that makes it easy to run automated builds on your own infrastructure. Its main responsibilities are polling buildkite.com for work, running build jobs, reporting back the status code and output log of the job, and uploading the job's artifacts.
 
-
 ## How it works
 
 The agent works by polling Buildkite's agent API over HTTPS. There is no need to forward ports or provide incoming firewall access, and the agents can be run across any number of machines and networks.
@@ -30,15 +29,15 @@ You can install the agent on a wide variety of platforms, see the [installation
   <pre class="highlight shell"><code>$ buildkite-agent --help
 Usage:
 
-  buildkite-agent <command> [arguments...]
+buildkite-agent <command> [arguments...]
 
 Available commands are:
 
-  <a href="/docs/agent/v2/cli-start">start</a>       Starts a Buildkite agent
-  <a href="/docs/agent/v2/cli-artifact">artifact</a>    Upload/download artifacts from Buildkite jobs
-  <a href="/docs/agent/v2/cli-meta-data">meta-data</a>   Get/set data from Buildkite jobs
-  <a href="/docs/agent/v3/cli-pipeline">pipeline</a>   Make changes to the pipeline of the currently running build
-  help, h     Shows a list of commands or help for one command
+<a href="/docs/agent/v2/cli-start">start</a> Starts a Buildkite agent
+<a href="/docs/agent/v2/cli-artifact">artifact</a> Upload/download artifacts from Buildkite jobs
+<a href="/docs/agent/v2/cli-meta-data">meta-data</a> Get/set data from Buildkite jobs
+<a href="/docs/agent/v3/cli-pipeline">pipeline</a> 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.
 </code></pre></div>

@@ -1,9 +1,9 @@
-* Configuration: `/etc/buildkite-agent/buildkite-agent.cfg`
-* Agent Hooks: `/etc/buildkite-agent/hooks/`
-* Builds: `/var/lib/buildkite-agent/builds/`
-* Logs, depending on your system:
-  - `journalctl -f -u buildkite-agent` (systemd)
-  - `/var/log/upstart/buildkite-agent.log` (upstart)
-  - `/var/log/buildkite-agent.log` (older systems)
-* Agent user home: `/var/lib/buildkite-agent/`
-* SSH keys: `/var/lib/buildkite-agent/.ssh/`
+-   Configuration: `/etc/buildkite-agent/buildkite-agent.cfg`
+-   Agent Hooks: `/etc/buildkite-agent/hooks/`
+-   Builds: `/var/lib/buildkite-agent/builds/`
+-   Logs, depending on your system:
+    -   `journalctl -f -u buildkite-agent` (systemd)
+    -   `/var/log/upstart/buildkite-agent.log` (upstart)
+    -   `/var/log/buildkite-agent.log` (older systems)
+-   Agent user home: `/var/lib/buildkite-agent/`
+-   SSH keys: `/var/lib/buildkite-agent/.ssh/`
@@ -1,11 +1,10 @@
 # Running Buildkite Agent on AWS
 
->🚧 This page references the out-of-date Buildkite Agent v2.
+> 🚧 This page references the out-of-date Buildkite Agent v2.
 > For docs referencing the Buildkite Agent v3, <a href="/docs/agent/v3/aws">see the latest version of this document</a>.
 
 The Buildkite Agent can be run on AWS using our Elastic CI Stack for AWS.
 
-
 ## Install the agent on your own AWS instance
 
 To run the agent on your own AWS instances use whichever installer matches your
@@ -21,5 +20,5 @@ parallelizing large legacy test suites, testing any Linux-based project that can
 [Read the documentation][github] on GitHub, and launch it using the
 button on your organization's Agents page.
 
-   [github]: https://github.com/buildkite/elastic-ci-stack-for-aws
-   [Red Hat/CentOS installer]: /docs/agent/v2/redhat
+[github]: https://github.com/buildkite/elastic-ci-stack-for-aws
+[Red Hat/CentOS installer]: /docs/agent/v2/redhat
@@ -1,13 +1,12 @@
 # `buildkite-agent artifact`
 
->🚧 This page references the out-of-date Buildkite Agent v2.
+> 🚧 This page references the out-of-date Buildkite Agent v2.
 > For docs referencing the Buildkite Agent v3, <a href="/docs/agent/v3/cli_artifact">see the latest version of this document</a>.
 
 The Buildkite Agent's `artifact` command provides support for uploading and downloading of build artifacts, allowing you to share binary data between build steps no matter the machine or network.
 
 See the [Using build artifacts](/docs/builds/artifacts) guide for a step-by-step example.
 
-
 ## Uploading artifacts
 
 You can use this command in your build scripts to store artifacts in the Buildkite artifact store. The stored artifacts will then be accessible using the web interface and can be downloaded by future build steps.
@@ -100,15 +99,14 @@ buildkite-agent artifact upload test.log
 
 Keep in mind while you're writing your path pattern:
 
-- patterns must match whole path strings, not only substrings
-- there are two wildcards available that match non-separator characters (on Linux `/` is a separator character, and on Windows `\` is a separator character):
-  + `*` to match a sequence of characters
-  + `?` to match a single character
-- character ranges surrounded by `[]` support the `^` as a negator
-- special characters can be escaped with `\\`
-- multiple paths are separated with `;`
-- surround the pattern with quotes
-
+-   patterns must match whole path strings, not only substrings
+-   there are two wildcards available that match non-separator characters (on Linux `/` is a separator character, and on Windows `\` is a separator character):
+    -   `*` to match a sequence of characters
+    -   `?` to match a single character
+-   character ranges surrounded by `[]` support the `^` as a negator
+-   special characters can be escaped with `\\`
+-   multiple paths are separated with `;`
+-   surround the pattern with quotes
 
 ## Downloading artifacts
 
@@ -271,8 +269,8 @@ You will need to make sure your agent instances have the following IAM policy to
                 "s3:PutObjectVersionAcl"
             ],
             "Resource": [
-               "arn\:aws\:s3:::my-s3-bucket",
-               "arn\:aws\:s3:::my-s3-bucket/*"
+                "arn:aws:s3:::my-s3-bucket",
+                "arn:aws:s3:::my-s3-bucket/*"
             ]
         }
     ]

@@ -1,13 +1,12 @@
 # `buildkite-agent meta-data`
 
->🚧 This page references the out-of-date Buildkite Agent v2.
+> 🚧 This page references the out-of-date Buildkite Agent v2.
 > For docs referencing the Buildkite Agent v3, <a href="/docs/agent/v3/cli_meta_data">see the latest version of this document</a>.
 
 The Buildkite Agent's `meta-data` command provides your build pipeline with a powerful key/value data-store that works across build steps and build agents, no matter the machine or network.
 
 See the [Using build meta-data](/docs/pipelines/build-meta-data) guide for a step-by-step example.
 
-
 ## Setting data
 
 Use this command in your build scripts to save string data in the Buildkite meta-data store.

@@ -1,13 +1,12 @@
 # `buildkite-agent pipeline`
 
->🚧 This page references the out-of-date Buildkite Agent v2.
+> 🚧 This page references the out-of-date Buildkite Agent v2.
 > For docs referencing the Buildkite Agent v3, <a href="/docs/agent/v3/cli_pipeline">see the latest version of this document</a>.
 
 The Buildkite Agent's `pipeline` command allows you to add and replace build steps in the running build. The steps are defined using YAML or JSON and can be read from a file or streamed from the output of a script.
 
 See the [Defining your pipeline steps](/docs/pipelines/uploading-pipelines) guide for a step-by-step example and list of step types.
 
-
 ## Uploading pipelines
 
 ```
@@ -48,8 +47,8 @@ Options:
 
 The pipeline can be written as YAML or JSON, but YAML is more common for its readability. There are two top level properties you can specify:
 
-* `env` - A map of <a href="/docs/pipelines/environment-variables">environment variables</a> to apply to all steps
-* `steps` - A list of [build pipeline steps](/docs/pipelines/defining-steps)
+-   `env` - A map of <a href="/docs/pipelines/environment-variables">environment variables</a> to apply to all steps
+-   `steps` - A list of [build pipeline steps](/docs/pipelines/defining-steps)
 
 ## Environment variable substitution
 
@@ -76,13 +75,13 @@ You can set required environment variables using the syntax `${VAR?}`. If `VAR`
 For example, the following step will cause the pipeline upload to error if the `SERVER` environment variable has not been set:
 
 ```yaml
-- command: "deploy.sh \"${SERVER?}\""
+- command: 'deploy.sh "${SERVER?}"'
 ```
 
 You can set a custom error message after the `?` character. For example, the following prints the error message `SERVER: is not set. Please specify a server` if the environment variable has not been set:
 
 ```yaml
-- command: "deploy.sh \"${SERVER?is not set. Please specify a server}\""
+- command: 'deploy.sh "${SERVER?is not set. Please specify a server}"'
 ```
 
 ### Default, blank and missing values
@@ -92,7 +91,7 @@ If an environment variable has not been set it will evaluate to a blank string.
 For example, the following step will run the command `deploy.sh staging`:
 
 ```yaml
-- command: "deploy.sh \"${SERVER:-staging}\""
+- command: 'deploy.sh "${SERVER:-staging}"'
 ```
 
 <table>
@@ -126,7 +125,7 @@ You can substitute a subset of characters from an environment variable by specif
 For example, the following step will echo the first 7 characters of the `BUILDKITE_COMMIT` environment variable:
 
 ```yaml
-- command: "echo \"Short commit is: ${BUILDKITE_COMMIT:0:7}\""
+- command: 'echo "Short commit is: ${BUILDKITE_COMMIT:0:7}"'
 ```
 
 If the environment variable has not been set, the range will return a blank string.
@@ -1,11 +1,10 @@
 # `buildkite-agent start`
 
->🚧 This page references the out-of-date Buildkite Agent v2.
+> 🚧 This page references the out-of-date Buildkite Agent v2.
 > For docs referencing the Buildkite Agent v3, <a href="/docs/agent/v3/cli_start">see the latest version of this document</a>.
 
 The Buildkite Agent's `start` command is used to manually start an agent and register it with Buildkite.
 
-
 ## Starting an agent
 
 ```
@@ -83,9 +82,9 @@ To do this from [uploaded pipeline.yml](/docs/agent/v2/cli-pipeline) you would d
 
 ```yaml
 steps:
-  - command: "script.sh"
-    agents:
-      postgres: "1.9.4"
+    - command: "script.sh"
+      agents:
+          postgres: "1.9.4"
 ```
 
 You can also match for any agent with a `postgres` meta-data by omitting the value after the `=` sign, or by using `*`, for example:
@@ -96,9 +95,9 @@ To do this from an [uploaded pipeline.yml](/docs/agent/v2/cli-pipeline) you woul
 
 ```yaml
 steps:
-  - command: "script.sh"
-    agents:
-      postgres: '*'
+    - command: "script.sh"
+      agents:
+          postgres: "*"
 ```
 
 Partial wildcard matching (for example, `postgres=1.9*` or `postgres=*1.9`) is not yet supported.

@@ -1,13 +1,12 @@
 # Buildkite Agent configuration
 
->🚧 This page references the out-of-date Buildkite Agent v2.
+> 🚧 This page references the out-of-date Buildkite Agent v2.
 > For docs referencing the Buildkite Agent v3, <a href="/docs/agent/v3/configuration">see the latest version of this document</a>.
 
 Every agent installer comes with a configuration file. You can also customize many of the configuration values using environment variables.
 
 You can find the location of your configuration file in your platform's installation documentation, or you can set it using the `BUILDKITE_AGENT_CONFIG` environment variable or the `--config` command line argument.
 
-
 ## Configuration settings
 
 `token`<br>

@@ -1,11 +1,10 @@
 # Installing Buildkite Agent on Debian
 
->🚧 This page references the out-of-date Buildkite Agent v2.
+> 🚧 This page references the out-of-date Buildkite Agent v2.
 > For docs referencing the Buildkite Agent v3, <a href="/docs/agent/v3/debian">see the latest version of this document</a>.
 
 The Buildkite Agent can be installed on Debian versions 7.x and 8.x using our signed apt repository.
 
-
 ## Installation
 
 Firstly, ensure your list of packages is up to date:
@@ -14,7 +13,7 @@ Firstly, ensure your list of packages is up to date:
 sudo apt-get update
 ```
 
->📘
+> 📘
 > Debian doesn't always have <code>sudo</code> available, so you can run these commands as root and omit the <code>sudo</code>, or install the sudo package as root first.
 
 Next, ensure you have the `apt-transport-https` package installed for the HTTPS package repository, and the `dirmngr` package installed for adding the signing key:

@@ -1,14 +1,13 @@
 # Running Buildkite Agent with Docker
 
->🚧 This page references the out-of-date Buildkite Agent v2.
+> 🚧 This page references the out-of-date Buildkite Agent v2.
 > For docs referencing the Buildkite Agent v3, <a href="/docs/agent/v3/docker">see the latest version of this document</a>.
 
 You can run the Buildkite Agent inside a Docker container using the official Docker images.
 
->📘 Running each build in its own container
+> 📘 Running each build in its own container
 > These instructions cover how to run the agent using Docker. If you want to learn how to isolate each build using Docker and any of our standard Linux-based installers read the <a href="/docs/tutorials/docker-containerized-builds">Docker-Based Builds</a> guide.
 
-
 ## Running using Docker
 
 Start an agent with the [official image](https://hub.docker.com/r/buildkite/agent/) based on Alpine Linux:

@@ -1,11 +1,10 @@
 # Installing Buildkite Agent on FreeBSD
 
->🚧 This page references the out-of-date Buildkite Agent v2.
+> 🚧 This page references the out-of-date Buildkite Agent v2.
 > For docs referencing the Buildkite Agent v3, <a href="/docs/agent/v3/freebsd">see the latest version of this document</a>.
 
 You can install Buildkite Agent on most FreeBSD systems.
 
-
 ## Installation
 
 You first need to ensure that both `git` and `bash` are installed on your server:
@@ -52,10 +51,10 @@ See the [Agent SSH keys](/docs/agent/v2/ssh-keys) documentation for more details
 
 ## File locations
 
-* Configuration: `~/.buildkite-agent/buildkite-agent.cfg`
-* Agent Hooks: `~/.buildkite-agent/hooks`
-* Builds: `~/.buildkite-agent/builds`
-* SSH keys: `~/.ssh`
+-   Configuration: `~/.buildkite-agent/buildkite-agent.cfg`
+-   Agent Hooks: `~/.buildkite-agent/hooks`
+-   Builds: `~/.buildkite-agent/builds`
+-   SSH keys: `~/.ssh`
 
 ## Configuration
 

@@ -1,11 +1,10 @@
 # Running Buildkite Agent on Google Cloud Platform
 
->🚧 This page references the out-of-date Buildkite Agent v2.
+> 🚧 This page references the out-of-date Buildkite Agent v2.
 > For docs referencing the Buildkite Agent v3, <a href="/docs/agent/v3/gcloud">see the latest version of this document</a>.
 
 The Buildkite Agent can be run on [Google Cloud Platform](https://cloud.google.com). For fine control over long–lived agents, you might like to run the agent using individual VM instances on Google Compute Engine. Or run Docker–based builds using a scalable cluster of agents on the Google Kubernetes Engine using Kubernetes.
 
-
 ## Running the agent on Google Compute Engine
 
 To run the agent on your own [Google Compute Engine](https://cloud.google.com/compute) instance use whichever installer matches your instance type. For example:

@@ -1,14 +1,13 @@
 # GitHub SSH keys
 
->🚧 This page references the out-of-date Buildkite Agent v2.
+> 🚧 This page references the out-of-date Buildkite Agent v2.
 > For docs referencing the Buildkite Agent v3, <a href="/docs/agent/v3/github_ssh_keys">see the latest version of this document</a>.
 
 The Buildkite Agent clones your source code directly from GitHub or GitHub Enterprise. The easiest way to provide it with access is by creating a “Buildkite Agent” machine user in your organization, and adding it to a team that has access to the relevant repositories.
 
->📘
+> 📘
 > If you're running a build agent on a local development machine which already has access to GitHub then you can skip this setup and start running builds.
 
-
 ## Method 1: Machine user
 
 Creating a [machine user](https://developer.github.com/guides/managing-deploy-keys/#machine-users) is the simplest way to create a single SSH key which provides access to your organization's repositories.
@@ -17,15 +16,15 @@ The easiest way to do this is by creating a “Buildkite Agent” machine user i
 
 To setup a GitHub machine user:
 
-* On your agent machine, generate a key as per the [agent SSH keys documentation](/docs/agent/v2/ssh-keys#creating-a-single-ssh-key)
-* Sign up to GitHub as a new user (using a valid email address), and add the SSH key to the user's settings
-* Sign back into GitHub as an organization admin, create a new team, then add the new user and any required repositories to the team
+-   On your agent machine, generate a key as per the [agent SSH keys documentation](/docs/agent/v2/ssh-keys#creating-a-single-ssh-key)
+-   Sign up to GitHub as a new user (using a valid email address), and add the SSH key to the user's settings
+-   Sign back into GitHub as an organization admin, create a new team, then add the new user and any required repositories to the team
 
 ## Method 2: Deploy keys
 
 An alternative method of providing access to your repositories is to use deploy keys. The advantage of deploy keys is they can provide read-only access to your source code, but the disadvantage is that you'll have to configure ssh on your build agents to handle multiple keys.
 
 To setup GitHub deploy keys with the Buildkite Agent, you'll need to do the following for each repository:
 
-* On your agent machine, generate a key as per the [agent SSH keys documentation](/docs/agent/v2/ssh- keys#creating-multiple-ssh-keys)
-* In GitHub, copy the key into the repository's “Deploy keys” settings
+-   On your agent machine, generate a key as per the [agent SSH keys documentation](/docs/agent/v2/ssh- keys#creating-multiple-ssh-keys)
+-   In GitHub, copy the key into the repository's “Deploy keys” settings