Add checkout-override-mode option

[petetomasik]

Description

The agent exposes a number of checkout-related environment variables (git clone/fetch/checkout/clean flags, sparse-checkout paths, submodules, skip-fetch-existing-commits, skip-checkout). Historically the protections around these were implicit and inconsistent: some were silently overwritten by agent config in createEnvironment, others were overridable from the backend job env, hooks, plugins, the Job API, or secrets, with the rules spread across a single protectedEnv map and scattered logic. Because git flags are a shell-injection vector (for example --upload-pack, -c core.sshCommand, ext:: transports), letting a job set them can be equivalent to arbitrary command execution and a way to bypass no-command-eval.

This PR replaces that implicit handling with an explicit, tri-state --checkout-override-mode flag (env BUILDKITE_CHECKOUT_OVERRIDE_MODE), shared by agent start and bootstrap, controlling which sources may override the agent's checkout-scoped configuration:

• strict — the agent is authoritative against every source: pipeline/step env, secrets, hooks, plugins, and the Job API.
• from-job (default) — hooks, plugins, and the Job API may set checkout-scoped vars (so a job can still tailor its own checkout), but the backend job env (pipeline/step env) and secrets may not. This matches the agent's historical behavior.
• none — any source, including the backend job env and secrets, may set them.

Disabling command evaluation via no-command-eval=true forces the mode to strict regardless of the configured value, so git flags can never be used to undermine no-command-eval.

The protection model lives in env/protected.go and is split into two disjoint tiers (disjointness enforced by a test):

• protectedEnv — always agent-authoritative in every mode: agent infrastructure, all mirror configuration (BUILDKITE_GIT_MIRRORS_PATH, BUILDKITE_GIT_MIRRORS_LOCK_TIMEOUT, BUILDKITE_GIT_MIRRORS_SKIP_UPDATE, BUILDKITE_GIT_MIRROR_CHECKOUT_MODE, BUILDKITE_GIT_CLONE_MIRROR_FLAGS), and BUILDKITE_GIT_SUBMODULE_CLONE_CONFIG.
• checkoutOverrideScope — the checkout-scoped vars whose lock depends on the mode: BUILDKITE_GIT_CHECKOUT_FLAGS, BUILDKITE_GIT_CHECKOUT_TIMEOUT, BUILDKITE_GIT_CLEAN_FLAGS, BUILDKITE_GIT_CLONE_FLAGS, BUILDKITE_GIT_FETCH_FLAGS, BUILDKITE_GIT_SKIP_FETCH_EXISTING_COMMITS, BUILDKITE_GIT_SPARSE_CHECKOUT_PATHS, BUILDKITE_GIT_SUBMODULES, BUILDKITE_SKIP_CHECKOUT.

Context

Linear

Changes

New CLI flag, shared by agent start and bootstrap:

--checkout-override-mode value   Controls which sources may override the agent's checkout settings;
                                 one of [strict from-job none]. 'strict' makes the agent authoritative
                                 against pipeline/step env, secrets, hooks, plugins, and the Job API.
                                 'from-job' (default) lets hooks, plugins, and the Job API set checkout
                                 vars, but blocks pipeline/step env and secrets. 'none' additionally
                                 lets pipeline/step env and secrets set them. All mirror configuration
                                 and submodule clone config stay agent-authoritative in every mode. The
                                 checkout SSH key and Git LFS toggle are not governed by this flag and
                                 stay job-settable in every mode. Disabling command-eval forces this to
                                 'strict'.
                                 (default: "from-job") [$BUILDKITE_CHECKOUT_OVERRIDE_MODE]

