Merge pull request #64 from buildkite/agent-v3.83.0

Update docs for agent v3.83.0

pages/agent/v3.md

@@ -189,72 +189,27 @@ The agent also accepts the following two signals directly:
 
 The agent reports its activity to Buildkite using exit codes. The most common exit codes and their descriptions can be found in the table below.
 
-<table>
-  <tr>
-    <td>0</td>
-    <td>The job exited with a status of 0 (success)</td>
-  </tr>
-  <tr>
-    <td>1</td>
-    <td>The job exited with a status of 1 (most common error status)</td>
-  </tr>
-  <tr>
-    <td>128 + signal number</td>
-    <td>The job was terminated by a signal (see note below)</td>
-  </tr>
-  <tr>
-    <td>255</td>
-    <td>The agent was gracefully terminated</td>
-  </tr>
-  <tr>
-    <td>-1</td>
-    <td>Buildkite lost contact with the agent or it stopped reporting to us</td>
-  </tr>
-</table>
+Exit code           | Description
+------------------- | -------------------------------------------------------------------
+0                   | The job exited with a status of 0 (success)
+1                   | The job exited with a status of 1 (most common error status)
+94                  | The checkout timed out waiting for a Git mirrors lock
+128 + signal number | The job was terminated by a signal (see note below)
+255                 | The agent was gracefully terminated
+-1                  | Buildkite lost contact with the agent or it stopped reporting to us
 
 > 📘 Jobs terminated by signals
 > When a job is terminated by a signal, the exit code will be set to 128 + the signal number. For more information about how shells manage commands terminated by signals, see the Wiki page on <a href="https://en.wikipedia.org/wiki/Exit_status#Shell_and_scripts">Exit Signals</a>.
 
 Exit codes for common signals:
 
-<table>
-<tr>
-  <td>Exit code</td>
-  <td>Signal</td>
-  <td>Name</td>
-  <td>Description</td>
-</tr>
-<tr>
-  <td>130</td>
-  <td>2</td>
-  <td>SIGINT</td>
-  <td>Terminal interrupt signal</td>
-<tr>
-<tr>
-  <td>137</td>
-  <td>9</td>
-  <td>SIGKILL</td>
-  <td>Kill (cannot be caught or ignored)</td>
-<tr>
-<tr>
-  <td>139</td>
-  <td>11</td>
-  <td>SIGSEGV</td>
-  <td>Segmentation fault; Invalid memory reference</td>
-<tr>
-<tr>
-  <td>141</td>
-  <td>13</td>
-  <td>SIGPIPE</td>
-  <td>Write on a pipe with no one to read it</td>
-<tr>
-<tr>
-  <td>143</td>
-  <td>15</td>
-  <td>SIGTERM</td>
-  <td>Termination signal (graceful)</td>
-<tr>
-</table>
+Exit code | Signal | Name    | Description
+--------- | ------ | ------- | --------------------------------------------
+130       | 2      | SIGINT  | Terminal interrupt signal
+137       | 9      | SIGKILL | Kill (cannot be caught or ignored)
+139       | 11     | SIGSEGV | Segmentation fault; Invalid memory reference
+141       | 13     | SIGPIPE | Write on a pipe with no one to read it
+143       | 15     | SIGTERM | Termination signal (graceful)
 
 ## Troubleshooting
 

pages/agent/v3/help/_artifact_search.md

@@ -87,4 +87,6 @@ Format specifiers:
 
 %S    SHA1 checksum of the artifact
 
+%T    SHA256 checksum of the artifact
+
 %u    Download URL for the artifact, though consider using 'buildkite-agent artifact download' instead

pages/agent/v3/help/_artifact_upload.md

@@ -102,6 +102,7 @@ $ buildkite-agent upload log.tar
 <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>
