Document strict commit verification default in agent v4

data/content/environment_variables.yaml

@@ -240,11 +240,12 @@ variables:
     example: "-v"
   - name: BUILDKITE_GIT_COMMIT_VERIFICATION
     desc: |
-      Controls whether the agent verifies that the commit being built exists on the specified branch. Set automatically from the `checkout.commit_verification` key in your pipeline YAML, or from the agent's `--git-commit-verification` configuration setting. When set to `strict`, the agent fails the job when it determines the commit is not on the branch. When set to `warn`, the agent emits a warning without failing the job. If the agent cannot complete the check, it warns and continues in both modes. The agent skips verification for tag builds, pull request builds, builds where the commit is `HEAD`, builds with no branch set, and builds using a custom refspec.
+      Controls whether the agent verifies that the commit being built exists on the specified branch. Set automatically from the `checkout.commit_verification` key in your pipeline YAML, or from the agent's `--git-commit-verification` configuration setting. Buildkite agent v4 accepts `strict` or `off` and uses `strict` by default. The value `strict` fails the job when the agent determines that the commit is not on the branch. The value `off` skips verification. An empty v4 agent configuration value prevents the agent from starting. An empty value from `checkout.commit_verification` causes job bootstrap to fail when a v4 agent runs with `checkout-override-mode` set to `none`. Buildkite agent v3 accepts `strict`, `warn`, or an empty value. The value `strict` fails the job, `warn` emits a warning without failing the job, and an empty value skips verification. Do not use `off` with v3. The value prevents a v3 agent from starting when supplied in agent configuration. When supplied by `checkout.commit_verification`, `off` uses warning behavior rather than skipping verification. If the agent cannot complete the check, it warns and continues. The agent skips verification for tag builds, pull request builds, builds where the commit is `HEAD`, builds with no branch set, and builds using a custom refspec.
     modifiable: false
     values:
       - strict
       - warn
+      - off
   - name: BUILDKITE_GIT_FETCH_FLAGS
     desc: |
       The value of the `git-fetch-flags` [agent configuration option](/docs/agent/self-hosted/configure). The value can be modified by exporting the environment variable in the `environment` or `pre-checkout` hooks. Setting this variable or the `checkout.flags.fetch` key in pipeline YAML requires the agent to run with `checkout-override-mode` set to `none`.

pages/agent/v3_v4_upgrade_guide.md

@@ -21,6 +21,7 @@ Most agent setups need no changes for v4. Read the following breaking changes ca
 
 - After repository checkout, the agent resolves `BUILDKITE_COMMIT` to a commit hash. This change is useful when the initial value is a refspec such as `HEAD`.
 - The OpenSSH option `StrictHostKeyChecking=accept-new` has replaced the built-in SSH key scan and `known-hosts` file updater in the default checkout process. The default checkout process now requires OpenSSH version 7.6 or later unless you enable `--no-ssh-keyscan` or `BUILDKITE_NO_SSH_KEYSCAN`. OpenSSH 7.6 was released in 2017.
