Default git commit verification to strict in v4

agent/integration/job_environment_integration_test.go

@@ -759,19 +759,19 @@ func TestCheckoutScopedJobEnvOverrideHonorsCheckoutOverrideMode(t *testing.T) {
 			wantIgnoredEnvVars: []string{"BUILDKITE_GIT_CHECKOUT_TIMEOUT"},
 		},
 		// Commit verification is an enum (not a flag) but is checkout-override
-		// scoped, so it follows the same mode rules. The first case is the reported
-		// scenario: agent leaves it unset, the pipeline requests strict, and none
-		// lets the job env win so verification actually runs.
+		// scoped, so it follows the same mode rules. With v4's strict default, none
+		// lets the backend job env turn verification off instead.
 		{
-			name:    "none_allows_job_env_to_enable_commit_verification_when_agent_unset",
+			name:    "none_allows_job_env_to_override_default_commit_verification",
 			varName: "BUILDKITE_GIT_COMMIT_VERIFICATION",
 			jobEnv: map[string]string{
-				"BUILDKITE_GIT_COMMIT_VERIFICATION": "strict",
+				"BUILDKITE_GIT_COMMIT_VERIFICATION": "off",
 			},
 			agentCfg: agent.AgentConfiguration{
-				CheckoutOverrideMode: env.CheckoutOverrideNone,
+				GitCommitVerification: "strict",
+				CheckoutOverrideMode:  env.CheckoutOverrideNone,
 			},
-			wantEnvValue: "strict",
+			wantEnvValue: "off",
 		},
 		{
 			name:    "none_allows_job_env_to_override_commit_verification",
@@ -780,7 +780,7 @@ func TestCheckoutScopedJobEnvOverrideHonorsCheckoutOverrideMode(t *testing.T) {
 				"BUILDKITE_GIT_COMMIT_VERIFICATION": "strict",
 			},
 			agentCfg: agent.AgentConfiguration{
-				GitCommitVerification: "warn",
+				GitCommitVerification: "off",
 				CheckoutOverrideMode:  env.CheckoutOverrideNone,
 			},
 			wantEnvValue: "strict",
@@ -792,10 +792,10 @@ func TestCheckoutScopedJobEnvOverrideHonorsCheckoutOverrideMode(t *testing.T) {
 				"BUILDKITE_GIT_COMMIT_VERIFICATION": "strict",
 			},
 			agentCfg: agent.AgentConfiguration{
-				GitCommitVerification: "warn",
+				GitCommitVerification: "off",
 				CheckoutOverrideMode:  env.CheckoutOverrideStrict,
 			},
-			wantEnvValue:       "warn",
+			wantEnvValue:       "off",
 			wantIgnoredEnvVars: []string{"BUILDKITE_GIT_COMMIT_VERIFICATION"},
 		},
 		{
@@ -807,10 +807,10 @@ func TestCheckoutScopedJobEnvOverrideHonorsCheckoutOverrideMode(t *testing.T) {
 				"BUILDKITE_GIT_COMMIT_VERIFICATION": "strict",
 			},
 			agentCfg: agent.AgentConfiguration{
-				GitCommitVerification: "warn",
+				GitCommitVerification: "off",
 				CheckoutOverrideMode:  env.CheckoutOverrideFromJob,
 			},
-			wantEnvValue:       "warn",
+			wantEnvValue:       "off",
 			wantIgnoredEnvVars: []string{"BUILDKITE_GIT_COMMIT_VERIFICATION"},
 		},
 	}

clicommand/agent_start.go

@@ -820,9 +820,10 @@ var AgentStartCommand = &cli.Command{
 			}
 		}
 
-		// Validate the commit verification option input
-		if v := cfg.GitCommitVerification; v != "" && v != "strict" && v != "warn" {
-			return fmt.Errorf("invalid value for --git-commit-verification: %q (must be \"strict\" or \"warn\")", v)
+		// The config file is loaded after CLI flag validation, so validate its
+		// commit verification value here as well.
+		if err := validateGitCommitVerification(cfg.GitCommitVerification); err != nil {
+			return err
 		}
 
 		// Force some settings if on Windows (these aren't supported yet)

clicommand/global.go

@@ -198,6 +198,18 @@ var (
 	}
 )
 
