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,22 +1023,17 @@ 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 {
-		printer.StepFail("Failed to commit scaffold files")
-		return fmt.Errorf("committing scaffold files: %w", err)
-	}
-	if committed {
-		noun := "files"
-		if len(files) == 1 {
-			noun = "file"
-		}
-		printer.StepDone(fmt.Sprintf("Pushed %d %s to %s", len(files), noun, targetRepo.DefaultBranch))
-	} else {
-		printer.StepDone("Scaffold up to date")
+	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)
+	if err := layers.CommitScaffoldFiles(ctx, client, printer,
+		owner, repo, targetRepo.DefaultBranch,
+		commitMsg, "chore: initialize fullsend per-repo installation", prBody, files); err != nil {
+		return err
 	}
 
 	printer.StepStart("Configuring repository variables")

internal/cli/admin_test.go

@@ -1980,6 +1980,8 @@ func TestApplyPerRepoScaffold_CommitFilesError(t *testing.T) {
 		"acme", "widget", files, nil, nil)
 	require.Error(t, err)
 	assert.Contains(t, err.Error(), "committing scaffold files")
+	assert.Empty(t, client.CreatedBranches, "should not attempt fallback for generic error")
+	assert.Empty(t, client.CreatedProposals, "should not attempt fallback for generic error")
 }
 
 func TestApplyPerRepoScaffold_Idempotent(t *testing.T) {
@@ -2046,3 +2048,169 @@ 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")
+}
+
+func TestApplyPerRepoScaffold_ProtectedBranch_CreateBranchFails(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("forbidden")
+	printer := ui.New(&bytes.Buffer{})
+
+	files := []forge.TreeFile{
+		{Path: ".fullsend/config.yaml", Content: []byte("cfg"), Mode: "100644"},
+	}
+
+	err := applyPerRepoScaffold(context.Background(), client, printer,
+		"acme", "widget", files, nil, nil)
+	require.Error(t, err)
+	assert.Contains(t, err.Error(), "creating scaffold branch")
+}
+
+func TestApplyPerRepoScaffold_ProtectedBranch_CommitToBranchFails(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["CommitFilesToBranch"] = fmt.Errorf("server error")
+	printer := ui.New(&bytes.Buffer{})
+
+	files := []forge.TreeFile{
+		{Path: ".fullsend/config.yaml", Content: []byte("cfg"), Mode: "100644"},
+	}
+
+	err := applyPerRepoScaffold(context.Background(), client, printer,
+		"acme", "widget", files, nil, nil)
+	require.Error(t, err)
+	assert.Contains(t, err.Error(), "committing scaffold files to branch")
+}
+
+func TestApplyPerRepoScaffold_ProtectedBranch_CreatePRFails(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["CreateChangeProposal"] = fmt.Errorf("forbidden")
+	printer := ui.New(&bytes.Buffer{})
+
+	files := []forge.TreeFile{
+		{Path: ".fullsend/config.yaml", Content: []byte("cfg"), Mode: "100644"},
+	}
+
+	err := applyPerRepoScaffold(context.Background(), client, printer,
+		"acme", "widget", files, nil, nil)
+	require.Error(t, err)
+	assert.Contains(t, err.Error(), "creating scaffold PR")
+}
+
+func TestApplyPerRepoScaffold_ProtectedBranch_DuplicatePR(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["CreateChangeProposal"] = 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)
+
+	output := buf.String()
+	assert.Contains(t, output, "already exists")
+	assert.Contains(t, output, "Merge the PR")
+}
+
+func TestApplyPerRepoScaffold_ProtectedBranch_BranchUpToDate(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)
+	noChange := false
+	client.CommitFilesChanged = &noChange
+	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)
+
+	assert.Empty(t, client.CreatedProposals, "should not create PR when branch files are unchanged")
+	assert.Contains(t, buf.String(), "up to date")
+}

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