• Adds a CheckoutOverrideMode type in env (strict/from-job/none) with ParseCheckoutOverrideMode, String, and RestrictedForCommandEval (forces strict when command-eval is off).
• Wires the mode through AgentConfiguration, AgentStartConfig, BootstrapConfig, ExecutorConfig, and the Job API server (WithCheckoutOverrideMode), via a shared resolveCheckoutOverrideMode helper that applies the command-eval floor. ExecutorConfig.CheckoutOverrideMode has no env tag, so a hook cannot relax the mode mid-job.
• Splits env/protected.go into protectedEnv (always protected) and checkoutOverrideScope (mode-dependent), and adds predicates IsCheckoutOverrideScoped, IsCheckoutLocked (within-job sources: hooks, plugins, and the Job API; strict only), and IsCheckoutLockedForSecrets (secrets; every mode except none). The backend job env follows the same rule as secrets (locked in every mode except none), enforced in createEnvironment. The two maps are asserted disjoint.
• Enforces the mode at every point a job can reach checkout config: backend job-env precedence in createEnvironment (setCheckoutEnv), runtime config refresh in ReadFromEnvironment, hook env changes in applyEnvironmentChanges, secret-to-env mappings in fetchAndSetSecrets, and Job API patch/delete (checkProtected).
• Makes all mirror configuration and BUILDKITE_GIT_SUBMODULE_CLONE_CONFIG always agent-authoritative, including moving BUILDKITE_GIT_MIRRORS_SKIP_UPDATE and BUILDKITE_GIT_CLONE_MIRROR_FLAGS out of the mode-dependent scope (the mirror is shared infrastructure and clone-mirror flags are a cross-job injection vector).
• The Job API rejection message names the checkout-override lock when that is the reason for rejection.
• Adds unit and integration coverage across env, internal/job config, the agent job runner, and the hooks/plugins/secrets/Job API paths, including: the job-env override matrix across all three modes, infra vars staying agent-authoritative even under none, secrets rejected for the protected checkout-infra vars, and an end-to-end test that disabling command-eval auto-forces strict.

Agent behavior changes

Under from-job (the default), checkout-scoped vars remain overridable from within-job sources (hooks, plugins, and the Job API) but not from the backend job env or secrets, matching the agent's historical behavior. strict offers a more protected behavior: hooks and plugins can no longer set the checkout-scoped or mirror vars (on main several were mutable from within the job). none is the only mode that opens checkout-scoped vars to the backend job env and secrets.

Testing

• Tests have run locally (with go test ./...).
• Code is formatted (with go tool gofumpt -extra -w .)

go test ./... passes locally, including the full checkout-override-mode unit and integration coverage across env, internal/job, agent, jobapi, and clicommand.

Disclosures / Credits

Code generated by Claude Code (Opus 4.8) under my guidance. Multiple reviews were conducted to establish the correctness and completeness of the implementation of this new agent config option and protection model. The core feature and its conversion from the earlier binary design to the tri-state mode were implemented in earlier revisions.

[buildsworth-bk-app]

I didn’t find any new issues in this pass. This is security-sensitive agent checkout/env protection logic, so it’s above my approval ceiling and I’m leaving the review as a comment.

Want to dig deeper?

The full session log is attached to this Buildkite build. Download the session file and open a new pi session with it:

Download the buildsworth logs from build 5323, then answer my questions about the findings.

[buildsworth-bk-app]

I found one blocking issue around allowed secret mappings not updating the checkout config, and left a question on the default timeout behavior.

Want to dig deeper?

The full session log is attached to this Buildkite build. Download the session file and open a new pi session with it:

Download the buildsworth logs from build 5326, then answer my questions about the findings.

Previous concerns have been addressed.

[buildsworth-bk-app]

The previous secret-refresh and timeout concerns are addressed. I found one new blocker in the secret refresh path.

This is security-sensitive agent checkout/env protection logic, so it remains above my approval ceiling.

Want to dig deeper?

The full session log is attached to this Buildkite build. Download the session file and open a new pi session with it:

Download the buildsworth logs from build 5331, then answer my questions about the findings.

Previous concerns have been addressed.

[buildsworth-bk-app]

The previous secret-refresh leak is fixed. I left one non-blocking edge case around secret-backed LFS enabling; this security-sensitive checkout/env protection change is still above my approval ceiling, so I’m leaving a comment.

Want to dig deeper?

The full session log is attached to this Buildkite build. Download the session file and open a new pi session with it:

Download the buildsworth logs from build 5332, then answer my questions about the findings.

[buildsworth-bk-app]

I found one help-text mismatch in the new mode description and left a related LFS timing follow-up in the existing thread. This remains security-sensitive agent checkout/env protection logic, so it’s above my approval ceiling.

Want to dig deeper?

The full session log is attached to this Buildkite build. Download the session file and open a new pi session with it:

Download the buildsworth logs from build 5333, then answer my questions about the findings.

[buildsworth-bk-app]

The previous LFS timing and help-text concerns are addressed. I didn’t find any new issues in this pass; this is still security-sensitive agent checkout/env protection logic, so it’s above my approval ceiling.

Want to dig deeper?

The full session log is attached to this Buildkite build. Download the session file and open a new pi session with it:

Download the buildsworth logs from build 5335, then answer my questions about the findings.