Merge pull request #97 from buildkite/agent-v3.84.0

Update agent docs for v3.84.0

data/nav.yml

@@ -157,6 +157,8 @@
               path: "agent/v3/cli-artifact"
             - name: "bootstrap"
               path: "agent/v3/cli-bootstrap"
+            - name: "build"
+              path: "agent/v3/cli-build"
             - name: "env"
               path: "agent/v3/cli-env"
             - name: "lock"

pages/agent/v3/cli_build.md

@@ -0,0 +1,7 @@
+# buildkite-agent build
+
+The Buildkite Agent's `build` subcommands provide the ability to control builds.
+
+## Canceling a build
+
+<%= render 'agent/v3/help/build_cancel' %>

pages/agent/v3/help/_build_cancel.md

@@ -0,0 +1,47 @@
+<!--
+  _____   ____    _   _  ____ _______   ______ _____ _____ _______
+ |  __ \ / __ \  | \ | |/ __ \__   __| |  ____|  __ \_   _|__   __|
+ | |  | | |  | | |  \| | |  | | | |    | |__  | |  | || |    | |
+ | |  | | |  | | | . ` | |  | | | |    |  __| | |  | || |    | |
+ | |__| | |__| | | |\  | |__| | | |    | |____| |__| || |_   | |
+ |_____/ \____/  |_| \_|\____/  |_|    |______|_____/_____|  |_|
+
+This file is auto-generated by scripts/update-agent-help.sh, please update the
+agent CLI help in https://github.com/buildkite/agent and run the generation
+script.
+
+-->
+
+### Usage
+
+`buildkite-agent build cancel [options...]`
+
+### Description
+
+Cancel a running build.
+
+### Example
+
+```shell
+# Cancels the current build
+$ buildkite-agent build cancel
+```
+
+### Options
+
+<!-- vale off -->
+
+<table class="Docs__attribute__table">
+<tr id="build"><th><code>--build value</code> <a class="Docs__attribute__link" href="#build">#</a></th><td><p>The build UUID to cancel<br /><strong>Environment variable</strong>: <code>$BUILDKITE_BUILD_ID</code></p></td></tr>
+<tr id="agent-access-token"><th><code>--agent-access-token value</code> <a class="Docs__attribute__link" href="#agent-access-token">#</a></th><td><p>The access token used to identify the agent<br /><strong>Environment variable</strong>: <code>$BUILDKITE_AGENT_ACCESS_TOKEN</code></p></td></tr>
+<tr id="endpoint"><th><code>--endpoint value</code> <a class="Docs__attribute__link" href="#endpoint">#</a></th><td><p>The Agent API endpoint (default: "<code>https://agent.buildkite.com/v3</code>")<br /><strong>Environment variable</strong>: <code>$BUILDKITE_AGENT_ENDPOINT</code></p></td></tr>
+<tr id="no-http2"><th><code>--no-http2 </code> <a class="Docs__attribute__link" href="#no-http2">#</a></th><td><p>Disable HTTP2 when communicating with the Agent API.<br /><strong>Environment variable</strong>: <code>$BUILDKITE_NO_HTTP2</code></p></td></tr>
+<tr id="debug-http"><th><code>--debug-http </code> <a class="Docs__attribute__link" href="#debug-http">#</a></th><td><p>Enable HTTP debug mode, which dumps all request and response bodies to the log<br /><strong>Environment variable</strong>: <code>$BUILDKITE_AGENT_DEBUG_HTTP</code></p></td></tr>
+<tr id="no-color"><th><code>--no-color </code> <a class="Docs__attribute__link" href="#no-color">#</a></th><td><p>Don't show colors in logging<br /><strong>Environment variable</strong>: <code>$BUILDKITE_AGENT_NO_COLOR</code></p></td></tr>
+<tr id="debug"><th><code>--debug </code> <a class="Docs__attribute__link" href="#debug">#</a></th><td><p>Enable debug mode. Synonym for `--log-level debug`. Takes precedence over `--log-level`<br /><strong>Environment variable</strong>: <code>$BUILDKITE_AGENT_DEBUG</code></p></td></tr>
+<tr id="log-level"><th><code>--log-level value</code> <a class="Docs__attribute__link" href="#log-level">#</a></th><td><p>Set the log level for the agent, making logging more or less verbose. Defaults to notice. Allowed values are: debug, info, error, warn, fatal (default: "notice")<br /><strong>Environment variable</strong>: <code>$BUILDKITE_AGENT_LOG_LEVEL</code></p></td></tr>
+<tr id="experiment"><th><code>--experiment value</code> <a class="Docs__attribute__link" href="#experiment">#</a></th><td><p>Enable experimental features within the buildkite-agent<br /><strong>Environment variable</strong>: <code>$BUILDKITE_AGENT_EXPERIMENT</code></p></td></tr>
+<tr id="profile"><th><code>--profile value</code> <a class="Docs__attribute__link" href="#profile">#</a></th><td><p>Enable a profiling mode, either cpu, memory, mutex or block<br /><strong>Environment variable</strong>: <code>$BUILDKITE_AGENT_PROFILE</code></p></td></tr>
+</table>
+
+<!-- vale on -->

pages/agent/v3/help/_redactor_add.md

@@ -44,21 +44,21 @@ JSON object file (for example, 'my-secrets.json'), with multiple "k
 one for each secret:
 
 ```shell
