fix(cli): fall back to PR when default branch is protected

When `fullsend github setup owner/repo` or `fullsend admin install owner/repo`
encounters a protected default branch (422 on ref update), the CLI now falls back
to creating a feature branch and opening a PR with the scaffold files instead of
failing. Variables and secrets are set regardless of which path is taken.

- Add ErrBranchProtected sentinel and CommitFilesToBranch to forge.Client
- Refactor CommitFiles to detect 422 as branch protection failure
- Add PR-based fallback in applyPerRepoScaffold

Signed-off-by: Wayne Sun <gsun@redhat.com>

Author: waynesun09

internal/cli/admin.go

@@ -1023,15 +1023,44 @@ func applyPerRepoScaffold(ctx context.Context, client forge.Client, printer *ui.
 	if err != nil {
 		return fmt.Errorf("getting repo info: %w", err)
 	}
+	commitMsg := fmt.Sprintf("chore: initialize fullsend-%s per-repo installation", version)
 	printer.StepStart(fmt.Sprintf("Committing scaffold files to %s/%s (%s branch)",
 		owner, repo, targetRepo.DefaultBranch))
-	committed, err := client.CommitFiles(ctx, owner, repo,
-		fmt.Sprintf("chore: initialize fullsend-%s per-repo installation", version), files)
-	if err != nil {
+	committed, err := client.CommitFiles(ctx, owner, repo, commitMsg, files)
+	if err != nil && forge.IsBranchProtected(err) {
+		printer.StepWarn("Default branch is protected — creating scaffold PR instead")
+
+		const scaffoldBranch = "fullsend/scaffold-install"
+		if branchErr := client.CreateBranch(ctx, owner, repo, scaffoldBranch); branchErr != nil {
+			if !strings.Contains(branchErr.Error(), "already exists") {
+				printer.StepFail("Failed to create scaffold branch")
+				return fmt.Errorf("creating scaffold branch: %w", branchErr)
+			}
+		}
+
+		if _, commitErr := client.CommitFilesToBranch(ctx, owner, repo, scaffoldBranch, commitMsg, files); commitErr != nil {
+			printer.StepFail("Failed to commit scaffold files to branch")
+			return fmt.Errorf("committing scaffold files to branch: %w", commitErr)
+		}
+
+		prBody := fmt.Sprintf("This PR adds the fullsend scaffold files for per-repo installation.\n\n"+
+			"The default branch (%s) has branch protection rules that prevent direct pushes, "+
+			"so these files are delivered via PR instead.\n\n"+
+			"Merge this PR to activate fullsend workflows.", targetRepo.DefaultBranch)
+		proposal, prErr := client.CreateChangeProposal(ctx, owner, repo,
+			"chore: initialize fullsend per-repo installation", prBody,
+			scaffoldBranch, targetRepo.DefaultBranch)
+		if prErr != nil {
+			printer.StepFail("Failed to create scaffold PR")
+			return fmt.Errorf("creating scaffold PR: %w", prErr)
+		}
+
+		printer.StepDone(fmt.Sprintf("Created PR #%d: %s", proposal.Number, proposal.URL))
+		printer.StepInfo("Merge the PR to activate fullsend workflows")
+	} else if err != nil {
 		printer.StepFail("Failed to commit scaffold files")
 		return fmt.Errorf("committing scaffold files: %w", err)
-	}
-	if committed {
+	} else if committed {
 		noun := "files"
 		if len(files) == 1 {
 			noun = "file"

internal/cli/admin_test.go

@@ -2046,3 +2046,76 @@ func TestApplyPerRepoScaffold_CreateSecretError(t *testing.T) {
 	require.Error(t, err)
 	assert.Contains(t, err.Error(), "setting repo secret")
 }
+
+func TestApplyPerRepoScaffold_ProtectedBranchFallback(t *testing.T) {
+	client := forge.NewFakeClient()
+	client.Repos = []forge.Repository{{FullName: "acme/widget", DefaultBranch: "main"}}
+	client.Errors["CommitFiles"] = fmt.Errorf("%w: github api: 422", forge.ErrBranchProtected)
+	var buf bytes.Buffer
+	printer := ui.New(&buf)
+
+	files := []forge.TreeFile{
+		{Path: ".github/workflows/fullsend.yaml", Content: []byte("workflow"), Mode: "100644"},
+	}
+	repoVars := map[string]string{"K": "V"}
+	repoSecrets := map[string]string{"S": "secret"}
+
+	err := applyPerRepoScaffold(context.Background(), client, printer,
+		"acme", "widget", files, repoVars, repoSecrets)
+	require.NoError(t, err)
+
+	require.Len(t, client.CreatedBranches, 1)
+	assert.Equal(t, "acme/widget/fullsend/scaffold-install", client.CreatedBranches[0])
+
+	require.Len(t, client.CommittedFilesToBranch, 1)
+	assert.Equal(t, "fullsend/scaffold-install", client.CommittedFilesToBranch[0].Branch)
+	assert.Len(t, client.CommittedFilesToBranch[0].Files, 1)
+
+	require.Len(t, client.CreatedProposals, 1)
+	assert.Contains(t, client.CreatedProposals[0].Title, "fullsend")
+
+	output := buf.String()
+	assert.Contains(t, output, "protected")
+	assert.Contains(t, output, "PR #1")
+	assert.Contains(t, output, "Merge the PR")
+}
+
+func TestApplyPerRepoScaffold_ProtectedBranch_ExistingBranch(t *testing.T) {
+	client := forge.NewFakeClient()
+	client.Repos = []forge.Repository{{FullName: "acme/widget", DefaultBranch: "main"}}
+	client.Errors["CommitFiles"] = fmt.Errorf("%w: github api: 422", forge.ErrBranchProtected)
+	client.Errors["CreateBranch"] = fmt.Errorf("already exists")
+	var buf bytes.Buffer
+	printer := ui.New(&buf)
+
+	files := []forge.TreeFile{
+		{Path: ".fullsend/config.yaml", Content: []byte("cfg"), Mode: "100644"},
+	}
+
+	err := applyPerRepoScaffold(context.Background(), client, printer,
+		"acme", "widget", files, nil, nil)
+	require.NoError(t, err)
+
+	require.Len(t, client.CommittedFilesToBranch, 1, "should proceed despite branch existing")
+	require.Len(t, client.CreatedProposals, 1)
+}
+
+func TestApplyPerRepoScaffold_ProtectedBranch_StillSetsVarsAndSecrets(t *testing.T) {
+	client := forge.NewFakeClient()
+	client.Repos = []forge.Repository{{FullName: "acme/widget", DefaultBranch: "main"}}
+	client.Errors["CommitFiles"] = fmt.Errorf("%w: github api: 422", forge.ErrBranchProtected)
+	printer := ui.New(&bytes.Buffer{})
+
+	files := []forge.TreeFile{
+		{Path: ".fullsend/config.yaml", Content: []byte("cfg"), Mode: "100644"},
+	}
+	repoVars := map[string]string{"FULLSEND_MINT_URL": "https://mint.example.run.app"}
+	repoSecrets := map[string]string{"FULLSEND_GCP_PROJECT_ID": "my-project"}
+
+	err := applyPerRepoScaffold(context.Background(), client, printer,
+		"acme", "widget", files, repoVars, repoSecrets)
+	require.NoError(t, err)
+
+	assert.Len(t, client.Variables, 1, "variables should be set even with PR fallback")
+	assert.Len(t, client.CreatedSecrets, 1, "secrets should be set even with PR fallback")
+}

internal/forge/fake.go

@@ -95,6 +95,12 @@ type CommitFilesRecord struct {
 	Files                []TreeFile
 }
 
+// CommitFilesToBranchRecord records a CommitFilesToBranch call.
+type CommitFilesToBranchRecord struct {
+	Owner, Repo, Branch, Message string
+	Files                        []TreeFile
+}
+
 // FakeClient is a thread-safe test double for forge.Client.
 // Pre-populate its fields to control return values, and inspect
 // recorder slices after the test to verify which calls were made.
@@ -175,8 +181,9 @@ type FakeClient struct {
 	MinimizedComments   []MinimizedCommentRecord
 	CreatedReviews      []ReviewRecord
 	DismissedReviews    []DismissedReviewRecord
-	CommittedFiles      []CommitFilesRecord
-	DeletedComments []int // comment IDs
+	CommittedFiles        []CommitFilesRecord
+	CommittedFilesToBranch []CommitFilesToBranchRecord
+	DeletedComments       []int // comment IDs
 
 	// internal counters
 	proposalCounter int
@@ -448,6 +455,33 @@ func (f *FakeClient) CommitFiles(_ context.Context, owner, repo, message string,
 	return changed, nil
 }
 
+func (f *FakeClient) CommitFilesToBranch(_ context.Context, owner, repo, branch, message string, files []TreeFile) (bool, error) {
+	f.mu.Lock()
+	defer f.mu.Unlock()
+
+	if e := f.err("CommitFilesToBranch"); e != nil {
+		return false, e
+	}
+
+	f.CommittedFilesToBranch = append(f.CommittedFilesToBranch, CommitFilesToBranchRecord{
+		Owner:   owner,
+		Repo:    repo,
+		Branch:  branch,
+		Message: message,
+		Files:   files,
+	})
+
+	if f.FileContents == nil {
+		f.FileContents = make(map[string][]byte)
+	}
+	for _, file := range files {
+		f.FileContents[owner+"/"+repo+"/"+file.Path] = file.Content
+	}
+
+	changed := f.CommitFilesChanged == nil || *f.CommitFilesChanged
+	return changed, nil
+}
+
 func (f *FakeClient) CreateBranch(_ context.Context, owner, repo, branchName string) error {
 	f.mu.Lock()
 	defer f.mu.Unlock()

internal/forge/forge.go

@@ -24,6 +24,15 @@ func IsNotFound(err error) bool {
 	return errors.Is(err, ErrNotFound)
 }
 
+// ErrBranchProtected indicates that a ref update failed because the
+// target branch has protection rules that prevent direct pushes.
+var ErrBranchProtected = errors.New("branch is protected")
+
+// IsBranchProtected reports whether err indicates a branch protection failure.
+func IsBranchProtected(err error) bool {
+	return errors.Is(err, ErrBranchProtected)
+}
+
 // Repository represents a repository on a git forge.
 type Repository struct {
 	ID            int64
@@ -186,6 +195,11 @@ type Client interface {
 	// and it returns (false, nil).
 	CommitFiles(ctx context.Context, owner, repo, message string, files []TreeFile) (committed bool, err error)
 
+	// CommitFilesToBranch atomically commits multiple files to a specific
+	// branch. Like CommitFiles, it is idempotent: if all files already
+	// have the expected content, no commit is created.
+	CommitFilesToBranch(ctx context.Context, owner, repo, branch, message string, files []TreeFile) (committed bool, err error)
+
 	// Branch operations
 	CreateBranch(ctx context.Context, owner, repo, branchName string) error
 	CreateFileOnBranch(ctx context.Context, owner, repo, branch, path, message string, content []byte) error

internal/forge/github/github.go

@@ -599,12 +599,15 @@ func isTransientStatus(code int) bool {
 // CommitFiles atomically commits multiple files to the default branch
 // using the Git Trees/Blobs/Commits API. Returns (false, nil) when
 // all files already match the current tree (idempotent).
+//
+// Returns forge.ErrBranchProtected (wrapped) when the ref update fails
+// with a 422, which indicates branch protection rules prevent direct pushes.
 func (c *LiveClient) CommitFiles(ctx context.Context, owner, repo, message string, files []forge.TreeFile) (bool, error) {
 	if len(files) == 0 {
 		return false, nil
 	}
 
-	// 1. Get default branch name.
+	// Get default branch name.
 	repoResp, err := c.get(ctx, fmt.Sprintf("/repos/%s/%s", owner, repo))
 	if err != nil {
 		return false, fmt.Errorf("get repo: %w", err)
@@ -616,12 +619,34 @@ func (c *LiveClient) CommitFiles(ctx context.Context, owner, repo, message strin
 		return false, fmt.Errorf("decode repo info: %w", err)
 	}
 
-	// 2. Get current commit SHA from the branch ref.
-	// Wrapped in retryOnTransient for freshly-created repos where the
-	// branch ref may not be materialized yet (async auto_init).
+	committed, err := c.commitFilesTo(ctx, owner, repo, repoInfo.DefaultBranch, message, files)
+	if err != nil {
+		var apiErr *APIError
+		if errors.As(err, &apiErr) && apiErr.StatusCode == http.StatusUnprocessableEntity {
+			return false, fmt.Errorf("%w: %w", forge.ErrBranchProtected, err)
+		}
+		return false, err
+	}
+	return committed, nil
+}
+
+// CommitFilesToBranch atomically commits multiple files to a specific
+// branch. Like CommitFiles, it is idempotent.
+func (c *LiveClient) CommitFilesToBranch(ctx context.Context, owner, repo, branch, message string, files []forge.TreeFile) (bool, error) {
+	if len(files) == 0 {
+		return false, nil
+	}
+	return c.commitFilesTo(ctx, owner, repo, branch, message, files)
+}
+
+// commitFilesTo is the shared implementation for CommitFiles and
+// CommitFilesToBranch. It commits files to the specified branch using
+// the Git Trees/Blobs/Commits API.
+func (c *LiveClient) commitFilesTo(ctx context.Context, owner, repo, branch, message string, files []forge.TreeFile) (bool, error) {
+	// 1. Get current commit SHA from the branch ref.
 	var commitSHA string
 	if err := c.retryOnTransient(ctx, "get branch ref", func() error {
-		refResp, refErr := c.get(ctx, fmt.Sprintf("/repos/%s/%s/git/ref/heads/%s", owner, repo, repoInfo.DefaultBranch))
+		refResp, refErr := c.get(ctx, fmt.Sprintf("/repos/%s/%s/git/ref/heads/%s", owner, repo, branch))
 		if refErr != nil {
 			return fmt.Errorf("get branch ref: %w", refErr)
 		}
@@ -639,7 +664,7 @@ func (c *LiveClient) CommitFiles(ctx context.Context, owner, repo, message strin
 		return false, err
 	}
 
-	// 3. Get the current commit to find its tree SHA.
+	// 2. Get the current commit to find its tree SHA.
 	cResp, err := c.get(ctx, fmt.Sprintf("/repos/%s/%s/git/commits/%s", owner, repo, commitSHA))
 	if err != nil {
 		return false, fmt.Errorf("get commit: %w", err)
@@ -654,7 +679,7 @@ func (c *LiveClient) CommitFiles(ctx context.Context, owner, repo, message strin
 	}
 	baseTreeSHA := commitObj.Tree.SHA
 
-	// 4. Get the full recursive tree to compare existing blobs.
+	// 3. Get the full recursive tree to compare existing blobs.
 	treeResp, err := c.get(ctx, fmt.Sprintf("/repos/%s/%s/git/trees/%s?recursive=1", owner, repo, baseTreeSHA))
 	if err != nil {
 		return false, fmt.Errorf("get tree: %w", err)
@@ -683,7 +708,7 @@ func (c *LiveClient) CommitFiles(ctx context.Context, owner, repo, message strin
 		existing[entry.Path] = blobInfo{sha: entry.SHA, mode: entry.Mode}
 	}
 
-	// 5. Compute expected blob SHAs and filter to changed files.
+	// 4. Compute expected blob SHAs and filter to changed files.
 	var changedEntries []map[string]string
 	for _, f := range files {
 		expectedSHA := blobSHA(f.Content)
@@ -702,7 +727,7 @@ func (c *LiveClient) CommitFiles(ctx context.Context, owner, repo, message strin
 		return false, nil
 	}
 
-	// 6. Create new tree with base_tree + changed entries.
+	// 5. Create new tree with base_tree + changed entries.
 	treePayload := map[string]any{
 		"base_tree": baseTreeSHA,
 		"tree":      changedEntries,
@@ -718,7 +743,7 @@ func (c *LiveClient) CommitFiles(ctx context.Context, owner, repo, message strin
 		return false, fmt.Errorf("decode new tree: %w", err)
 	}
 
-	// 7. Create commit with new tree and old commit as parent.
+	// 6. Create commit with new tree and old commit as parent.
 	commitPayload := map[string]any{
 		"message": message,
 		"tree":    newTree.SHA,
@@ -735,11 +760,11 @@ func (c *LiveClient) CommitFiles(ctx context.Context, owner, repo, message strin
 		return false, fmt.Errorf("decode new commit: %w", err)
 	}
 
-	// 8. Update branch ref to point to new commit.
+	// 7. Update branch ref to point to new commit.
 	refPayload := map[string]string{
 		"sha": newCommit.SHA,
 	}
-	refUpdateResp, err := c.patch(ctx, fmt.Sprintf("/repos/%s/%s/git/refs/heads/%s", owner, repo, repoInfo.DefaultBranch), refPayload)
+	refUpdateResp, err := c.patch(ctx, fmt.Sprintf("/repos/%s/%s/git/refs/heads/%s", owner, repo, branch), refPayload)
 	if err != nil {
 		return false, fmt.Errorf("update ref: %w", err)
 	}