Update docs for Agent v3.48.0

pages/agent/v3.md

@@ -89,26 +89,6 @@ The Buildkite agent can redact strings that match the value of environment varia
 
 See [redacted-vars](/docs/pipelines/managing-log-output#redacted-environment-variables) for more information.
 
-### Git mirrors
-
-Maintain a single bare git mirror for each repository on a host that is shared amongst multiple agents and pipelines. Checkouts reference the git mirror using `git clone --reference`, as do submodules.
-
->🛠 Experimental feature
-> To use it, set <code>experiment="git-mirrors"</code> in your <a href="/docs/agent/v3/configuration#experiment"> agent configuration</a>.
-
-See the following agent configuration options for more information:
-
-- [git-clone-mirror-flags](/docs/agent/v3/configuration#git-clone-mirror-flags)
-- [git-mirrors-lock-timeout](/docs/agent/v3/configuration#git-mirrors-lock-timeout)
-- [git-mirrors-path](/docs/agent/v3/configuration#git-mirrors-path)
-
-### ANSI timestamps
-
-Outputs inline ANSI timestamps for each line of log output which enables toggle-able timestamps in the Buildkite UI.
-
->🛠 Experimental feature
-> To use it, set <code>experiment="ansi-timestamps"</code> in your <a href="/docs/agent/v3/configuration#experiment"> agent configuration</a>.
-
 ### Normalised upload paths
 
 Artifacts uploaded by `buildkite-agent artifact upload` will be uploaded using URI/Unix-style paths, even on Windows. This makes sure that artifacts uploaded from Windows agents are stored in a URI-compatible URL.
@@ -127,15 +107,6 @@ After repository checkout, resolve `BUILDKITE_COMMIT` to a commit hash. This mak
 >🛠 Experimental feature
 > To use it, set <code>experiment="resolve-commit-after-checkout"</code> in your <a href="/docs/agent/v3/configuration#experiment"> agent configuration</a>.
 
-### Flock file locks
-
-Changes the file lock implementation from `github.com/nightlyone/lockfile` to `github.com/gofrs/flock` to address an issue where file locks are never released by agents that don't shut down cleanly. The new file locks are implemented at the kernel level, and are aware of when their parent process dies.
-
-When the experiment is enabled, the agent will use different lock files from agents where the experiment is disabled, so the agents with this experiment enabled should not be run on the same host as the agents where the experiment is disabled.
-
->🛠 Experimental feature
-> To use flock file locks, set <code>experiment="flock-file-locks"</code> in your <a href="/docs/agent/v3/configuration#experiment"> agent configuration</a>.
-
 ### Kubernetes exec
 
 Modifies `start` and `bootstrap` to execute in separate Kubernetes containers in the same pod.
@@ -165,6 +136,53 @@ The job API is unavailable on agents running versions of Windows before build 17
 >🛠 Experimental feature
 > To use the job API, set <code>experiment="job-api"</code> in your <a href="/docs/agent/v3/configuration#experiment"> agent configuration</a>.
 
+### Agent API
+
+Like the Job API experiment above, this exposes a (separate) local API for interacting with the agent process.
+The Agent API offers these endpoints:
+
+* `GET /api/leader/v0/ping` - Returns a JSON object with the current time (useful for testing liveness).
+* `GET /api/leader/v0/lock?key=<key>` - Returns a JSON object containing the current state of a lock.
+* `PATCH /api/leader/v0/lock?key=<key>` - Accepts a JSON object with old and new states for a lock. The lock is then updated atomically, and a JSON object describing whether the operation proceeded is returned
+
+The API is exposed via a Unix Domain Socket. Unlike the `job-api`, the path to the socket is not available via a environment variable - rather, there is a single (configurable) path on the system.
+
+>🛠 Experimental feature
+> To use the agent API, set <code>experiment="agent-api"</code> in your <a href="/docs/agent/v3/configuration#experiment"> agent configuration</a>.
+
+
+## Promoted experiments
+
+We've made some experiments into full features. These are kept below.
+
+### Git mirrors
+
+Maintain a single bare git mirror for each repository on a host that is shared amongst multiple agents and pipelines. Checkouts reference the git mirror using `git clone --reference`, as do submodules.
+
+>🎓 Promoted experiment
+> Git mirrors became a default feature in Agent v3.47.0. It can be used by setting the `--git-mirrors-path` flag.
+
+See the following agent configuration options for more information:
+
+- [git-clone-mirror-flags](/docs/agent/v3/configuration#git-clone-mirror-flags)
+- [git-mirrors-lock-timeout](/docs/agent/v3/configuration#git-mirrors-lock-timeout)
+- [git-mirrors-path](/docs/agent/v3/configuration#git-mirrors-path)
+
+### Flock file locks
+
+Changes the file lock implementation from `github.com/nightlyone/lockfile` to `github.com/gofrs/flock` to address an issue where file locks are never released by agents that don't shut down cleanly. The new file locks are implemented at the kernel level, and are aware of when their parent process dies.
+
+>🎓 Promoted experiment
+> Flock file locks became a default feature in Agent v3.48.0. There is no configuration required to use it; it is just on. Because the old and new lock systems do not interact, we *strongly* recommend not running different versions of the agent on the same host.
+
+### ANSI timestamps
+
+Outputs inline ANSI timestamps for each line of log output which enables toggle-able timestamps in the Buildkite UI.
+
+>🎓 Promoted experiment
+> ANSI timestaps became a default feature in Agent v3.48.0. There is no configuration required to use it. If you want to turn it off, pass the `--no-ansi-timestamps` flag.
+
+
 ## Customizing with hooks
 
 The agent's behavior can be customized using hooks, which are shell scripts that exist on your build machines or in each pipeline's code repository. Hooks can be used to set up [secrets](/docs/pipelines/secrets) as well as overriding default behavior. See the [hooks](/docs/agent/v3/hooks) documentation for full details.

pages/agent/v3/help/_start.md

@@ -70,7 +70,8 @@ The agent will run any jobs within a PTY (pseudo terminal) if available.
 <tr id="hooks-path"><th><code>--hooks-path value</code> <a class="Docs__attribute__link" href="#hooks-path">#</a></th><td><p>Directory where the hook scripts are found<br /><strong>Environment variable</strong>: <code>$BUILDKITE_HOOKS_PATH</code></p></td></tr>
 <tr id="sockets-path"><th><code>--sockets-path value</code> <a class="Docs__attribute__link" href="#sockets-path">#</a></th><td><p>Directory where the agent will place sockets (default: "$HOME/.buildkite-agent/sockets")<br /><strong>Environment variable</strong>: <code>$BUILDKITE_SOCKETS_PATH</code></p></td></tr>
 <tr id="plugins-path"><th><code>--plugins-path value</code> <a class="Docs__attribute__link" href="#plugins-path">#</a></th><td><p>Directory where the plugins are saved to<br /><strong>Environment variable</strong>: <code>$BUILDKITE_PLUGINS_PATH</code></p></td></tr>
-<tr id="timestamp-lines"><th><code>--timestamp-lines </code> <a class="Docs__attribute__link" href="#timestamp-lines">#</a></th><td><p>Prepend timestamps on each line of output.<br /><strong>Environment variable</strong>: <code>$BUILDKITE_TIMESTAMP_LINES</code></p></td></tr>
+<tr id="no-ansi-timestamps"><th><code>--no-ansi-timestamps </code> <a class="Docs__attribute__link" href="#no-ansi-timestamps">#</a></th><td><p>Do not insert ANSI timestamp codes at the start of each line of job output<br /><strong>Environment variable</strong>: <code>$BUILDKITE_NO_ANSI_TIMESTAMPS</code></p></td></tr>
+<tr id="timestamp-lines"><th><code>--timestamp-lines </code> <a class="Docs__attribute__link" href="#timestamp-lines">#</a></th><td><p>Prepend timestamps on each line of job output. Has no effect unless --no-ansi-timestamps is also used<br /><strong>Environment variable</strong>: <code>$BUILDKITE_TIMESTAMP_LINES</code></p></td></tr>
 <tr id="health-check-addr"><th><code>--health-check-addr value</code> <a class="Docs__attribute__link" href="#health-check-addr">#</a></th><td><p>Start an HTTP server on this addr:port that returns whether the agent is healthy, disabled by default<br /><strong>Environment variable</strong>: <code>$BUILDKITE_AGENT_HEALTH_CHECK_ADDR</code></p></td></tr>
 <tr id="no-pty"><th><code>--no-pty </code> <a class="Docs__attribute__link" href="#no-pty">#</a></th><td><p>Do not run jobs within a pseudo terminal<br /><strong>Environment variable</strong>: <code>$BUILDKITE_NO_PTY</code></p></td></tr>
 <tr id="no-ssh-keyscan"><th><code>--no-ssh-keyscan </code> <a class="Docs__attribute__link" href="#no-ssh-keyscan">#</a></th><td><p>Don't automatically run ssh-keyscan before checkout<br /><strong>Environment variable</strong>: <code>$BUILDKITE_NO_SSH_KEYSCAN</code></p></td></tr>