-$ echo '{"key":"secret1","key":"secret2"}' | buildkite-agent redactor add --format=json
+$ echo '{"key":"secret1","key":"secret2"}' | buildkite-agent redactor add --format json
 ```
 
 Or
 
 ```shell
-$ buildkite-agent redactor add --format=json my-secrets.json
+$ buildkite-agent redactor add --format json my-secrets.json
 ```
 
 ### Options
 
 <!-- vale off -->
 
 <table class="Docs__attribute__table">
-<tr id="format"><th><code>--format value</code> <a class="Docs__attribute__link" href="#format">#</a></th><td><p>The format for the input, one of: [json none]. `none` will add the entire input as a to the redactor, save for leading and trailing whitespace, `json` will parse it a string valued JSON Object, where each value of each key will be added to the redactor. (default: "none")<br /><strong>Environment variable</strong>: <code>$BUILDKITE_AGENT_REDACT_ADD_FORMAT</code></p></td></tr>
+<tr id="format"><th><code>--format value</code> <a class="Docs__attribute__link" href="#format">#</a></th><td><p>The format for the input, whose value is either `json` or `none`. `none` adds the entire input's content to the redactor, with the exception of leading and trailing space. `json` parses the input's content as a JSON object, where each value of each key is added to the redactor. (default: "none")<br /><strong>Environment variable</strong>: <code>$BUILDKITE_AGENT_REDACT_ADD_FORMAT</code></p></td></tr>
 <tr id="agent-access-token"><th><code>--agent-access-token value</code> <a class="Docs__attribute__link" href="#agent-access-token">#</a></th><td><p>The access token used to identify the agent<br /><strong>Environment variable</strong>: <code>$BUILDKITE_AGENT_ACCESS_TOKEN</code></p></td></tr>
 <tr id="endpoint"><th><code>--endpoint value</code> <a class="Docs__attribute__link" href="#endpoint">#</a></th><td><p>The Agent API endpoint (default: "<code>https://agent.buildkite.com/v3</code>")<br /><strong>Environment variable</strong>: <code>$BUILDKITE_AGENT_ENDPOINT</code></p></td></tr>
 <tr id="no-http2"><th><code>--no-http2 </code> <a class="Docs__attribute__link" href="#no-http2">#</a></th><td><p>Disable HTTP2 when communicating with the Agent API.<br /><strong>Environment variable</strong>: <code>$BUILDKITE_NO_HTTP2</code></p></td></tr>

scripts/update-agent-help.sh

@@ -10,6 +10,7 @@ commands=(
   "artifact upload"
   "artifact search"
   "bootstrap"
+  "build cancel"
   "env dump"
   "env set"
   "env get"