feat: add labels to github PRs (#773)

Adds -l/--label flags to set labels on GitHub PRs.
Can also be set with the spice.submit.label configuration option.
Includes integration tests at GitHub and git-spice script test levels.
DOES NOT include GitLab support.

Resolves #414

---------

Co-authored-by: Abhinav Gupta <[email protected]>

Author: carmooo

.changes/unreleased/Added-20250723-164325.yaml

@@ -0,0 +1,5 @@
+kind: Added
+body: >-
+  submit: Add -l/--label flag and accompanying spice.submit.label option
+  to add labels to created/updated CRs.
+time: 2025-07-23T16:43:25.552204+01:00

doc/includes/cli-reference.md

@@ -236,9 +236,10 @@ or --nav-comment=multiple to post those comments only if there are multiple CRs
 * `--force`: Force push, bypassing safety checks
 * `--no-verify`: Bypass pre-push hooks when pushing to the remote. <span class="mdx-badge"><span class="mdx-badge__icon">:material-tag:{ title="Released in version" }</span><span class="mdx-badge__text">[v0.15.0](/changelog.md#v0.15.0)</span>
 * `-u`, `--update-only`: Only update existing change requests, do not create new ones
+* `-l`, `--label=LABEL,...`: Add labels to the change request. Pass multiple times or separate with commas.
 * `--no-web`: Alias for --web=false.
 
-**Configuration**: [spice.submit.draft](/cli/config.md#spicesubmitdraft), [spice.submit.listTemplatesTimeout](/cli/config.md#spicesubmitlisttemplatestimeout), [spice.submit.navigationComment](/cli/config.md#spicesubmitnavigationcomment), [spice.submit.navigationCommentSync](/cli/config.md#spicesubmitnavigationcommentsync), [spice.submit.publish](/cli/config.md#spicesubmitpublish), [spice.submit.web](/cli/config.md#spicesubmitweb)
+**Configuration**: [spice.submit.draft](/cli/config.md#spicesubmitdraft), [spice.submit.label](/cli/config.md#spicesubmitlabel), [spice.submit.listTemplatesTimeout](/cli/config.md#spicesubmitlisttemplatestimeout), [spice.submit.navigationComment](/cli/config.md#spicesubmitnavigationcomment), [spice.submit.navigationCommentSync](/cli/config.md#spicesubmitnavigationcommentsync), [spice.submit.publish](/cli/config.md#spicesubmitpublish), [spice.submit.web](/cli/config.md#spicesubmitweb)
 
 ### gs stack restack
 
@@ -346,10 +347,11 @@ or --nav-comment=multiple to post those comments only if there are multiple CRs
 * `--force`: Force push, bypassing safety checks
 * `--no-verify`: Bypass pre-push hooks when pushing to the remote. <span class="mdx-badge"><span class="mdx-badge__icon">:material-tag:{ title="Released in version" }</span><span class="mdx-badge__text">[v0.15.0](/changelog.md#v0.15.0)</span>
 * `-u`, `--update-only`: Only update existing change requests, do not create new ones
+* `-l`, `--label=LABEL,...`: Add labels to the change request. Pass multiple times or separate with commas.
 * `--no-web`: Alias for --web=false.
 * `--branch=NAME`: Branch to start at
 
-**Configuration**: [spice.submit.draft](/cli/config.md#spicesubmitdraft), [spice.submit.listTemplatesTimeout](/cli/config.md#spicesubmitlisttemplatestimeout), [spice.submit.navigationComment](/cli/config.md#spicesubmitnavigationcomment), [spice.submit.navigationCommentSync](/cli/config.md#spicesubmitnavigationcommentsync), [spice.submit.publish](/cli/config.md#spicesubmitpublish), [spice.submit.web](/cli/config.md#spicesubmitweb)
+**Configuration**: [spice.submit.draft](/cli/config.md#spicesubmitdraft), [spice.submit.label](/cli/config.md#spicesubmitlabel), [spice.submit.listTemplatesTimeout](/cli/config.md#spicesubmitlisttemplatestimeout), [spice.submit.navigationComment](/cli/config.md#spicesubmitnavigationcomment), [spice.submit.navigationCommentSync](/cli/config.md#spicesubmitnavigationcommentsync), [spice.submit.publish](/cli/config.md#spicesubmitpublish), [spice.submit.web](/cli/config.md#spicesubmitweb)
 
 ### gs upstack restack
 
@@ -478,10 +480,11 @@ or --nav-comment=multiple to post those comments only if there are multiple CRs
 * `--force`: Force push, bypassing safety checks
 * `--no-verify`: Bypass pre-push hooks when pushing to the remote. <span class="mdx-badge"><span class="mdx-badge__icon">:material-tag:{ title="Released in version" }</span><span class="mdx-badge__text">[v0.15.0](/changelog.md#v0.15.0)</span>
 * `-u`, `--update-only`: Only update existing change requests, do not create new ones
+* `-l`, `--label=LABEL,...`: Add labels to the change request. Pass multiple times or separate with commas.
 * `--no-web`: Alias for --web=false.
 * `--branch=NAME`: Branch to start at
 
-**Configuration**: [spice.submit.draft](/cli/config.md#spicesubmitdraft), [spice.submit.listTemplatesTimeout](/cli/config.md#spicesubmitlisttemplatestimeout), [spice.submit.navigationComment](/cli/config.md#spicesubmitnavigationcomment), [spice.submit.navigationCommentSync](/cli/config.md#spicesubmitnavigationcommentsync), [spice.submit.publish](/cli/config.md#spicesubmitpublish), [spice.submit.web](/cli/config.md#spicesubmitweb)
+**Configuration**: [spice.submit.draft](/cli/config.md#spicesubmitdraft), [spice.submit.label](/cli/config.md#spicesubmitlabel), [spice.submit.listTemplatesTimeout](/cli/config.md#spicesubmitlisttemplatestimeout), [spice.submit.navigationComment](/cli/config.md#spicesubmitnavigationcomment), [spice.submit.navigationCommentSync](/cli/config.md#spicesubmitnavigationcommentsync), [spice.submit.publish](/cli/config.md#spicesubmitpublish), [spice.submit.web](/cli/config.md#spicesubmitweb)
 
 ### gs downstack edit
 
@@ -896,12 +899,13 @@ or --nav-comment=multiple to post those comments only if there are multiple CRs
 * `--force`: Force push, bypassing safety checks
 * `--no-verify`: Bypass pre-push hooks when pushing to the remote. <span class="mdx-badge"><span class="mdx-badge__icon">:material-tag:{ title="Released in version" }</span><span class="mdx-badge__text">[v0.15.0](/changelog.md#v0.15.0)</span>
 * `-u`, `--update-only`: Only update existing change requests, do not create new ones
+* `-l`, `--label=LABEL,...`: Add labels to the change request. Pass multiple times or separate with commas.
 * `--no-web`: Alias for --web=false.
 * `--title=TITLE`: Title of the change request
 * `--body=BODY`: Body of the change request
 * `--branch=NAME`: Branch to submit
 
-**Configuration**: [spice.submit.draft](/cli/config.md#spicesubmitdraft), [spice.submit.listTemplatesTimeout](/cli/config.md#spicesubmitlisttemplatestimeout), [spice.submit.navigationComment](/cli/config.md#spicesubmitnavigationcomment), [spice.submit.navigationCommentSync](/cli/config.md#spicesubmitnavigationcommentsync), [spice.submit.publish](/cli/config.md#spicesubmitpublish), [spice.submit.web](/cli/config.md#spicesubmitweb)
+**Configuration**: [spice.submit.draft](/cli/config.md#spicesubmitdraft), [spice.submit.label](/cli/config.md#spicesubmitlabel), [spice.submit.listTemplatesTimeout](/cli/config.md#spicesubmitlisttemplatestimeout), [spice.submit.navigationComment](/cli/config.md#spicesubmitnavigationcomment), [spice.submit.navigationCommentSync](/cli/config.md#spicesubmitnavigationcommentsync), [spice.submit.publish](/cli/config.md#spicesubmitpublish), [spice.submit.web](/cli/config.md#spicesubmitweb)
 
 ## Commit
 

doc/mise.lock

@@ -280,6 +280,18 @@ This option affects both interactive and non-interactive modes:
 - `true`: create CRs as drafts by default
 - `false` (default): create CRs as ready for review by default
 
+### spice.submit.label
+
+<!-- gs:version unreleased -->
+
+Add the configured labels to all submitted and updated change requests
+when using $$gs branch submit$$ and friends.
+
+The value must be a comma-separated list of labels.
+
+Labels specified with the `-l`/`--label` flags
+will be combined with the configured labels.
+
 ### spice.submit.listTemplatesTimeout
 
 <!-- gs:version v0.8.0 -->

doc/src/cli/config.md

@@ -298,6 +298,9 @@ type SubmitChangeRequest struct {
 
 	// Draft specifies whether the change should be marked as a draft.
 	Draft bool
+
+	// Labels are optional labels to apply to the change.
+	Labels []string
 }
 
 // SubmitChangeResult is the result of creating a new change in a repository.
@@ -317,6 +320,8 @@ type EditChangeOptions struct {
 	// Draft specifies whether the change should be marked as a draft.
 	// If unset, the draft status is not changed.
 	Draft *bool
+
+	Labels []string
 }
 
 // FindChangeItem is a single result from searching for changes in the

internal/forge/forge.go

@@ -11,7 +11,7 @@ import (
 
 // EditChange edits an existing change in a repository.
 func (r *Repository) EditChange(ctx context.Context, fid forge.ChangeID, opts forge.EditChangeOptions) error {
-	if cmputil.Zero(opts) {
+	if cmputil.Zero(opts.Base) && cmputil.Zero(opts.Draft) && len(opts.Labels) == 0 {
 		return nil // nothing to do
 	}
 	pr := mustPR(fid)
@@ -85,5 +85,10 @@ func (r *Repository) EditChange(ctx context.Context, fid forge.ChangeID, opts fo
 		r.log.Debug(logMsg, "pr", pr.Number)
 	}
 
+	err = r.addLabelsToPullRequest(ctx, opts.Labels, graphQLID)
+	if err != nil {
+		return fmt.Errorf("add labels to PR: %w", err)
+	}
+
 	return nil
 }

internal/forge/github/edit.go

@@ -393,6 +393,163 @@ func TestIntegration_Repository_SubmitEditChange(t *testing.T) {
 	})
 }
 
+func TestIntegration_Repository_SubmitEditChange_labels(t *testing.T) {
+	label1 := fixturetest.New(_fixtures, "label1", func() string { return randomString(8) }).Get(t)
+	label2 := fixturetest.New(_fixtures, "label2", func() string { return randomString(8) }).Get(t)
+	label3 := fixturetest.New(_fixtures, "label3", func() string { return randomString(8) }).Get(t)
+
+	branchFixture := fixturetest.New(_fixtures, "branch", func() string {
+		return randomString(8)
+	})
+
+	branchName := branchFixture.Get(t)
+	t.Logf("Creating branch: %s", branchName)
+
+	var (
+		gitRepo *git.Repository // only when _update is true
+		gitWork *git.Worktree
+	)
+	if *_update {
+		t.Setenv("GIT_AUTHOR_EMAIL", "[email protected]")
+		t.Setenv("GIT_AUTHOR_NAME", "gs-test[bot]")
+		t.Setenv("GIT_COMMITTER_EMAIL", "[email protected]")
+		t.Setenv("GIT_COMMITTER_NAME", "gs-test[bot]")
+
+		output := ioutil.TestLogWriter(t, "[git] ")
+
+		t.Logf("Cloning test-repo...")
+		repoDir := t.TempDir()
+		cmd := exec.Command("git", "clone", "https://github.com/abhinav/test-repo", repoDir)
+		cmd.Stdout = output
+		cmd.Stdout = output
+		require.NoError(t, cmd.Run(), "failed to clone test-repo")
+
+		ctx := t.Context()
+
+		var err error
+		gitWork, err = git.OpenWorktree(ctx, repoDir, git.OpenOptions{
+			Log: silogtest.New(t),
+		})
+		require.NoError(t, err, "failed to open git repo")
+		gitRepo = gitWork.Repository()
+
+		require.NoError(t, gitRepo.CreateBranch(ctx, git.CreateBranchRequest{
+			Name: branchName,
+		}), "could not create branch: %s", branchName)
+		require.NoError(t, gitWork.Checkout(ctx, branchName),
+			"could not checkout branch: %s", branchName)
+		require.NoError(t, os.WriteFile(
+			filepath.Join(repoDir, branchName+".txt"),
+			[]byte(randomString(32)),
+			0o644,
+		), "could not write file to branch")
+
+		cmd = exec.Command("git", "add", ".")
+		cmd.Dir = repoDir
+		cmd.Stdout = output
+		cmd.Stderr = output
+		require.NoError(t, cmd.Run(), "git add failed")
+		require.NoError(t, gitWork.Commit(ctx, git.CommitRequest{
+			Message: "commit from test",
+		}), "could not commit changes")
+
+		t.Logf("Pushing to origin")
+		require.NoError(t,
+			gitWork.Push(ctx, git.PushOptions{
+				Remote:  "origin",
+				Refspec: git.Refspec(branchName),
+			}), "error pushing branch")
+
+		t.Cleanup(func() {
+			t.Logf("Deleting remote branch: %s", branchName)
+			assert.NoError(t,
+				gitWork.Push(context.WithoutCancel(ctx), git.PushOptions{
+					Remote:  "origin",
+					Refspec: git.Refspec(":" + branchName),
+				}), "error deleting branch")
+		})
+	}
+
+	rec := newRecorder(t, t.Name())
+	ghc := newGitHubClient(rec.GetDefaultClient())
+	repo, err := github.NewRepository(
+		t.Context(), new(github.Forge), "abhinav", "test-repo", silogtest.New(t), ghc, _testRepoID,
+	)
+	require.NoError(t, err)
+
+	t.Cleanup(func() {
+		labels := []string{label1, label2, label3}
+		ctx := context.WithoutCancel(t.Context())
+		for _, label := range labels {
+			assert.NoError(t,
+				repo.DeleteLabel(ctx, label), "could not delete label: %s", label)
+		}
+	})
+
+	change, err := repo.SubmitChange(t.Context(), forge.SubmitChangeRequest{
+		Subject: branchName,
+		Body:    "Test PR",
+		Base:    "main",
+		Head:    branchName,
+		Labels:  []string{label1},
+	})
+	require.NoError(t, err, "error creating PR")
+	changeID := change.ID
+
+	t.Run("AddNewLabel", func(t *testing.T) {
+		require.NoError(t,
+			repo.EditChange(t.Context(), changeID, forge.EditChangeOptions{
+				Labels: []string{label2},
+			}), "could not add labels to PR")
+	})
+
+	t.Run("AddExistingLabel", func(t *testing.T) {
+		require.NoError(t,
+			repo.EditChange(t.Context(), changeID, forge.EditChangeOptions{
+				Labels: []string{label2, label3},
+			}), "could not add existing label to PR")
+	})
+}
+
+func TestIntegration_Repository_LabelCreateDelete(t *testing.T) {
+	label := fixturetest.New(_fixtures, "label1", func() string { return randomString(8) }).Get(t)
+
+	rec := newRecorder(t, t.Name())
+	ghc := newGitHubClient(rec.GetDefaultClient())
+	repo, err := github.NewRepository(
+		t.Context(), new(github.Forge), "abhinav", "test-repo", silogtest.New(t), ghc, _testRepoID,
+	)
+	require.NoError(t, err)
+
+	t.Run("DoesNotExist", func(t *testing.T) {
+		_, err := repo.LabelID(t.Context(), label)
+		require.Error(t, err, "expected error for non-existent label")
+		assert.ErrorIs(t, err, github.ErrLabelNotFound)
+	})
+
+	id, err := repo.CreateLabel(t.Context(), label)
+	require.NoError(t, err, "could not create label")
+	t.Cleanup(func() {
+		t.Logf("Deleting label: %s", label)
+		ctx := context.WithoutCancel(t.Context())
+		assert.NoError(t,
+			repo.DeleteLabel(ctx, label), "could not delete label")
+	})
+
+	t.Run("LabelID", func(t *testing.T) {
+		gotID, err := repo.LabelID(t.Context(), label)
+		require.NoError(t, err, "could not get label ID")
+		assert.Equal(t, id, gotID, "label ID does not match")
+	})
+
+	t.Run("createIsIdempotent", func(t *testing.T) {
+		newID, err := repo.CreateLabel(t.Context(), label)
+		require.NoError(t, err, "could not create label again")
+
+		assert.Equal(t, id, newID, "label ID should be the same on idempotent create")
+	})
+}
+
 func TestIntegration_Repository_SubmitChange_baseBranchDoesNotExist(t *testing.T) {
 	branchFixture := fixturetest.New(_fixtures, "branch", func() string {
 		return randomString(8)