From a50184b232e1359fdb441995638035abb1c63697 Mon Sep 17 00:00:00 2001
From: Mark Wolfe <mark.wolfe@buildkite.com>
Date: Fri, 13 Sep 2024 16:33:30 +1000
Subject: [PATCH 1/2] Updated agent configuration using some new automation

---
 data/content/agent_attributes.yaml      | 482 +++++++++++++++++-------
 pages/agent/v3/help/_artifact_search.md |   2 +
 2 files changed, 338 insertions(+), 146 deletions(-)

diff --git a/data/content/agent_attributes.yaml b/data/content/agent_attributes.yaml
index 7019e2353a..bd889a2838 100644
--- a/data/content/agent_attributes.yaml
+++ b/data/content/agent_attributes.yaml
@@ -1,352 +1,542 @@
 attributes:
-- name: token
-  env_var: BUILDKITE_AGENT_TOKEN
-  default_value: None
-  required: true
+- name: acquire-job
+  env_var: BUILDKITE_AGENT_ACQUIRE_JOB
+  default_value: "none"
+  required: false
   desc: |
-      The agent token associated with a cluster. The agent token is configurable through the cluster that's accessible from your organization's **Agents** page.
-- name: build-path
-  env_var: BUILDKITE_BUILD_PATH
-  default_value: "(depends on platform)"
-  required: true
+    Start this agent and only run the specified job, disconnecting after it's finished
+- name: allowed-environment-variables
+  env_var: BUILDKITE_ALLOWED_ENVIRONMENT_VARIABLES
+  default_value: ""
+  required: false
+  desc: |
+    A comma-separated list of regular expressions representing environment variables the agent will pass to jobs (for example, "^MYAPP_.*$"). Environment variables set by Buildkite will always be allowed. Requires --enable-environment-variable-allowlist to be set
+- name: allowed-plugins
+  env_var: BUILDKITE_ALLOWED_PLUGINS
+  default_value: ""
+  required: false
   desc: |
-      The path to the directory where the builds will run.
+    A comma-separated list of regular expressions representing plugins the agent is allowed to use (for example, "^buildkite-plugins/.*$" or "^/var/lib/buildkite-plugins/.*")
 - name: allowed-repositories
   env_var: BUILDKITE_ALLOWED_REPOSITORIES
   default_value: ""
   required: false
   desc: |
-      A comma-separated list of regular expressions representing repositories the agent is allowed to clone (for example, `^git@github.com:buildkite/.\*` or `^https://github.com/buildkite/.*`)
+    A comma-separated list of regular expressions representing repositories the agent is allowed to clone (for example, "^git@github.com:buildkite/.*" or "^https://github.com/buildkite/.*")
 - name: bootstrap-script
   env_var: BUILDKITE_BOOTSTRAP_SCRIPT_PATH
-  default_value: "buildkite-agent bootstrap"
+  default_value: "none"
   required: false
   desc: |
-      The command to invoke the bootstrap process.
+    The command that is executed for bootstrapping a job, defaults to the bootstrap sub-command of this binary
+- name: build-path
+  env_var: BUILDKITE_BUILD_PATH
+  default_value: "none"
+  required: false
+  desc: |
+    Path to where the builds will run from
 - name: cancel-grace-period
   env_var: BUILDKITE_CANCEL_GRACE_PERIOD
   default_value: "10"
   required: false
   desc: |
-      The number of seconds a canceled or timed-out job is given to gracefully terminate and upload its artifacts.
+    The number of seconds a canceled or timed out job is given to gracefully terminate and upload its artifacts
 - name: cancel-signal
   env_var: BUILDKITE_CANCEL_SIGNAL
   default_value: "SIGTERM"
   required: false
   desc: |
-      The signal the agent sends to the bootstrap to signal cancellation.
+    The signal to use for cancellation
+- name: config
+  env_var: BUILDKITE_AGENT_CONFIG
+  default_value: "none"
+  required: false
+  desc: |
+    Path to a configuration file
 - name: debug
   env_var: BUILDKITE_AGENT_DEBUG
-  default_value: "false"
+  default_value: false
   required: false
   desc: |
-      Enables debug mode.
+    Enable debug mode. Synonym for ′--log-level debug′. Takes precedence over ′--log-level′
 - name: debug-http
   env_var: BUILDKITE_AGENT_DEBUG_HTTP
-  default_value: "false"
+  default_value: false
   required: false
   desc: |
-      Log all HTTP request and response bodies.
-- name: disconnect-after-job
-  env_var: BUILDKITE_AGENT_DISCONNECT_AFTER_JOB
-  default_value: "false"
+    Enable HTTP debug mode, which dumps all request and response bodies to the log
+- name: debug-signing
+  env_var: BUILDKITE_AGENT_DEBUG_SIGNING
+  default_value: false
   required: false
   desc: |
-      Disconnect after processing a single job.
+    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
+- name: disable-warnings-for
+  env_var: BUILDKITE_AGENT_DISABLE_WARNINGS_FOR
+  default_value: "none"
+  required: false
+  desc: |
+    A list of warning IDs to disable
 - name: disconnect-after-idle-timeout
   env_var: BUILDKITE_AGENT_DISCONNECT_AFTER_IDLE_TIMEOUT
   default_value: "none"
   required: false
   desc: |
