Disable checkout by default for pull_request_target workflows

pkg/workflow/pr.go

@@ -10,8 +10,12 @@ import (
 var prLog = logger.New("workflow:pr")
 
 // ShouldGeneratePRCheckoutStep returns true if the checkout-pr step should be generated
-// based on the workflow permissions. The step requires contents read access.
+// based on the workflow permissions and checkout configuration.
+// The step requires contents read access and checkout must not be disabled.
 func ShouldGeneratePRCheckoutStep(data *WorkflowData) bool {
+	if data.CheckoutDisabled {
+		return false
+	}
 	if data.CachedPermissions != nil {
 		return data.CachedPermissions.HasContentsReadAccess()
 	}

pkg/workflow/pr_ready_for_review_checkout_test.go

@@ -224,3 +224,121 @@ Test workflow with pull_request triggers.
 		}
 	}
 }
+
+// TestPullRequestTargetCheckoutDisabledByDefault verifies that pull_request_target workflows
+// do not generate a "Checkout PR branch" step when checkout is not explicitly configured.
+// This prevents the step from hard-failing when head branches are deleted (merged PRs) or
+// inaccessible (fork PRs).
+func TestPullRequestTargetCheckoutDisabledByDefault(t *testing.T) {
+	tests := []struct {
+		name             string
+		workflowContent  string
+		expectPRCheckout bool
+		description      string
+	}{
+		{
+			name: "pull_request_target with no checkout key - no PR checkout step",
+			workflowContent: `---
+on:
+  pull_request_target:
+    types: [closed]
+permissions:
+  contents: read
+  pull-requests: read
+engine: claude
+strict: false
+---
+
+# Thank you note workflow
+Workflow triggered when a PR is closed.
+`,
+			expectPRCheckout: false,
+			description:      "pull_request_target without explicit checkout key should not generate 'Checkout PR branch' step",
+		},
+		{
+			name: "pull_request_target with checkout: false - no PR checkout step",
+			workflowContent: `---
+on:
+  pull_request_target:
+    types: [closed]
+permissions:
+  contents: read
+  pull-requests: read
+engine: claude
+strict: false
+checkout: false
+---
+
+# Thank you note workflow
+Workflow triggered when a PR is closed.
+`,
+			expectPRCheckout: false,
+			description:      "pull_request_target with explicit checkout: false should not generate 'Checkout PR branch' step",
+		},
+		{
+			name: "pull_request_target with trusted checkout mapping - PR checkout step present",
+			workflowContent: `---
+on:
+  pull_request_target:
+    types: [opened]
+permissions:
+  contents: read
+  pull-requests: read
+engine: claude
+checkout:
+  repository: ${{ github.repository }}
+  ref: ${{ github.event.pull_request.base.sha }}
+---
+
+# PR review workflow
+Workflow triggered when a PR is opened with a trusted base checkout.
+`,
+			expectPRCheckout: true,
+			description:      "pull_request_target with explicit checkout mapping should generate 'Checkout PR branch' step",
+		},
+	}
+
+	for _, tt := range tests {
+		t.Run(tt.name, func(t *testing.T) {
+			// Create temporary directory for test
+			tempDir, err := os.MkdirTemp("", "prt-checkout-test")
+			if err != nil {
+				t.Fatalf("Failed to create temp dir: %v", err)
+			}
+			defer os.RemoveAll(tempDir)
+
+			// Create workflows directory
+			workflowsDir := filepath.Join(tempDir, ".github", "workflows")
+			if err := os.MkdirAll(workflowsDir, 0755); err != nil {
+				t.Fatalf("Failed to create workflows directory: %v", err)
+			}
+
+			// Write test workflow file
+			workflowPath := filepath.Join(workflowsDir, "test-prt-workflow.md")
+			if err := os.WriteFile(workflowPath, []byte(tt.workflowContent), 0644); err != nil {
+				t.Fatalf("Failed to write workflow file: %v", err)
+			}
+
+			// Compile workflow
+			compiler := NewCompiler()
+			compiler.SetActionMode(ActionModeDev)
+			if err := compiler.CompileWorkflow(workflowPath); err != nil {
+				t.Fatalf("Failed to compile workflow: %v", err)
+			}
+
+			// Read generated lock file
+			lockPath := filepath.Join(workflowsDir, "test-prt-workflow.lock.yml")
+			lockContent, err := os.ReadFile(lockPath)
+			if err != nil {
+				t.Fatalf("Failed to read lock file: %v", err)
+			}
+			lockStr := string(lockContent)
+
+			// Check for PR checkout step
+			hasPRCheckout := strings.Contains(lockStr, "Checkout PR branch")
+			if hasPRCheckout != tt.expectPRCheckout {
+				t.Errorf("%s: expected PR checkout step: %v, got: %v", tt.description, tt.expectPRCheckout, hasPRCheckout)
+			}
+		})
+	}
+}

pkg/workflow/pr_test.go