+- [Git commit verification](/docs/pipelines/configure/git-checkout#commit-verification) now defaults to `strict`. The agent fails a job when it determines that the requested commit is not on the specified branch. To disable verification, set the `git-commit-verification` agent configuration option or `BUILDKITE_GIT_COMMIT_VERIFICATION` environment variable to `off`. Before upgrading, replace any v3 `warn` value with `strict` or `off`. Replace any empty value used to disable verification with `off`. In v4, an empty agent configuration value prevents the agent from starting. An empty value supplied by `checkout.commit_verification` causes job bootstrap to fail when the agent runs with `checkout-override-mode` set to `none`.
 
 ### Changes to agent parallelism
 

pages/pipelines/configure/git_checkout.md

@@ -470,14 +470,14 @@ steps:
 
 The `checkout.commit_verification` key tells the Buildkite agent to verify that the commit being built exists on the specified branch. This security feature is a branch-commit verification check, not GPG or SSH signature verification. This check protects against a scenario where a bad actor tries to trick CI into building a malicious commit that exists on a branch as though it is actually a commit on your `main` branch.
 
-Two modes are available:
+The supported values depend on the Buildkite agent version:
 
-- `strict`: Fails the job when the agent determines the commit is not on the branch.
-- `warn`: Emits a warning in the build log without failing the job.
+- **Buildkite agent v4:** Set the value to `strict` to fail the job when the agent determines that the commit is not on the branch. Set the value to `off` to skip commit verification. An empty value causes job bootstrap to fail.
+- **Buildkite agent v3:** Set the value to `strict` to fail the job, or `warn` to emit a warning without failing the job. An empty value skips commit verification. Do not use `off` with v3. A job-supplied `off` value uses warning behavior rather than skipping verification.
 
-If the agent cannot complete the check (for example, because a shallow clone cannot be deepened), it warns and continues in both modes.
+If the agent cannot complete the check (for example, because a shallow clone cannot be deepened), it warns and continues.
 
-When omitted, the agent falls back to its own `--git-commit-verification` [configuration setting](/docs/agent/self-hosted/configure#configuration-settings).
+When omitted, the agent falls back to its own `--git-commit-verification` [configuration setting](/docs/agent/self-hosted/configure#configuration-settings). Buildkite agent v4 uses `strict` by default. To disable verification, configure a v4 agent with `git-commit-verification="off"`. An empty v4 agent configuration value prevents the agent from starting. Buildkite agent v3 does not verify commits by default. To disable verification explicitly, leave the v3 agent configuration value empty. The value `off` prevents a v3 agent from starting.
 
 > 📘 Requires none mode
 > The `checkout.commit_verification` key only takes effect when the agent runs with `--checkout-override-mode=none`. Under the default `from-job` mode, the agent uses its own `--git-commit-verification` setting and ignores the pipeline value. See [Agent checkout-override mode](#agent-checkout-override-mode).

pages/pipelines/configure/step_types/command_step.md

@@ -408,7 +408,9 @@ For `flags`, `commit_verification`, and `sparse`, an explicit entry in the step'
   <tr>
     <td><code>commit_verification</code></td>
     <td>
-      <p>Whether the agent should verify that the commit being built exists on the specified branch. Set to <code>strict</code> to fail the job when the agent determines the commit is not on the branch, or <code>warn</code> to emit a warning without failing. If the agent cannot complete the check (for example, due to a shallow clone that cannot be deepened), it warns and continues in both modes. Emitted as <a href="/docs/pipelines/configure/environment-variables#BUILDKITE_GIT_COMMIT_VERIFICATION"><code>BUILDKITE_GIT_COMMIT_VERIFICATION</code></a>. When omitted, the agent falls back to its own <code>--git-commit-verification</code> <a href="/docs/agent/self-hosted/configure#configuration-settings">configuration setting</a>.</p>
+      <p>Whether the agent should verify that the commit being built exists on the specified branch. For Buildkite agent v4, set the value to <code>strict</code> to fail the job when the agent determines that the commit is not on the branch. Set the value to <code>off</code> to skip verification. An empty value causes job bootstrap to fail.</p>
+      <p>For Buildkite agent v3, set the value to <code>strict</code> to fail the job, or <code>warn</code> to emit a warning without failing the job. An empty value skips verification. Do not use <code>off</code> with v3. A job-supplied <code>off</code> value uses warning behavior rather than skipping verification.</p>
+      <p>If the agent cannot complete the check (for example, due to a shallow clone that cannot be deepened), it warns and continues. The value is emitted as <a href="/docs/pipelines/configure/environment-variables#BUILDKITE_GIT_COMMIT_VERIFICATION"><code>BUILDKITE_GIT_COMMIT_VERIFICATION</code></a>. When omitted, the agent falls back to its own <code>--git-commit-verification</code> <a href="/docs/agent/self-hosted/configure#configuration-settings">configuration setting</a>. Buildkite agent v4 uses <code>strict</code> by default. Buildkite agent v3 does not verify commits by default.</p>
       <p>The agent skips verification for tag builds, pull request builds, builds where the commit is <code>HEAD</code>, builds with no branch set, and builds using a custom refspec. In each of these cases, verification is either not possible or not meaningful.</p>
       <em>Example:</em> <code>strict</code>
     </td>