-      The number of idle seconds to wait before shutting down. When setting this option alongside `spawn`, all agents started by `spawn` must be idle before the timeout counter will begin. After the timeout, the spawned agents will all disconnect.
+    The maximum idle time in seconds to wait for a job before disconnecting. The default of 0 means no timeout
+- name: disconnect-after-job
+  env_var: BUILDKITE_AGENT_DISCONNECT_AFTER_JOB
+  default_value: false
+  required: false
+  desc: |
+    Disconnect the agent after running exactly one job. When used in conjunction with the ′--spawn′ flag, each worker booted will run exactly one job
+- name: disconnect-after-job-timeout
+  env_var: BUILDKITE_AGENT_DISCONNECT_AFTER_JOB_TIMEOUT
+  default_value: "none"
+  required: false
+  desc: |-
+    When --disconnect-after-job is specified, the number of seconds to wait for a job before shutting down
+- name: enable-environment-variable-allowlist
+  env_var: BUILDKITE_ENABLE_ENVIRONMENT_VARIABLE_ALLOWLIST
+  default_value: false
+  required: false
+  desc: |
+    Only run jobs where all environment variables are allowed by the allowed-environment-variables option, or have been set by Buildkite
 - name: enable-job-log-tmpfile
   env_var: BUILDKITE_ENABLE_JOB_LOG_TMPFILE
-  default_value: "false"
+  default_value: false
   required: false
   desc: |