@@ -76,6 +76,26 @@ pull-requests: read`,
 	}
 }
 
+func TestShouldGeneratePRCheckoutStep_CheckoutDisabled(t *testing.T) {
+	t.Run("returns false when CheckoutDisabled is true even with contents read", func(t *testing.T) {
+		data := &WorkflowData{
+			Permissions:      "contents: read",
+			CheckoutDisabled: true,
+		}
+		result := ShouldGeneratePRCheckoutStep(data)
+		assert.False(t, result, "ShouldGeneratePRCheckoutStep() should return false when CheckoutDisabled is true")
+	})
+
+	t.Run("returns true when CheckoutDisabled is false with contents read", func(t *testing.T) {
+		data := &WorkflowData{
+			Permissions:      "contents: read",
+			CheckoutDisabled: false,
+		}
+		result := ShouldGeneratePRCheckoutStep(data)
+		assert.True(t, result, "ShouldGeneratePRCheckoutStep() should return true when CheckoutDisabled is false and permissions allow")
+	})
+}
+
 func TestGeneratePRReadyForReviewCheckout_IncludesWorkflowDispatchIssueCommentContext(t *testing.T) {
 	compiler := NewCompiler()
 	var yaml strings.Builder

pkg/workflow/pull_request_target_validation_test.go

@@ -52,7 +52,7 @@ Test workflow content.`,
 			warningCount:  1, // sandbox.agent: false
 		},
 		{
-			name: "pull_request_target with checkout enabled - non-strict - should warn",
+			name: "pull_request_target with no checkout key - non-strict - checkout auto-disabled",
 			frontmatter: `---
 strict: false
 on:
@@ -72,7 +72,7 @@ Test workflow content.`,
 			strictMode:    false,
 			expectError:   false,
 			expectWarning: true,
-			warningCount:  2, // 1 for insecure checkout + 1 for sandbox.agent: false
+			warningCount:  1, // checkout is auto-disabled for pull_request_target; only sandbox.agent: false warning
 		},
 		{
 			name: "pull_request_target with trusted checkout - non-strict - no warnings no error",
@@ -170,7 +170,7 @@ Test workflow content.`,
 			warningCount:  1, // dangerous-trigger warning
 		},
 		{
-			name: "pull_request_target with checkout enabled - strict - error (extremely insecure)",
+			name: "pull_request_target with no checkout key - strict - checkout auto-disabled, dangerous-trigger warning only",
 			frontmatter: `---
 on:
   pull_request_target:
@@ -186,10 +186,9 @@ permissions:
 Test workflow content.`,
 			filename:      "prt-checkout-enabled-strict.md",
 			strictMode:    true,
-			expectError:   true,
-			expectWarning: true, // dangerous-trigger warning is still emitted before the error
-			errorContains: "pull_request_target trigger with checkout enabled is extremely insecure",
-			warningCount:  1, // dangerous-trigger warning
+			expectError:   false,
+			expectWarning: true, // dangerous-trigger warning only; checkout auto-disabled so no insecure-checkout error
+			warningCount:  1,    // dangerous-trigger warning
 		},
 		{
 			name: "pull_request_target with explicit checkout pinned to base sha - strict - warning only",
@@ -341,7 +340,7 @@ Test workflow content.`,
 			warningCount:  1, // dangerous-trigger warning
 		},
 		{
-			name: "pull_request_target with checkout enabled - strict CLI + frontmatter strict false - warning only",
+			name: "pull_request_target with no checkout key - strict CLI + frontmatter strict false - no warnings",
 			frontmatter: `---
 strict: false
 on:
@@ -359,8 +358,8 @@ Test workflow content.`,
 			filename:      "prt-checkout-enabled-strict-frontmatter-opt-out.md",
 			strictMode:    true,
 			expectError:   false,
-			expectWarning: true,
-			warningCount:  1, // insecure-checkout warning only
+			expectWarning: false,
+			warningCount:  0, // checkout auto-disabled; strict:false suppresses dangerous-trigger warning; no insecure-checkout warning
 		},
 		{
 			name: "pull_request trigger (not target) - strict - no diagnostic",

pkg/workflow/workflow_builder.go

@@ -105,6 +105,23 @@ func (c *Compiler) buildInitialWorkflowData(
 		}
 	}
 
+	// Auto-disable checkout for pull_request_target workflows when not explicitly configured.
+	// For pull_request_target events, the head branch is often deleted (closed/merged PRs)
+	// or inaccessible (fork PRs), causing the "Checkout PR branch" step to fail.
+	// Users who need checkout can explicitly set a checkout configuration in frontmatter.
+	if len(workflowData.CheckoutConfigs) == 0 {
+		if _, checkoutExplicitlySet := result.Frontmatter["checkout"]; !checkoutExplicitlySet {
+			if onVal, ok := result.Frontmatter["on"]; ok {
+				if onMap, ok := onVal.(map[string]any); ok {
+					if _, hasPRT := onMap["pull_request_target"]; hasPRT {
+						workflowBuilderLog.Print("Auto-disabling checkout for pull_request_target workflow")
+						workflowData.CheckoutDisabled = true
+					}
+				}
+			}
+		}
+	}
+
 	// Merge checkout configs from imported shared workflows.
 	// Imported configs are appended after the main workflow's configs so that the main
 	// workflow's entries take precedence when CheckoutManager deduplicates by (repository, path).