+<tr id="no-multipart-artifact-upload"><th><code>--no-multipart-artifact-upload </code> <a class="Docs__attribute__link" href="#no-multipart-artifact-upload">#</a></th><td><p>For Buildkite-hosted artifacts, disables the use of multipart uploads. Has no effect on uploads to other destinations such as custom cloud buckets<br /><strong>Environment variable</strong>: <code>$BUILDKITE_NO_MULTIPART_ARTIFACT_UPLOAD</code></p></td></tr>
 </table>
 
 <!-- vale on -->

pages/agent/v3/help/_oidc_request_token.md

@@ -40,6 +40,7 @@ Requests and prints an OIDC token from Buildkite that claims the Job ID
 <tr id="lifetime"><th><code>--lifetime value</code> <a class="Docs__attribute__link" href="#lifetime">#</a></th><td><p>The time (in seconds) the OIDC token will be valid for before expiry. Must be a non-negative integer. If the flag is omitted or set to 0, the API will choose a default finite lifetime. (default: 0)</p></td></tr>
 <tr id="job"><th><code>--job value</code> <a class="Docs__attribute__link" href="#job">#</a></th><td><p>Buildkite Job Id to claim in the OIDC token<br /><strong>Environment variable</strong>: <code>$BUILDKITE_JOB_ID</code></p></td></tr>
 <tr id="claim"><th><code>--claim value</code> <a class="Docs__attribute__link" href="#claim">#</a></th><td><p>Claims to add to the OIDC token<br /><strong>Environment variable</strong>: <code>$BUILDKITE_OIDC_TOKEN_CLAIMS</code></p></td></tr>
+<tr id="aws-session-tag"><th><code>--aws-session-tag value</code> <a class="Docs__attribute__link" href="#aws-session-tag">#</a></th><td><p>Add claims as AWS Session Tags<br /><strong>Environment variable</strong>: <code>$BUILDKITE_OIDC_TOKEN_AWS_SESSION_TAGS</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>

pages/agent/v3/help/_start.md

@@ -105,12 +105,13 @@ $ buildkite-agent start --token xxx
 <tr id="signing-jwks-key-id"><th><code>--signing-jwks-key-id value</code> <a class="Docs__attribute__link" href="#signing-jwks-key-id">#</a></th><td><p>The JWKS key ID to use when signing the pipeline. If omitted, and the signing JWKS contains only one key, that key will be used.<br /><strong>Environment variable</strong>: <code>$BUILDKITE_AGENT_SIGNING_JWKS_KEY_ID</code></p></td></tr>
 <tr id="signing-aws-kms-key"><th><code>--signing-aws-kms-key value</code> <a class="Docs__attribute__link" href="#signing-aws-kms-key">#</a></th><td><p>The KMS KMS key ID, or key alias used when signing and verifying the pipeline.<br /><strong>Environment variable</strong>: <code>$BUILDKITE_AGENT_SIGNING_AWS_KMS_KEY</code></p></td></tr>
 <tr id="debug-signing"><th><code>--debug-signing </code> <a class="Docs__attribute__link" href="#debug-signing">#</a></th><td><p>Enable debug logging for pipeline signing. This can potentially leak secrets to the logs as it prints each step in full before signing. Requires debug logging to be enabled<br /><strong>Environment variable</strong>: <code>$BUILDKITE_AGENT_DEBUG_SIGNING</code></p></td></tr>