+func validateGitCommitVerification(value string) error {
+	if value != job.GitCommitVerificationStrict && value != job.GitCommitVerificationOff {
+		return fmt.Errorf(
+			"invalid value for --git-commit-verification: %q (must be %q or %q)",
+			value,
+			job.GitCommitVerificationStrict,
+			job.GitCommitVerificationOff,
+		)
+	}
+	return nil
+}
+
 // Git related flags shared between agent start and bootstrap
 var (
 	SkipCheckoutFlag = &cli.BoolFlag{
@@ -246,9 +258,12 @@ var (
 	}
 
 	GitCommitVerificationFlag = &cli.StringFlag{
-		Name:    "git-commit-verification",
-		Usage:   "Enable git commit verification",
-		Sources: cli.EnvVars("BUILDKITE_GIT_COMMIT_VERIFICATION"),
+		Name:             "git-commit-verification",
+		Value:            job.GitCommitVerificationStrict,
+		Usage:            "Verify that the commit being built exists on the specified branch; one of strict or off",
+		Sources:          cli.EnvVars("BUILDKITE_GIT_COMMIT_VERIFICATION"),
+		ValidateDefaults: true,
+		Validator:        validateGitCommitVerification,
 	}
 
 	GitFetchFlagsFlag = &cli.StringFlag{

clicommand/global_test.go

@@ -1,10 +1,12 @@
 package clicommand
 
 import (
+	"context"
 	"slices"
 	"testing"
 
 	"github.com/google/go-cmp/cmp"
+	"github.com/urfave/cli/v3"
 )
 
 func TestAllFlagEnvs(t *testing.T) {
@@ -23,3 +25,49 @@ func TestAllFlagEnvs(t *testing.T) {
 		t.Errorf("allFlagEnvs(EnvDumpCommand) diff (-got +want):\n%s", diff)
 	}
 }
+
+func TestGitCommitVerificationFlag(t *testing.T) {
+	tests := []struct {
+		name string
+		args []string
+		want string
+	}{
+		{
+			name: "defaults to strict",
+			want: "strict",
+		},
+		{
+			name: "can be overridden with off",
+			args: []string{"--git-commit-verification", "off"},
+			want: "off",
+		},
+	}
+
+	for _, test := range tests {
+		t.Run(test.name, func(t *testing.T) {
+			flag := &cli.StringFlag{
+				Name:             GitCommitVerificationFlag.Name,
+				Value:            GitCommitVerificationFlag.Value,
+				ValidateDefaults: GitCommitVerificationFlag.ValidateDefaults,
+				Validator:        GitCommitVerificationFlag.Validator,
+			}
+
+			var got string
+			command := &cli.Command{
+				Name:  "test",
+				Flags: []cli.Flag{flag},
+				Action: func(_ context.Context, command *cli.Command) error {
+					got = command.String("git-commit-verification")
+					return nil
+				},
+			}
+
+			if err := command.Run(t.Context(), append([]string{"test"}, test.args...)); err != nil {
+				t.Fatalf("command.Run() error = %v", err)
+			}
+			if got != test.want {
+				t.Errorf("git-commit-verification = %q, want %q", got, test.want)
+			}
+		})
+	}
+}

env/protected.go

@@ -103,12 +103,12 @@ var protectedEnv = map[string]protection{
 // Locking matters because git is riddled with shell injections, so letting a job
 // set git flags would otherwise be a way to bypass protections like
 // no-command-eval (which is why disabling command-eval forces the mode to
-// strict). BUILDKITE_GIT_COMMIT_VERIFICATION is an enum ("", "warn", "strict"),
+// strict). BUILDKITE_GIT_COMMIT_VERIFICATION is an enum ("strict", "off"),
 // not an injection vector, but the backend exposes it under `checkout:` alongside
-// the flag vars, so it's governed by the mode too: only none lets a job's own
-// checkout config (pipeline/step env, secrets) turn verification on, matching the
-// other checkout settings. Vars here must not also appear in protectedEnv; the
-// two maps are disjoint.
+// the flag vars, so it's governed by the mode too: only none lets the backend job
+// env and secrets select the verification mode, matching the other checkout
+// settings. Vars here must not also appear in protectedEnv; the two maps are
+// disjoint.
 var checkoutOverrideScope = map[string]struct{}{
 	"BUILDKITE_GIT_CHECKOUT_FLAGS":              {},
 	"BUILDKITE_GIT_CHECKOUT_TIMEOUT":            {},

internal/job/commit_verification.go

@@ -21,6 +21,13 @@ var ErrCommitVerificationFailed = errors.New("commit verification failed")
 // This is NOT evidence of an attack — it's an infrastructure problem.
 var ErrCommitVerificationUnavailable = errors.New("commit verification unavailable")
 
+const (
+	// GitCommitVerificationStrict checks branch ancestry and blocks a definitive mismatch.
+	GitCommitVerificationStrict = "strict"
+	// GitCommitVerificationOff skips branch ancestry verification entirely.
+	GitCommitVerificationOff = "off"
+)
+
 // checkCommitOnBranch performs the actual git ancestry check, handling shallow
 // clones by deepening or unshallowing as needed. It returns:
 //   - nil if the commit is verified on the branch
@@ -237,12 +244,24 @@ func stripRefSuppressingFetchFlags(flags []string) []string {
 	return out
 }
 
-// verifyCommit is called if the user has commit verification enabled. It ensures that the commit we are
-// asked to build exists and is reachable on the branch we are given.
+// verifyCommit ensures that the commit we are asked to build exists and is
+// reachable on the branch we are given.
 func (e *Executor) verifyCommit(ctx context.Context) error {
-	// Skip if not enabled
-	if e.GitCommitVerification == "" {
+	switch e.GitCommitVerification {
+	case GitCommitVerificationOff:
+		e.shell.Commentf("Skipping commit verification: mode is off")
 		return nil
+	case GitCommitVerificationStrict, "":
+		// The zero value is treated as strict for programmatic ExecutorConfig
+		// consumers. The CLI rejects empty values, and only explicit off skips.
+		// Continue below.
+	default:
+		return fmt.Errorf(
+			"invalid git commit verification mode %q (must be %q or %q)",
+			e.GitCommitVerification,
+			GitCommitVerificationStrict,
+			GitCommitVerificationOff,
+		)
 	}
 
 	// Skip if commit is HEAD (nothing to verify)
@@ -287,17 +306,11 @@ func (e *Executor) verifyCommit(ctx context.Context) error {
 
 	// Definitive failure — commit is provably not on the branch
 	if errors.Is(err, ErrCommitVerificationFailed) {
-		if e.GitCommitVerification == "strict" {
-			return err
-		}
-		// err already begins with "commit verification failed", so log it as-is.
-		e.shell.Warningf("%s", err)
-		return nil
+		return err
 	}
 
-	// Verification unavailable — infrastructure issue, not a security concern.
-	// We always warn but never block, even in strict mode, to avoid users
-	// disabling verification entirely due to infrastructure false positives.
+	// Verification unavailable — infrastructure issue, not a definitive mismatch.
+	// We always warn but never block, even in strict mode.
 	// err already begins with "commit verification unavailable", so log it as-is.
 	e.shell.Warningf("%s", err)
 	return nil