Add the publish command to open the backport pull requests

Pushes the branches apply built and opens one pull request per affected
branch, so a fix that lands on seven branches is one command rather than
seven trips through the GitHub UI. apply --open-pr offers it as soon as the
cherry-picks are done, so a local session stays analyze then apply

A branch is publishable once its cherry-pick is finished, which is read from
git rather than from anything apply recorded. Resolving a conflict by hand is
therefore enough to make the next publish pick that branch up, with no need
to run apply again

Branches are pushed to a fork and the pull requests are opened against
aws/aws-lc. Pushing to aws/aws-lc is refused outright, so a stray --remote
cannot put half-reviewed work on the real repository. A branch that already
has an open pull request is left alone, so re-running is safe

Everything that talks to GitHub lives in util/github.py. The previous version
of this tool grew one PR opener in publish and a second in resolve, and they
drifted apart

Nothing is ever a draft and nothing is auto-merged

Author: tianyiy-tim

util/backport/README.md

@@ -17,9 +17,10 @@ passes:
    review, but a no-answer always leaves the branch flagged, so it can never hide a
    needed backport.
 
-`apply` then cherry-picks the fix onto one local branch per affected branch.
+`apply` then cherry-picks the fix onto one local branch per affected branch, and
+`publish` turns those into one pull request each.
 
-Nothing is pushed and no pull request is opened. The branches are yours to review.
+Nothing is auto-merged, and nothing is ever a draft. Every pull request needs review.
 
 ## Prerequisites
 
@@ -31,6 +32,8 @@ Nothing is pushed and no pull request is opened. The branches are yours to revie
 - **anthropic + boto3**: required, not optional (`pip3 install --user anthropic boto3`).
   The AI pass is part of how a verdict is reached, so the tool imports them at startup
   even when `BACKPORT_DISABLE_AI` is set
+- **gh**: the GitHub CLI, for `publish` only. Logged in with `gh auth login`, or
+  `GH_TOKEN` set, which is how CI supplies it
 
 ### AWS Permissions
 
@@ -176,6 +179,64 @@ normal on the older branches, where the surrounding code has moved on.
 leaves the branches you already have alone. The command exits non-zero if any branch
 conflicted, so a script can tell whether anything needs a human.
 
+### Open the pull requests
+
+```bash
+util/backport/backport publish
+```
+
+Pushes each finished backport branch to your fork and opens one pull request per
+branch into the matching release branch. One command, however many branches the fix
+touched.
+
+Most of the time you never type it: `apply --open-pr` offers to run it as soon as the
+cherry-picks are done, so a normal session is `analyze` then `apply`.
+
+```bash
+util/backport/backport apply --open-pr
+```
+
+| Flag | Purpose |
+| --- | --- |
+| `--branch` | just this release branch |
+| `--pr` | source pull request number, linked in each body and given a summary comment |
+| `--remote` | fork remote the branches are pushed to, `origin` by default |
+| `--dry-run` | print what would be pushed and opened, touch nothing |
+| `--yes` | skip the confirm, for scripts and CI |
+
+Branches go to your fork; the pull requests are opened against `aws/aws-lc`. Pushing
+to `aws/aws-lc` is refused outright, so a stray `--remote` cannot put half-reviewed
+work on the real repository.
+
+**Example Output:**
+
+```
+Fix ac3aee3104
+Opening pull requests into aws/aws-lc for: fips-2025-09-12-lts, fips-2024-09-27
+Branches are pushed to 'origin'
+Go ahead? [Y/N] y
+  fips-2025-09-12-lts: opened: https://github.com/aws/aws-lc/pull/3401
+  fips-2024-09-27: unfinished: cherry-pick still open in .backport-worktrees/...
+
+1 pull request(s) opened, 1 still need attention
+  fips-2024-09-27
+  Finish the cherry-pick in its worktree, then run publish again.
+```
+
+**Results:**
+
+| Result | Meaning |
+| --- | --- |
+| `opened` | pushed and a pull request created |
+| `already open` | a pull request for that branch exists, so nothing was done again |
+| `unfinished` | its cherry-pick is still stopped in the worktree, resolve it first |
+| `missing` | no such backport branch, run `apply` first |
+| `failed` | the push or the pull request failed, with the reason |
+
+Nothing is ever a draft and nothing is auto-merged. Re-running is safe: a branch that
+already has a pull request is left alone, and finishing a conflict by hand is enough
+to let the next run pick it up, with no need to run `apply` again.
+
 ## Configuration
 
 ### Model settings
@@ -250,7 +311,8 @@ util/backport/
 │   ├── main.py                   # argument parsing
 │   ├── commands/
 │   │   ├── analyze.py            # the analyze command
-│   │   └── apply.py              # the apply command
+│   │   ├── apply.py              # the apply command
+│   │   └── publish.py            # the publish command
 │   ├── engine/
 │   │   ├── inspect_fix.py        # which lines the fix deletes, who wrote them
 │   │   ├── discover_branches.py  # which release branches to check