-<tr id="verification-failure-behavior"><th><code>--verification-failure-behavior value</code> <a class="Docs__attribute__link" href="#verification-failure-behavior">#</a></th><td><p>The behavior when a job is received without a signature. One of: [block warn]. Defaults to block (default: "block")<br /><strong>Environment variable</strong>: <code>$BUILDKITE_AGENT_JOB_VERIFICATION_NO_SIGNATURE_BEHAVIOR</code></p></td></tr>
+<tr id="verification-failure-behavior"><th><code>--verification-failure-behavior value</code> <a class="Docs__attribute__link" href="#verification-failure-behavior">#</a></th><td><p>The behavior when a job is received without a valid verifiable signature (without a signature, with an invalid signature, or with a signature that fails verification). One of: [block warn]. Defaults to block (default: "block")<br /><strong>Environment variable</strong>: <code>$BUILDKITE_AGENT_JOB_VERIFICATION_NO_SIGNATURE_BEHAVIOR</code></p></td></tr>
 <tr id="disable-warnings-for"><th><code>--disable-warnings-for value</code> <a class="Docs__attribute__link" href="#disable-warnings-for">#</a></th><td><p>A list of warning IDs to disable<br /><strong>Environment variable</strong>: <code>$BUILDKITE_AGENT_DISABLE_WARNINGS_FOR</code></p></td></tr>
 <tr id="token"><th><code>--token value</code> <a class="Docs__attribute__link" href="#token">#</a></th><td><p>Your account agent token<br /><strong>Environment variable</strong>: <code>$BUILDKITE_AGENT_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="trace-http"><th><code>--trace-http </code> <a class="Docs__attribute__link" href="#trace-http">#</a></th><td><p>Enable HTTP trace mode, which logs timings for each HTTP request. Timings are logged at the debug level unless a request fails at the network level in which case they are logged at the error level<br /><strong>Environment variable</strong>: <code>$BUILDKITE_AGENT_TRACE_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>
@@ -120,6 +121,7 @@ $ buildkite-agent start --token xxx
 <tr id="strict-single-hooks"><th><code>--strict-single-hooks </code> <a class="Docs__attribute__link" href="#strict-single-hooks">#</a></th><td><p>Enforces that only one checkout hook, and only one command hook, can be run<br /><strong>Environment variable</strong>: <code>$BUILDKITE_STRICT_SINGLE_HOOKS</code></p></td></tr>
 <tr id="kubernetes-exec"><th><code>--kubernetes-exec </code> <a class="Docs__attribute__link" href="#kubernetes-exec">#</a></th><td><p>This is intended to be used only by the Buildkite k8s stack (github.com/buildkite/agent-stack-k8s); it enables a Unix socket for transporting logs and exit statuses between containers in a pod<br /><strong>Environment variable</strong>: <code>$BUILDKITE_KUBERNETES_EXEC</code></p></td></tr>
 <tr id="trace-context-encoding"><th><code>--trace-context-encoding value</code> <a class="Docs__attribute__link" href="#trace-context-encoding">#</a></th><td><p>Sets the inner encoding for BUILDKITE_TRACE_CONTEXT. Must be either json or gob (default: "gob")<br /><strong>Environment variable</strong>: <code>$BUILDKITE_TRACE_CONTEXT_ENCODING</code></p></td></tr>
+<tr id="no-multipart-artifact-upload"><th><code>--no-multipart-artifact-upload </code> <a class="Docs__attribute__link" href="#no-multipart-artifact-upload">#</a></th><td><p>For Buildkite-hosted artifacts, disables the use of multipart uploads. Has no effect on uploads to other destinations such as custom cloud buckets<br /><strong>Environment variable</strong>: <code>$BUILDKITE_NO_MULTIPART_ARTIFACT_UPLOAD</code></p></td></tr>
 <tr id="tags-from-ec2"><th><code>--tags-from-ec2 </code> <a class="Docs__attribute__link" href="#tags-from-ec2">#</a></th><td><p>Include the host's EC2 meta-data as tags (instance-id, instance-type, and ami-id)<br /><strong>Environment variable</strong>: <code>$BUILDKITE_AGENT_TAGS_FROM_EC2</code></p></td></tr>
 <tr id="tags-from-gcp"><th><code>--tags-from-gcp </code> <a class="Docs__attribute__link" href="#tags-from-gcp">#</a></th><td><p>Include the host's Google Cloud instance meta-data as tags (instance-id, machine-type, preemptible, project-id, region, and zone)<br /><strong>Environment variable</strong>: <code>$BUILDKITE_AGENT_TAGS_FROM_GCP</code></p></td></tr>
 </table>