-      Enables the writing of job logs into a temporary file which can be accessed via the `BUILDKITE_JOB_LOG_TMPFILE` environment variable. Introduced in [v3.36](https://github.com/buildkite/agent/releases/tag/v3.36.0).
+    Store the job logs in a temporary file ′BUILDKITE_JOB_LOG_TMPFILE′ that is accessible during the job and removed at the end of the job
 - name: endpoint
   env_var: BUILDKITE_AGENT_ENDPOINT
   default_value: "https://agent.buildkite.com/v3"
   required: false
   desc: |
-      The Agent endpoint.
+    The Agent API endpoint
 - name: experiment
   env_var: BUILDKITE_AGENT_EXPERIMENT
-  default_value: "none"
+  default_value: ""
   required: false
   desc: |
-      A list of [experimental agent features](https://buildkite.com/docs/agent/v3#experimental-features) you want to enable.
+    Enable experimental features within the buildkite-agent
+- name: git-checkout-flags
+  env_var: BUILDKITE_GIT_CHECKOUT_FLAGS
+  default_value: "-f"
+  required: false
+  desc: |
+    Flags to pass to "git checkout" command
 - name: git-clean-flags
   env_var: BUILDKITE_GIT_CLEAN_FLAGS
   default_value: "-ffxdq"
   required: false
   desc: |
-      Flags to pass to the `git clean` command.
-      Agents below v3.0.0 default to `-fdq`.
-      Agents v3.0.0 to v3.7.0 default to `-fxdq`.
+    Flags to pass to "git clean" command
 - name: git-clone-flags
   env_var: BUILDKITE_GIT_CLONE_FLAGS
   default_value: "-v"
   required: false
   desc: |
-      Flags to pass to the `git clone` command.
+    Flags to pass to the "git clone" command
 - name: git-clone-mirror-flags
   env_var: BUILDKITE_GIT_CLONE_MIRROR_FLAGS
-  default_value: "none"
-  experimental: false
+  default_value: "-v"
   required: false
   desc: |
-      Flags to pass to the `git clone` command when used for mirroring. Refer to [Git mirrors](/docs/agent/v3#promoted-experiments-git-mirrors) for more information on this feature. Introduced in [v3.47.0](https://github.com/buildkite/agent/releases/tag/v3.47.0).
-      _Example:_ `-v --mirror`.
+    Flags to pass to the "git clone" command when used for mirroring
 - name: git-fetch-flags
   env_var: BUILDKITE_GIT_FETCH_FLAGS
   default_value: "-v --prune"
   required: false
-  experimental: true
   desc: |
-      Flags to pass to the `git fetch` command. Before [running builds on git tags](https://buildkite.com/docs/integrations/github#running-builds-on-git-tags), make sure your agent is fetching git tags.
+    Flags to pass to "git fetch" command
 - name: git-mirrors-lock-timeout
   env_var: BUILDKITE_GIT_MIRRORS_LOCK_TIMEOUT
   default_value: "300"
   required: false
-  experimental: false
   desc: |
-      Seconds to lock a git mirror during clone. Should exceed your longest checkout. Refer to [Git mirrors](/docs/agent/v3#promoted-experiments-git-mirrors) for more information on this feature. Introduced in [v3.47.0](https://github.com/buildkite/agent/releases/tag/v3.47.0).
+    Seconds to lock a git mirror during clone, should exceed your longest checkout
 - name: git-mirrors-path
   env_var: BUILDKITE_GIT_MIRRORS_PATH
   default_value: "none"
   required: false
-  experimental: false
   desc: |
-      Path to where mirrors of git repositories are stored. Refer to [Git mirrors](/docs/agent/v3#promoted-experiments-git-mirrors) for more information on this feature. Introduced in [v3.47.0](https://github.com/buildkite/agent/releases/tag/v3.47.0).
-      _Example:_ `/tmp/buildkite-git-mirrors`
+    Path to where mirrors of git repositories are stored
 - name: git-mirrors-skip-update
   env_var: BUILDKITE_GIT_MIRRORS_SKIP_UPDATE
-  default_value: "false"
+  default_value: false
   required: false
-  experimental: false
   desc: |
-       Skips updating the git mirror before cloning. Refer to [Git mirrors](/docs/agent/v3#promoted-experiments-git-mirrors) for more information on this feature. Introduced in [v3.47.0](https://github.com/buildkite/agent/releases/tag/v3.47.0).
+    Skip updating the Git mirror
 - name: health-check-addr
   env_var: BUILDKITE_AGENT_HEALTH_CHECK_ADDR
-  default_value: "disabled"
+  default_value: "none"
   required: false
   desc: |
-      Start an HTTP server on the specified `address:port` that returns whether the agent is healthy.
+    Start an HTTP server on this addr:port that returns whether the agent is healthy, disabled by default
 - name: hooks-path
   env_var: BUILDKITE_HOOKS_PATH
-  default_value: "(depends on platform)"
+  default_value: "none"
   required: false
   desc: |
-      The directory to use for agent hooks. See [Hook locations](https://buildkite.com/docs/agent/v3/hooks#hook-locations) for details.
+    Directory where the hook scripts are found
 - name: job-log-path
   env_var: BUILDKITE_JOB_LOG_PATH
-  default_value: "platform's TempDir; e.g. '/tmp'"
+  default_value: "none"
+  required: false
+  desc: |
+    Location to store job logs created by configuring ′enable-job-log-tmpfile`, by default job log will be stored in TempDir
+- name: kubernetes-exec
+  env_var: BUILDKITE_KUBERNETES_EXEC
+  default_value: false
   required: false
   desc: |
-      The directory of the temporary job log file created by the `enable-job-log-tmpfile` [agent configuration option](/docs/agent/v3/configuration#enable-job-log-tmpfile). Introduced in [v3.50.0](https://github.com/buildkite/agent/releases/tag/v3.50.0).
+    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
 - name: log-format
   env_var: BUILDKITE_LOG_FORMAT
   default_value: "text"
   required: false
   desc: |
-      The format to use for the logger output.
+    The format to use for the logger output
+- name: log-level
+  env_var: BUILDKITE_AGENT_LOG_LEVEL
+  default_value: "notice"
+  required: false
+  desc: |
+    Set the log level for the agent, making logging more or less verbose. Defaults to notice. Allowed values are: debug, info, error, warn, fatal
+- name: meta-data
+  env_var: BUILDKITE_AGENT_META_DATA
+  default_value: ""
+  required: false
+  desc: ""
+- name: meta-data-ec2
+  env_var: BUILDKITE_AGENT_META_DATA_EC2
+  default_value: false
+  required: false
+  desc: ""
+- name: meta-data-ec2-tags
+  env_var: BUILDKITE_AGENT_TAGS_FROM_EC2_TAGS
+  default_value: false
+  required: false
+  desc: ""
+- name: meta-data-gcp
+  env_var: BUILDKITE_AGENT_META_DATA_GCP
+  default_value: false
+  required: false
+  desc: ""
 - name: metrics-datadog
   env_var: BUILDKITE_METRICS_DATADOG
-  default_value: "false"
+  default_value: false
   required: false
   desc: |
-      Send metrics to DogStatsD for Datadog. This will generate the following metrics (duration measured in milliseconds):
-      `buildkite.jobs.success`
-      `buildkite.jobs.duration.success.avg`
-      `buildkite.jobs.duration.success.max`
-      `buildkite.jobs.duration.success.count`
-      `buildkite.jobs.duration.success.median`
-      `buildkite.jobs.duration.success.95percentile`
+    Send metrics to DogStatsD for Datadog
+- name: metrics-datadog-distributions
+  env_var: BUILDKITE_METRICS_DATADOG_DISTRIBUTIONS
+  default_value: false
+  required: false
+  desc: |
+    Use Datadog Distributions for Timing metrics
 - name: metrics-datadog-host
   env_var: BUILDKITE_METRICS_DATADOG_HOST
   default_value: "127.0.0.1:8125"
   required: false
   desc: |
-        The DogStatsD instance to send metrics to using UDP.
-- name: metrics-datadog-distributions
-  env_var: BUILDKITE_METRICS_DATADOG_DISTRIBUTIONS
-  default_value: "false"
-  required: false
-  desc: |
-      Use [Datadog Distributions](https://docs.datadoghq.com/metrics/types/?tab=distribution#metric-types) for timing metrics. This is advisable when running multiple agents. Otherwise, metrics from multiple agents may be rolled up and appear to have the same value.
+    The dogstatsd instance to send metrics to using udp
 - name: name
   env_var: BUILDKITE_AGENT_NAME
-  default_value: "%hostname-%spawn"
-  required: false
-  desc: |
-      The name of the agent. Supports template variables.
-
-      - `%hostname` (the agent machine's hostname)
-      - `%spawn` (a unique number for each agent started using `--spawn`; added in [v3.27.0](https://github.com/buildkite/agent/releases/tag/v3.27.0)).
-      - `%random` (some random alphanumeric characters).
-      - `%pid` (the agent process id).
-
-      Note that if you're using `--spawn` to run multiple agents in a single process, we recommend using `%spawn` in your agent name, or to ensure that each agent running on a host with the same `build-path` has a unique name.
-
-      _Default on Elastic CI Stack for AWS:_ "`%hostname-%spawn`" ([v5.2.0](https://github.com/buildkite/elastic-ci-stack-for-aws/releases/tag/v5.2.0) and later).
-- name: no-color
-  env_var: BUILDKITE_AGENT_NO_COLOR
-  default_value: "false"
+  default_value: "none"
   required: false
   desc: |
-      Do not show colors in logging.
+    The name of the agent
 - name: no-ansi-timestamps
   env_var: BUILDKITE_NO_ANSI_TIMESTAMPS
-  default_value: "false"
+  default_value: false
+  required: false
+  desc: |
+    Do not insert ANSI timestamp codes at the start of each line of job output
+- name: no-automatic-ssh-fingerprint-verification
+  env_var: BUILDKITE_NO_AUTOMATIC_SSH_FINGERPRINT_VERIFICATION
+  default_value: false
+  required: false
+  desc: ""
+- name: no-color
+  env_var: BUILDKITE_AGENT_NO_COLOR
+  default_value: false
   required: false
   desc: |
-    Do not insert ANSI timestamp codes at the start of each line of job output.
+    Don't show colors in logging
 - name: no-command-eval
   env_var: BUILDKITE_NO_COMMAND_EVAL
-  default_value: "false"
+  default_value: false
+  required: false
+  desc: |
+    Don't allow this agent to run arbitrary console commands, including plugins
+- name: no-feature-reporting
+  env_var: BUILDKITE_AGENT_NO_FEATURE_REPORTING
+  default_value: false
   required: false
   desc: |
-      Do not allow this agent to run arbitrary console commands.
+    Disables sending a list of enabled features back to the Buildkite mothership. We use this information to measure feature usage, but if you're not comfortable sharing that information then that's totally okay :)
 - name: no-git-submodules
-  env_var: BUILDKITE_NO_GIT_SUBMODULES, BUILDKITE_DISABLE_GIT_SUBMODULES
-  default_value: "false"
+  env_var: BUILDKITE_NO_GIT_SUBMODULES,BUILDKITE_DISABLE_GIT_SUBMODULES
+  default_value: false
   required: false
   desc: |
-      Do not automatically checkout git submodules.
+    Don't automatically checkout git submodules
 - name: no-http2
   env_var: BUILDKITE_NO_HTTP2
-  default_value: "false"
+  default_value: false
   required: false
   desc: |
-      Disable HTTP2 when communicating with the Agent API.
+    Disable HTTP2 when communicating with the Agent API.
 - name: no-local-hooks
   env_var: BUILDKITE_NO_LOCAL_HOOKS
-  default_value: "false"
+  default_value: false
   required: false
   desc: |
-      Don't allow any local hooks, or plugins from any source.
+    Don't allow local hooks to be run from checked out repositories
 - name: no-plugins
   env_var: BUILDKITE_NO_PLUGINS
-  default_value: "false"
+  default_value: false
   required: false
   desc: |
-      Don't allow loading of plugins.
-- name: no-plugin-validation
-  env_var: BUILDKITE_NO_PLUGIN_VALIDATION
-  default_value: "true"
-  required: false
-  desc: |
-      Do not validate plugin configuration and requirements. By default the option is enabled, so the validation is not performed.
+    Don't allow this agent to load plugins
 - name: no-pty
   env_var: BUILDKITE_NO_PTY
-  default_value: "false"
+  default_value: false
   required: false
   desc: |
-      Do not run jobs within a pseudo terminal.
+    Do not run jobs within a pseudo terminal
 - name: no-ssh-keyscan
   env_var: BUILDKITE_NO_SSH_KEYSCAN
-  default_value: "false"
+  default_value: false
   required: false
   desc: |
-      Do not automatically run ssh-keyscan before checkout.
+    Don't automatically run ssh-keyscan before checkout
 - name: plugins-path
   env_var: BUILDKITE_PLUGINS_PATH
-  default_value: "(depends on platform)"
-  required: false
-  desc: |
-      Directory where the plugins are saved.
-- name: plugins-always-clone-fresh
-  env_var: BUILDKITE_PLUGINS_ALWAYS_CLONE_FRESH
-  default_value: "false"
+  default_value: "none"
   required: false
   desc: |
-      Force checking out a fresh clone of plugins every build. By default, if the organization, repository, and version tag of a plugin specified in a step match a plugin that is already on the agent, the agent uses that local version. Forcing fresh checkout is especially useful during plugin development. Available from [v3.37](https://github.com/buildkite/agent/releases/tag/v3.37.0).
+    Directory where the plugins are saved to
 - name: priority
   env_var: BUILDKITE_AGENT_PRIORITY
-  default_value: "null"
+  default_value: "none"
+  required: false
+  desc: |
+    The priority of the agent (higher priorities are assigned work first)
+- name: profile
+  env_var: BUILDKITE_AGENT_PROFILE
+  default_value: "none"
   required: false
   desc: |
-      The priority of the agent. Higher priorities are assigned work first, null is assigned last.
+    Enable a profiling mode, either cpu, memory, mutex or block
+- name: queue
+  env_var: BUILDKITE_AGENT_QUEUE
+  default_value: "none"
+  required: false
+  desc: |
+    The queue the agent will listen to for jobs. If not set, the agent will use the default queue. Overwrites the queue tag in the agent's tags
 - name: redacted-vars
   env_var: BUILDKITE_REDACTED_VARS
-  default_value: "'*_PASSWORD', '*_SECRET', '*_TOKEN', '*_ACCESS_KEY', '*_SECRET_KEY'"
+  default_value: "*_PASSWORD,*_SECRET,*_TOKEN,*_PRIVATE_KEY,*_ACCESS_KEY,*_SECRET_KEY,*_CONNECTION_STRING"
   required: false
   desc: |
-      A list of environment variable name patterns whose values should be [redacted](/docs/pipelines/managing-log-output#redacted-environment-variables) before being printed to the build log. To disable redaction, set this to an empty string. Introduced in [v3.31](https://github.com/buildkite/agent/releases/tag/v3.31.0).
+    Pattern of environment variable names containing sensitive values
 - name: shell
   env_var: BUILDKITE_SHELL
-  default_value: "`C:\\Windows\\System32\\CMD.exe`\" on Windows, \"`/bin/bash`\" on *nix systems"
+  default_value: "/bin/bash -e -c"
+  required: false
+  desc: |
+    The shell command used to interpret build commands, e.g /bin/bash -e -c
+- name: signal-grace-period-seconds
+  env_var: BUILDKITE_SIGNAL_GRACE_PERIOD_SECONDS
+  default_value: "-1"
   required: false
   desc: |
-      The shell command used to interpret build commands.
-      _Example:_ `/bin/bash -e -c`.
+    The number of seconds given to a subprocess to handle being sent ′cancel-signal′. After this period has elapsed, SIGKILL will be sent. Negative values are taken relative to ′cancel-grace-period′. The default is ′cancel-grace-period′ - 1.
+- name: signing-aws-kms-key
+  env_var: BUILDKITE_AGENT_SIGNING_AWS_KMS_KEY
+  default_value: "none"
+  required: false
+  desc: |
+    The KMS KMS key ID, or key alias used when signing and verifying the pipeline.
+- name: signing-jwks-file
+  env_var: BUILDKITE_AGENT_SIGNING_JWKS_FILE
+  default_value: "none"
+  required: false
+  desc: |
+    Path to a file containing a signing key. Passing this flag enables pipeline signing for all pipelines uploaded by this agent. For hmac-sha256, the raw file content is used as the shared key
+- name: signing-jwks-key-id
+  env_var: BUILDKITE_AGENT_SIGNING_JWKS_KEY_ID
+  default_value: "none"
+  required: false
+  desc: |
+    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.
+- name: sockets-path
+  env_var: BUILDKITE_SOCKETS_PATH
+  default_value: "/Users/markw/.buildkite-agent/sockets"
+  required: false
+  desc: |
+    Directory where the agent will place sockets
 - name: spawn
   env_var: BUILDKITE_AGENT_SPAWN
   default_value: "1"
   required: false
   desc: |
-      The number of agents to spawn in parallel.
+    The number of agents to spawn in parallel (mutually exclusive with --spawn-per-cpu)
+- name: spawn-per-cpu
+  env_var: BUILDKITE_AGENT_SPAWN_PER_CPU
+  default_value: "none"
+  required: false
+  desc: |
+    The number of agents to spawn per cpu in parallel (mutually exclusive with --spawn)
+- name: spawn-with-priority
+  env_var: BUILDKITE_AGENT_SPAWN_WITH_PRIORITY
+  default_value: false
+  required: false
+  desc: |
+    Assign priorities to every spawned agent (when using --spawn or --spawn-per-cpu) equal to the agent's index
+- name: strict-single-hooks
+  env_var: BUILDKITE_STRICT_SINGLE_HOOKS
+  default_value: false
+  required: false
+  desc: |
+    Enforces that only one checkout hook, and only one command hook, can be run
 - name: tags
   env_var: BUILDKITE_AGENT_TAGS
-  default_value: "queue=default"
+  default_value: ""
   required: false
   desc: |
-      Tags for the agent.
+    A comma-separated list of tags for the agent (for example, "linux" or "mac,xcode=8")
 - name: tags-from-ec2
   env_var: BUILDKITE_AGENT_TAGS_FROM_EC2
-  default_value: "false"
+  default_value: false
   required: false
   desc: |
-      Include the host's EC2 meta-data (instance-id, instance-type, and ami-id) as tags.
+    Include the host's EC2 meta-data as tags (instance-id, instance-type, and ami-id)
+- name: tags-from-ec2-meta-data
+  env_var: BUILDKITE_AGENT_TAGS_FROM_EC2_META_DATA
+  default_value: ""
+  required: false
+  desc: |
+    Include the default set of host EC2 meta-data as tags (instance-id, instance-type, ami-id, and instance-life-cycle)
+- name: tags-from-ec2-meta-data-paths
+  env_var: BUILDKITE_AGENT_TAGS_FROM_EC2_META_DATA_PATHS
+  default_value: ""
+  required: false
+  desc: |
+    Include additional tags fetched from EC2 meta-data using tag & path suffix pairs, e.g "tag_name=path/to/value"
 - name: tags-from-ec2-tags
   env_var: BUILDKITE_AGENT_TAGS_FROM_EC2_TAGS
-  default_value: "false"
+  default_value: false
   required: false
   desc: |
-      Include the host's EC2 tags as agent tags.
+    Include the host's EC2 tags as tags
+- name: tags-from-ecs-meta-data
+  env_var: BUILDKITE_AGENT_TAGS_FROM_ECS_META_DATA
+  default_value: false
+  required: false
+  desc: |
+    Include the host's ECS meta-data as tags (container-name, image, and task-arn)
 - name: tags-from-gcp
   env_var: BUILDKITE_AGENT_TAGS_FROM_GCP
-  default_value: "false"
+  default_value: false
   required: false
   desc: |
-      Include the host's Google Cloud meta-data as tags (instance-id, machine-type, preemptible, project-id, region, and zone).
+    Include the host's Google Cloud instance meta-data as tags (instance-id, machine-type, preemptible, project-id, region, and zone)
 - name: tags-from-gcp-labels
   env_var: BUILDKITE_AGENT_TAGS_FROM_GCP_LABELS
-  default_value: "false"
+  default_value: false
+  required: false
+  desc: |
+    Include the host's Google Cloud instance labels as tags
+- name: tags-from-gcp-meta-data
+  env_var: BUILDKITE_AGENT_TAGS_FROM_GCP_META_DATA
+  default_value: ""
   required: false
   desc: |
-      Include the host's Google Cloud instance labels as tags.
+    Include the default set of host Google Cloud instance meta-data as tags (instance-id, machine-type, preemptible, project-id, region, and zone)
+- name: tags-from-gcp-meta-data-paths
+  env_var: BUILDKITE_AGENT_TAGS_FROM_GCP_META_DATA_PATHS
+  default_value: ""
+  required: false
+  desc: |
+    Include additional tags fetched from Google Cloud instance meta-data using tag & path suffix pairs, e.g "tag_name=path/to/value"
 - name: tags-from-host
   env_var: BUILDKITE_AGENT_TAGS_FROM_HOST
-  default_value: "false"
+  default_value: false
   required: false
   desc: |
-      Include the host's meta-data as tags (hostname, machine-id, and OS).
+    Include tags from the host (hostname, machine-id, os)
 - name: timestamp-lines
   env_var: BUILDKITE_TIMESTAMP_LINES
-  default_value: "false"
+  default_value: false
+  required: false
+  desc: |
+    Prepend timestamps on each line of job output. Has no effect unless --no-ansi-timestamps is also used
+- name: token
+  env_var: BUILDKITE_AGENT_TOKEN
+  default_value: "none"
   required: false
   desc: |
-      Prepend timestamps on each line of output. Has no effect unless --no-ansi-timestamps is also used.
+    Your account agent token
+- name: trace-context-encoding
+  env_var: BUILDKITE_TRACE_CONTEXT_ENCODING
+  default_value: "gob"
+  required: false
+  desc: |
+    Sets the inner encoding for BUILDKITE_TRACE_CONTEXT. Must be either json or gob
 - name: tracing-backend
   env_var: BUILDKITE_TRACING_BACKEND
   default_value: "none"
   required: false
   desc: |
-      Set to `datadog` to enable the Datadog API tracing for builds using the default APM address `localhost:8126`, or Datadog variables like `DD_AGENT_HOST` and `DD_AGENT_TRACE_PORT`.
-      Set to `opentelemetry` to enable OpenTelemetry tracing, sending OTLP gRPC traces to `https://localhost:4317`, or override with the environment variable `OTEL_EXPORTER_OTLP_ENDPOINT`.
-      Accepts empty string (`""`), `"datadog"`, or `opentelemetry`.
+    Enable tracing for build jobs by specifying a backend, "datadog" or "opentelemetry"
+- name: tracing-service-name
+  env_var: BUILDKITE_TRACING_SERVICE_NAME
+  default_value: "buildkite-agent"
+  required: false
+  desc: |
+    Service name to use when reporting traces.
+- name: verification-failure-behavior
+  env_var: BUILDKITE_AGENT_JOB_VERIFICATION_NO_SIGNATURE_BEHAVIOR
+  default_value: "block"
+  required: false
+  desc: |
+    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
+- name: verification-jwks-file
+  env_var: BUILDKITE_AGENT_VERIFICATION_JWKS_FILE
+  default_value: "none"
+  required: false
+  desc: |
+    Path to a file containing a JSON Web Key Set (JWKS), used to verify job signatures.
+- name: wait-for-ec2-meta-data-timeout
+  env_var: BUILDKITE_AGENT_WAIT_FOR_EC2_META_DATA_TIMEOUT
+  default_value: "10s"
+  required: false
+  desc: |
+    The amount of time to wait for meta-data from EC2 before proceeding
 - name: wait-for-ec2-tags-timeout
   env_var: BUILDKITE_AGENT_WAIT_FOR_EC2_TAGS_TIMEOUT
-  default_value: "10"
+  default_value: "10s"
+  required: false
+  desc: |
+    The amount of time to wait for tags from EC2 before proceeding
+- name: wait-for-ecs-meta-data-timeout
+  env_var: BUILDKITE_AGENT_WAIT_FOR_ECS_META_DATA_TIMEOUT
+  default_value: "10s"
   required: false
   desc: |
-      The amount of time in seconds to wait for tags from EC2 before proceeding.
+    The amount of time to wait for meta-data from ECS before proceeding
 - name: wait-for-gcp-labels-timeout
   env_var: BUILDKITE_AGENT_WAIT_FOR_GCP_LABELS_TIMEOUT
-  default_value: "10"
+  default_value: "10s"
+  required: false
+  desc: |
+    The amount of time to wait for labels from GCP before proceeding
+- name: write-job-logs-to-stdout
+  env_var: BUILDKITE_WRITE_JOB_LOGS_TO_STDOUT
+  default_value: false
   required: false
   desc: |
-      The amount of time in seconds to wait for tags from GCP before proceeding.
+    Writes job logs to the agent process' stdout. This simplifies log collection if running agents in Docker.
diff --git a/pages/agent/v3/help/_artifact_search.md b/pages/agent/v3/help/_artifact_search.md
index c1a2bc6768..d2425a9d7c 100644
--- a/pages/agent/v3/help/_artifact_search.md
+++ b/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 &#39;buildkite-agent artifact download&#39; instead

From 6ad90f1f5daaecba2d62593145c4d7708150e73e Mon Sep 17 00:00:00 2001
From: Mark Wolfe <mark.wolfe@buildkite.com>
Date: Fri, 13 Sep 2024 17:07:19 +1000
Subject: [PATCH 2/2] Removed hidden options and config

---
 data/content/agent_attributes.yaml | 81 ++++++++----------------------
 1 file changed, 22 insertions(+), 59 deletions(-)

diff --git a/data/content/agent_attributes.yaml b/data/content/agent_attributes.yaml
index bd889a2838..f16ad6d848 100644
--- a/data/content/agent_attributes.yaml
+++ b/data/content/agent_attributes.yaml
@@ -1,7 +1,7 @@
 attributes:
 - name: acquire-job
   env_var: BUILDKITE_AGENT_ACQUIRE_JOB
-  default_value: "none"
+  default_value: "None"
   required: false
   desc: |
     Start this agent and only run the specified job, disconnecting after it's finished
@@ -25,13 +25,13 @@ attributes:
     A comma-separated list of regular expressions representing repositories the agent is allowed to clone (for example, "^git@github.com:buildkite/.*" or "^https://github.com/buildkite/.*")
 - name: bootstrap-script
   env_var: BUILDKITE_BOOTSTRAP_SCRIPT_PATH
-  default_value: "none"
+  default_value: "None"
   required: false
   desc: |
     The command that is executed for bootstrapping a job, defaults to the bootstrap sub-command of this binary
 - name: build-path
   env_var: BUILDKITE_BUILD_PATH
-  default_value: "none"
+  default_value: "None"
   required: false
   desc: |
     Path to where the builds will run from
@@ -47,12 +47,6 @@ attributes:
   required: false
   desc: |
     The signal to use for cancellation
-- name: config
-  env_var: BUILDKITE_AGENT_CONFIG
-  default_value: "none"
-  required: false
-  desc: |
-    Path to a configuration file
 - name: debug
   env_var: BUILDKITE_AGENT_DEBUG
   default_value: false
@@ -73,13 +67,13 @@ attributes:
     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
 - name: disable-warnings-for
   env_var: BUILDKITE_AGENT_DISABLE_WARNINGS_FOR
-  default_value: "none"
+  default_value: "None"
   required: false
   desc: |
     A list of warning IDs to disable
 - name: disconnect-after-idle-timeout
   env_var: BUILDKITE_AGENT_DISCONNECT_AFTER_IDLE_TIMEOUT
-  default_value: "none"
+  default_value: "None"
   required: false
   desc: |
     The maximum idle time in seconds to wait for a job before disconnecting. The default of 0 means no timeout
@@ -89,12 +83,6 @@ attributes:
   required: false
   desc: |
     Disconnect the agent after running exactly one job. When used in conjunction with the ′--spawn′ flag, each worker booted will run exactly one job
-- name: disconnect-after-job-timeout
-  env_var: BUILDKITE_AGENT_DISCONNECT_AFTER_JOB_TIMEOUT
-  default_value: "none"
-  required: false
-  desc: |-
-    When --disconnect-after-job is specified, the number of seconds to wait for a job before shutting down
 - name: enable-environment-variable-allowlist
   env_var: BUILDKITE_ENABLE_ENVIRONMENT_VARIABLE_ALLOWLIST
   default_value: false
@@ -157,7 +145,7 @@ attributes:
     Seconds to lock a git mirror during clone, should exceed your longest checkout
 - name: git-mirrors-path
   env_var: BUILDKITE_GIT_MIRRORS_PATH
-  default_value: "none"
+  default_value: "None"
   required: false
   desc: |
     Path to where mirrors of git repositories are stored
@@ -169,19 +157,19 @@ attributes:
     Skip updating the Git mirror
 - name: health-check-addr
   env_var: BUILDKITE_AGENT_HEALTH_CHECK_ADDR
-  default_value: "none"
+  default_value: "None"
   required: false
   desc: |
     Start an HTTP server on this addr:port that returns whether the agent is healthy, disabled by default
 - name: hooks-path
   env_var: BUILDKITE_HOOKS_PATH
-  default_value: "none"
+  default_value: "None"
   required: false
   desc: |
     Directory where the hook scripts are found
 - name: job-log-path
   env_var: BUILDKITE_JOB_LOG_PATH
-  default_value: "none"
+  default_value: "None"
   required: false
   desc: |
     Location to store job logs created by configuring ′enable-job-log-tmpfile`, by default job log will be stored in TempDir
@@ -203,26 +191,6 @@ attributes:
   required: false
   desc: |
     Set the log level for the agent, making logging more or less verbose. Defaults to notice. Allowed values are: debug, info, error, warn, fatal
-- name: meta-data
-  env_var: BUILDKITE_AGENT_META_DATA
-  default_value: ""
-  required: false
-  desc: ""
-- name: meta-data-ec2
-  env_var: BUILDKITE_AGENT_META_DATA_EC2
-  default_value: false
-  required: false
-  desc: ""
-- name: meta-data-ec2-tags
-  env_var: BUILDKITE_AGENT_TAGS_FROM_EC2_TAGS
-  default_value: false
-  required: false
-  desc: ""
-- name: meta-data-gcp
-  env_var: BUILDKITE_AGENT_META_DATA_GCP
-  default_value: false
-  required: false
-  desc: ""
 - name: metrics-datadog
   env_var: BUILDKITE_METRICS_DATADOG
   default_value: false
@@ -243,7 +211,7 @@ attributes:
     The dogstatsd instance to send metrics to using udp
 - name: name
   env_var: BUILDKITE_AGENT_NAME
-  default_value: "none"
+  default_value: "None"
   required: false
   desc: |
     The name of the agent
@@ -253,11 +221,6 @@ attributes:
   required: false
   desc: |
     Do not insert ANSI timestamp codes at the start of each line of job output
-- name: no-automatic-ssh-fingerprint-verification
-  env_var: BUILDKITE_NO_AUTOMATIC_SSH_FINGERPRINT_VERIFICATION
-  default_value: false
-  required: false
-  desc: ""
 - name: no-color
   env_var: BUILDKITE_AGENT_NO_COLOR
   default_value: false
@@ -314,25 +277,25 @@ attributes:
     Don't automatically run ssh-keyscan before checkout
 - name: plugins-path
   env_var: BUILDKITE_PLUGINS_PATH
-  default_value: "none"
+  default_value: "None"
   required: false
   desc: |
     Directory where the plugins are saved to
 - name: priority
   env_var: BUILDKITE_AGENT_PRIORITY
-  default_value: "none"
+  default_value: "None"
   required: false
   desc: |
     The priority of the agent (higher priorities are assigned work first)
 - name: profile
   env_var: BUILDKITE_AGENT_PROFILE
-  default_value: "none"
+  default_value: "None"
   required: false
   desc: |
     Enable a profiling mode, either cpu, memory, mutex or block
 - name: queue
   env_var: BUILDKITE_AGENT_QUEUE
-  default_value: "none"
+  default_value: "None"
   required: false
   desc: |
     The queue the agent will listen to for jobs. If not set, the agent will use the default queue. Overwrites the queue tag in the agent's tags
@@ -356,19 +319,19 @@ attributes:
     The number of seconds given to a subprocess to handle being sent ′cancel-signal′. After this period has elapsed, SIGKILL will be sent. Negative values are taken relative to ′cancel-grace-period′. The default is ′cancel-grace-period′ - 1.
 - name: signing-aws-kms-key
   env_var: BUILDKITE_AGENT_SIGNING_AWS_KMS_KEY
-  default_value: "none"
+  default_value: "None"
   required: false
   desc: |
     The KMS KMS key ID, or key alias used when signing and verifying the pipeline.
 - name: signing-jwks-file
   env_var: BUILDKITE_AGENT_SIGNING_JWKS_FILE
-  default_value: "none"
+  default_value: "None"
   required: false
   desc: |
     Path to a file containing a signing key. Passing this flag enables pipeline signing for all pipelines uploaded by this agent. For hmac-sha256, the raw file content is used as the shared key
 - name: signing-jwks-key-id
   env_var: BUILDKITE_AGENT_SIGNING_JWKS_KEY_ID
-  default_value: "none"
+  default_value: "None"
   required: false
   desc: |
     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.
@@ -386,7 +349,7 @@ attributes:
     The number of agents to spawn in parallel (mutually exclusive with --spawn-per-cpu)
 - name: spawn-per-cpu
   env_var: BUILDKITE_AGENT_SPAWN_PER_CPU
-  default_value: "none"
+  default_value: "None"
   required: false
   desc: |
     The number of agents to spawn per cpu in parallel (mutually exclusive with --spawn)
@@ -442,7 +405,7 @@ attributes:
   env_var: BUILDKITE_AGENT_TAGS_FROM_GCP
   default_value: false
   required: false
-  desc: |
+  desc: |-
     Include the host's Google Cloud instance meta-data as tags (instance-id, machine-type, preemptible, project-id, region, and zone)
 - name: tags-from-gcp-labels
   env_var: BUILDKITE_AGENT_TAGS_FROM_GCP_LABELS
@@ -476,7 +439,7 @@ attributes:
     Prepend timestamps on each line of job output. Has no effect unless --no-ansi-timestamps is also used
 - name: token
   env_var: BUILDKITE_AGENT_TOKEN
-  default_value: "none"
+  default_value: "None"
   required: false
   desc: |
     Your account agent token
@@ -488,7 +451,7 @@ attributes:
     Sets the inner encoding for BUILDKITE_TRACE_CONTEXT. Must be either json or gob
 - name: tracing-backend
   env_var: BUILDKITE_TRACING_BACKEND
-  default_value: "none"
+  default_value: "None"
   required: false
   desc: |
     Enable tracing for build jobs by specifying a backend, "datadog" or "opentelemetry"
@@ -506,7 +469,7 @@ attributes:
     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
 - name: verification-jwks-file
   env_var: BUILDKITE_AGENT_VERIFICATION_JWKS_FILE
-  default_value: "none"
+  default_value: "None"
   required: false
   desc: |
     Path to a file containing a JSON Web Key Set (JWKS), used to verify job signatures.