@@ -260,6 +322,7 @@ util/backport/
 │   └── util/
 │       ├── config.py             # verdicts, settings, the saved run
 │       ├── git.py                # everything that runs a git command
+│       ├── github.py             # everything that talks to GitHub, through gh
 │       └── render.py             # the output table and prompts
 ├── testing/
 │   ├── test_engine.py            # unit tests, no repo or credentials
@@ -405,6 +468,27 @@ The same error appears if the run names a fix this checkout no longer has, which
 happens when a range was analyzed and git has since collected the squashed commit.
 Re-running `analyze` fixes both.
 
+### No pull request can be opened
+
+`publish` needs the GitHub CLI, installed and logged in:
+
+```bash
+gh auth login
+gh auth status
+```
+
+In CI set `GH_TOKEN` instead, and give the job `contents: write` and
+`pull-requests: write`.
+
+### Refused to push to aws/aws-lc
+
+Backport branches belong on a fork; only the pull requests go to `aws/aws-lc`. Point
+`--remote` at your fork:
+
+```bash
+util/backport/backport publish --remote origin
+```
+
 ### Wrong or empty results from a subdirectory
 
 Should not happen. The tool pins itself to the checkout it lives in rather than

util/backport/src/commands/analyze.py

@@ -53,5 +53,5 @@ def cmd_analyze(args) -> int:
     verdicts, decided_by = refine_with_ai(fix_sha, src_files, bug_commits, verdicts)
 
     print_summary(fix_sha, files, bug_commits, verdicts, decided_by)
-    save_run(fix_sha, base, branches, verdicts)
+    save_run(fix_sha, base, branches, verdicts, decided_by)
     return 0

util/backport/src/commands/apply.py

@@ -156,5 +156,14 @@ def cmd_apply(args) -> int:
             "Resolve each conflict in the worktree named above, then "
             "'git cherry-pick --continue' there."
         )
-    print("Nothing was pushed. Review each branch before you open a pull request.")
+
+    # Imported here, not at the top: publish imports this module for the run file and
+    # the branch naming, so importing it up there would be a cycle
+    from commands.publish import offer_publish
+
+    ready = [b for b, (o, _) in results.items() if o in (PICKED, EMPTY)]
+    if args.open_pr:
+        offer_publish(run, ready, args.remote)
+    else:
+        print("Nothing was pushed. Review each branch before you open a pull request.")
     return 1 if conflicted else 0

util/backport/src/commands/publish.py

