[ArmandPhilippot]

The "umbrella PR assistant" idea is bigger than I thought and folding everything in a single PR is hard to review. So, I have this PR for the workflow itself, in addition to #14806 that adds a minimal GitHub client. The diff is still big but there are a lot of tests.

Description (required)

Adds a release assistant workflow to handle the umbrella PRs of Astro releases.

Every Astro release is handled by hand today: we find the docs PRs for the release, gather them on a temporary branch, open an umbrella PR, and merge it when the [ci] release PR is merged in withastro/astro. The preparation takes some time and it's not a great experience if someone wants to do a quick release.

With this workflow, most of the process is automated. The release assistant:

• Checks that the PR can join an umbrella. If not, it removes accepted and comments with every reason.
• Squash-merges the PR into the umbrella branch of its base branch (e.g. umbrella/main for main), and opens the umbrella PR when there is none.
• Refreshes every open umbrella PR (title, labels, description, etc.), including a review that blocks its merge until a maintainer goes through a checklist (e.g. a Lunaria directive).

A maintainer still decides when a docs PR is ready, by adding the accepted label. Merging the umbrella PR into main (or the prerelease branch) is still manual.

This relies on new labels: patch-release, major-release, and accepted (already created). There's no real distinction between patch-release and minor-release. On contributors PRs, it's mostly for maintainers to distinguish small PRs from features. On the umbrella PR, it shows if there are docs for a patch release.

Note: pull_request_target will be blocked on public repositories from December 2, 2026, unless an Actions event policy allows it. Five workflows already rely on it, so that policy is needed anyway.

How it works

The workflow runs when accepted is added to a PR, or by hand to only refresh the umbrellas. A new check (Release assistant / join-umbrella) is added to a PR when a new label is applied, and is skipped when this is not accepted.

In live mode, each run:

1. Reads the open [ci] release PRs of withastro/astro: the stable one, and the prerelease one while next is in pre mode.
2. Handles every open PR with accepted, oldest first, after reading it again:
   • Where it goes: patch-release or minor-release on main go to umbrella/main, major-release on a prerelease branch goes to umbrella/<branch>. A PR already based on an umbrella branch stays there.
   • Whether it can be merged: not a draft, approved by a maintainer (write access), no changes requested, no conflicts, and its checks are done and passing.
   • Whether the release allows it: when the next stable release is an Astro major, stable PRs go to the prerelease branch instead. When the release of an umbrella is already out, new PRs from main wait for the next umbrella (or should be retargeted manually).
   • Refused: accepted is removed, with a comment listing every reason.
   • Accepted: the PR's base changes to the umbrella branch (created from the base if missing), then it's squash-merged. The umbrella PR is opened if there is none, and the PR gets a comment linking it. If GitHub refuses the merge, the base changes back and the PR is refused with GitHub's message.
3. Refreshes every open umbrella PR:
   • its title ([ci] release astro@x.y.z docs) and labels (merge-on-release and the release type), from the release PR;
   • its description: the release PR, and the included PRs, read from the commits;
   • a review from github-actions[bot] requesting changes, with the merge checklist. Dismissing it allows the merge. It comes back when new PRs join after a dismissal.

Once the umbrella PR is merged, its branch is deleted and the next accepted PR starts a new umbrella.

This requires two tokens:

• FREDKBOT_GITHUB_TOKEN merges the docs PRs, opens and edits the umbrella PRs, and comments.
• GITHUB_TOKEN reads withastro/astro and posts the review: GitHub doesn't allow the author of a PR to review it, so the bot can't block its own umbrellas.

At the moment, this uses the dry run mode: on each accepted label, the workflow comments on the PR with what it would do, and removes accepted. It changes nothing else, and doesn't refresh umbrellas.

Switching to live mode requires updating .github/workflows/release-assistant.yml (--mode dry-run to --mode live). This happens in a follow-up PR that also updates the release process in CONTRIBUTING.md.

The script has unit tests using a fake repository. They can be run with pnpm test:scripts (introduced by #14806) for debugging. Outside GitHub Actions, the script is always read-only: it logs the writes instead of sending them, so it can be run locally to preview a PR.

I've done a first test run on my fork; expand to see some examples.

The fork: https://github.com/ArmandPhilippot/astro-docs

These examples predate the rewording of the messages and the rename (release-queue/main is now umbrella/main):

• Dry run with no associated labels: [dry run] accepted without an associated release label ArmandPhilippot/astro-docs#3
• Dry run with too many labels: [dry run] accepted with both patch and minor release labels ArmandPhilippot/astro-docs#5
• An example of umbrella PR targeting main: [ci] release astro@7.4.5 docs ArmandPhilippot/astro-docs#10
• Merging in an existing umbrella PR in live mode: [live] 3 accepted PRs at the same time: first one ArmandPhilippot/astro-docs#12

TODO: Second test run on my fork, after the fixes from the first one.

References

• Requires Add a minimal GitHub client for workflow scripts #14806
• Supersedes Umbrella PRs assistant #14763
• Related to Discord automation ideas thread

[github-actions]

Preview deployment

✅ Deployment complete!

• Latest commit: 03968e1
• Preview: https://armand-umbrella-assistant.previews.docs.astro.build
• Workflow run: View logs