@@ -0,0 +1,218 @@
+# Copyright Amazon.com, Inc. or its affiliates. All Rights Reserved.
+# SPDX-License-Identifier: Apache-2.0 OR ISC
+
+"""
+The publish command: pushes the branches apply built and opens one pull request each
+Run by apply after a local cherry-pick, or on its own in CI
+"""
+
+from commands.apply import backport_branch, load_run, pick_targets
+from util.config import BackportError
+from util.git import (
+    WORKTREE_ROOT,
+    cherry_pick_in_progress,
+    commit_subject,
+    commits_ahead,
+    branch_exists,
+    remove_worktree,
+)
+from util.github import (
+    base_repo,
+    comment_on_pr,
+    create_pr,
+    existing_pr,
+    head_spec,
+    pr_title_and_body,
+    push_branch,
+    require_gh,
+    require_push_remote,
+    summary_lines,
+)
+from util.render import ask_yn
+
+from typing import Dict, List, Optional, Tuple
+
+# What happened to one branch
+OPENED = "opened"
+ALREADY_OPEN = "already open"
+UNFINISHED = "unfinished"
+MISSING = "missing"
+FAILED = "failed"
+DRY_RUN = "dry run"
+
+
+def branch_state(release: str, local: str) -> str:
+    """
+    Whether one backport branch is ready to become a pull request
+    Returns MISSING when apply never made it, UNFINISHED while a cherry-pick is still
+    stopped in its worktree, and OPENED when it holds at least one commit. Resolving a
+    conflict by hand is enough to turn UNFINISHED into ready, with no need to re-run
+    apply
+    """
+    if not branch_exists(local):
+        return MISSING
+    worktree = WORKTREE_ROOT / local
+    if worktree.exists() and cherry_pick_in_progress(worktree):
+        return UNFINISHED
+    if commits_ahead(f"origin/{release}", local) < 1:
+        return MISSING
+    return OPENED
+
+
+def publish_one(
+    release: str,
+    fix: str,
+    subject: str,
+    basis: str,
+    source_pr: Optional[str],
+    remote: str,
+    push_slug: str,
+    repo: str,
+    dry_run: bool,
+) -> Tuple[str, str]:
+    """
+    Pushes one finished backport branch and opens its pull request
+    Returns (outcome, detail) where detail is a URL, a reason, or an error
+    """
+    local = backport_branch(fix, release)
+    state = branch_state(release, local)
+    if state == MISSING:
+        return MISSING, f"no branch {local}, run apply first"
+    if state == UNFINISHED:
+        return UNFINISHED, f"cherry-pick still open in {WORKTREE_ROOT / local}"
+
+    head = head_spec(push_slug, repo, local)
+    open_already = existing_pr(repo, head)
+    if open_already:
+        return ALREADY_OPEN, open_already
+    if dry_run:
+        return DRY_RUN, f"would push {local} and open a PR into {release}"
+
+    failure = push_branch(remote, local)
+    if failure:
+        return FAILED, f"push failed: {failure}"
+
+    title, body = pr_title_and_body(release, fix, subject, basis, source_pr)
+    url = create_pr(repo, release, head, title, body)
+    if url.startswith("error:"):
+        return FAILED, url
+    # The worktree only survives a resolved conflict, and it is finished with now
+    remove_worktree(WORKTREE_ROOT / local)
+    return OPENED, url
+
+
+def run_publish(
+    run: Dict,
+    branches: List[str],
+    remote: str,
+    push_slug: str,
+    source_pr: Optional[str],
+    dry_run: bool,
+) -> List[Tuple[str, str, str]]:
+    """
+    Publishes every named branch
+    Returns (branch, outcome, detail) per branch, in the order given. The caller has
+    already checked gh and the remote, so nothing here can fail on setup
+    """
+    repo = base_repo("upstream")
+    fix = run["fix"]
+    subject = commit_subject(fix)
+    decided = run.get("decided_by", {})
+
+    results = []
+    for release in branches:
+        outcome, detail = publish_one(
+            release,
+            fix,
+            subject,
+            decided.get(release, ""),
+            source_pr,
+            remote,
+            push_slug,
+            repo,
+            dry_run,
+        )
+        results.append((release, outcome, detail))
+        print(f"  {release}: {outcome}: {detail}")
+    return results
+
+
+def report(
+    run: Dict, results: List[Tuple[str, str, str]], source_pr: Optional[str], repo: str
+) -> None:
+    """Prints the tally and, when a source PR was named, comments the table on it"""
+    opened = sum(1 for _, o, _ in results if o == OPENED)
+    stuck = [b for b, o, _ in results if o in (UNFINISHED, MISSING, FAILED)]
+    print()
+    print(f"{opened} pull request(s) opened, {len(stuck)} still need attention")
+    if stuck:
+        print(f"  {', '.join(stuck)}")
+        # The advice has to match the cause, or it sends people to the wrong place
+        kinds = {o for _, o, _ in results}
+        if MISSING in kinds:
+            print("  Missing branches: run 'backport apply' first.")
+        if UNFINISHED in kinds:
+            print(
+                "  Unfinished branches: resolve the conflict in the worktree, then\n"
+                "  'git cherry-pick --continue' there and run publish again."
+            )
+        if FAILED in kinds:
+            print("  Failed branches: see the reason above.")
+    if source_pr:
+        table = summary_lines(run["fix"], commit_subject(run["fix"]), results)
+        failure = comment_on_pr(repo, source_pr, table)
+        if failure:
+            print(f"could not comment on #{source_pr}: {failure}")
+
+
+def cmd_publish(args) -> int:
+    """
+    Opens a backport pull request for every affected branch
+    Returns 0 when every branch was published or already had a pull request, 1 when
+    any branch still needs attention
+    """
+    run = load_run()
+    branches = pick_targets(run["verdicts"], args.branch)
+    if not branches:
+        print("No affected branches in the last analyze run, nothing to publish.")
+        return 0
+
+    # Checked before anything is printed, so nobody confirms a run that cannot work
+    require_gh()
+    push_slug = require_push_remote(args.remote)
+
+    repo = base_repo("upstream")
+    print(f"Fix {run['fix'][:10]}")
+    print(f"Opening pull requests into {repo} for: {', '.join(branches)}")
+    print(f"Branches are pushed to '{args.remote}'")
+    if not args.yes and not args.dry_run and not ask_yn("Go ahead?"):
+        print("Aborted. Nothing was pushed.")
+        return 0
+
+    results = run_publish(run, branches, args.remote, push_slug, args.pr, args.dry_run)
+    report(run, results, args.pr, repo)
+    return 1 if any(o in (UNFINISHED, MISSING, FAILED) for _, o, _ in results) else 0
+
+
+def offer_publish(run: Dict, branches: List[str], remote: str) -> None:
+    """
+    Asks whether to open the pull requests, straight after apply cherry-picked
+    Only the branches that applied cleanly are offered, so a conflict is never
+    published half-done
+    """
+    if not branches:
+        return
+    print()
+    # Checked before the question, so a missing gh is not discovered after a yes
+    try:
+        require_gh()
+        push_slug = require_push_remote(remote)
+    except BackportError as exc:
+        print(f"Cannot open pull requests: {exc}")
+        print("The branches are here. Fix that and run 'backport publish'.")
+        return
+    if not ask_yn(f"Open pull requests for {len(branches)} branch(es)?"):
+        print("Left as local branches. Run 'backport publish' when you are ready.")
+        return
+    results = run_publish(run, branches, remote, push_slug, None, False)
+    report(run, results, None, base_repo("upstream"))