From 09f0335c75fa2d4ffe506706bb634b6e7b294123 Mon Sep 17 00:00:00 2001 From: Sam Gutentag <1404219+samgutentag@users.noreply.github.com> Date: Mon, 18 May 2026 09:38:12 -0700 Subject: [PATCH 1/2] docs(merge-queue): rewrite GitHub migration page as runbook + scope dual mode to settings verification Reframes migrating-from-github-merge-queue around Robert Eperjesi's guidance (slack thread C09L0GB2771/1778860519): dual mode is a brief settings-verification step before a full switch to Trunk, not a long-term coexistence mode. Restructures the page into a 4-step migration runbook (enable Trunk alongside, verify in dual mode, disable GH queue, announce), keeps the "Trunk handles external merges gracefully" claims (verified against trunk/services/merge/src/controller/graph_controller.ts), explains preemption as the reason a hard cutover is recommended, and adds dev-facing announcement copy admins can paste into Slack or email. Co-Authored-By: Claude Opus 4.7 (1M context) --- .../migrating-from-github-merge-queue.md | 88 ++++++++++--------- 1 file changed, 48 insertions(+), 40 deletions(-) diff --git a/merge-queue/migrating-from-github-merge-queue.md b/merge-queue/migrating-from-github-merge-queue.md index 9953644c..2406aef4 100644 --- a/merge-queue/migrating-from-github-merge-queue.md +++ b/merge-queue/migrating-from-github-merge-queue.md @@ -1,86 +1,94 @@ --- description: >- - Switch from GitHub's native merge queue to Trunk Merge Queue with minimal - disruption to your workflow. + Move a repository from GitHub Merge Queue to Trunk Merge Queue with a brief + dual-mode validation followed by a full switch. --- # Migrate from GitHub Merge Queue -For teams switching from [GitHub Merge Queues](https://docs.github.com/en/pull-requests/collaborating-with-pull-requests/incorporating-changes-from-a-pull-request/merging-a-pull-request-with-a-merge-queue) to Trunk Merge Queue, the process is straight forward. +For teams switching from [GitHub Merge Queues](https://docs.github.com/en/pull-requests/collaborating-with-pull-requests/incorporating-changes-from-a-pull-request/merging-a-pull-request-with-a-merge-queue) to Trunk Merge Queue, the recommended path is a short dual-mode validation followed by a full switch to Trunk. {% hint style="success" %} -Looking for a more detailed comparison between Trunk and GitHub's Merge Queues? [Learn more](https://trunk.io/trunk-vs-github-merge-queue) +Looking for a more detailed comparison between Trunk and GitHub's Merge Queues? [Learn more](https://trunk.io/trunk-vs-github-merge-queue) {% endhint %} -*** - -### Turn off GitHub Merge Queue - -To start, you will need to disable the existing merge queue for the target repository. This can be done by navigating to the repository and opening **Settings > Branches >** branch rule **>** toggle **off Require merge queue.** Be sure to click **Save changes** to confirm the settings. - -{% hint style="info" %} -Note that only users with admin permissions can manage merge queues for pull requests targeting selected branches of a repository. More information on [manage merge queues](https://docs.github.com/en/repositories/configuring-branches-and-merges-in-your-repository/managing-protected-branches/managing-a-branch-protection-rule#creating-a-branch-protection-rule) can be found in the GitHub documentation. +{% hint style="warning" %} +Running both queues for an extended period is not recommended. Use dual mode only to verify Trunk's settings against a few real PRs, then disable GitHub Merge Queue and run on Trunk only. See [Why complete the migration](#why-complete-the-migration) for the reasoning. {% endhint %} *** -### Enable Trunk Merge Queue +### Migration steps -Follow the [Getting Started](getting-started/) to setup your repo with Trunk Merge Queue and configure the [settings](administration/advanced-settings.md) for your repository. +The recommended sequence for admins moving a repository from GitHub Merge Queue to Trunk Merge Queue. -*** +#### 1. Enable Trunk Merge Queue alongside GitHub -### Running both merge queues simultaneously +Follow [Getting Started](getting-started/) to install Trunk and configure your repository. Leave GitHub Merge Queue enabled for now. -Many teams prefer a gradual migration approach where Trunk Merge Queue runs alongside GitHub Merge Queue before fully switching over. This is a common path for teams migrating from GitHub's merge queue to Trunk and works well for several reasons: +Before opting your team in, turn off Trunk's automatic PR comments so developers aren't confused by comments from a queue they don't yet know about. -#### No Disruption to Existing Workflows +This setting is under **Merge Queue** tab **>** repository **> Settings >** toggle **off GitHub Comments.** -Enabling Trunk Merge Queue does not stop or prevent your current merging flow. GitHub's merge queue will continue to function normally and merge PRs as it always has. Your team can continue using their familiar workflow while you evaluate Trunk Merge Queue. +#### 2. Verify settings in dual mode -#### Disable Comments During Evaluation +With both queues enabled, run a few real PRs through Trunk to confirm: -To prevent confusion for developers who aren't yet aware of the migration, you can disable the comments Trunk leaves on PRs. This way, developers won't see unfamiliar comments about Trunk Merge Queue while you're still evaluating. +* Branch protection rules trigger the required checks you expect. +* Test orchestration policies match your repo's CI. +* [Advanced settings](administration/advanced-settings.md) such as timeouts, batching, and optimistic merging behave correctly for your repo. -This setting is found under **Merge Queue** tab **>** repository **> Settings >** toggle **off GitHub Comments.** +Dual mode exists for this validation step only. The goal is to confirm Trunk's configuration before committing to the switch, not to run both queues indefinitely. See [What happens during dual mode](#what-happens-during-dual-mode) for behavior details. -#### Trunk Handles External Merges Gracefully +#### 3. Turn off GitHub Merge Queue -Trunk Merge Queue understands when a PR is merged outside of its queue (for example, through GitHub's merge queue): +Once you've validated Trunk's configuration, disable GitHub Merge Queue. In the GitHub repository, navigate to **Settings > Branches >** branch rule **>** toggle **off Require merge queue.** Click **Save changes** to confirm. -- **If the PR is also in Trunk's queue**: Trunk will automatically mark it as merged on its side. -- **If the PR is not in Trunk's queue**: Trunk will restart any PRs currently in its queue so they can test on top of the new commit. +{% hint style="info" %} +Only users with GitHub admin permissions can manage merge queues for pull requests targeting selected branches of a repository. See GitHub's [managing merge queues](https://docs.github.com/en/repositories/configuring-branches-and-merges-in-your-repository/managing-protected-branches/managing-a-branch-protection-rule#creating-a-branch-protection-rule) documentation for details. +{% endhint %} -This ensures that Trunk always tests against the latest state of your target branch, regardless of how PRs are merged. +#### 4. Re-enable Trunk's GitHub comments and announce -*** +Turn Trunk's automatic PR comments back on under the **Merge Queue** tab **>** repository **> Settings >** toggle **on GitHub Comments.** -### Pre-migration +Share the change with your team. See [Dev-facing announcement copy](#dev-facing-announcement-copy) for a template you can paste into Slack or email, and [Using the Queue](using-the-queue/) for the full developer workflow. -Before migrating fully, it may be useful to evaluate the workflows quietly and confirm settings before converting your repository to an entirely new workflow. +*** -Here are some useful steps to get you familiar with the Trunk Merge Queue workflow without disrupting engineers. +### What happens during dual mode -#### Enable Trunk Merge for testing but with the automatic comments disabled +While both queues are enabled, Trunk Merge Queue detects when a PR is merged outside of its queue (for example, by GitHub's merge queue or a direct push to the target branch): -While evaluating and testing Trunk Merge Queue for your team, we suggest disabling automatic comments on PRs. This can be done by toggling off GitHub Comments in the Trunk web app. +* **If the PR is also in Trunk's queue**: Trunk automatically marks it as merged on its side. +* **If the PR is not in Trunk's queue**: Trunk restarts any PRs currently in its queue so they can test on top of the new commit. -This setting is found under **Merge Queue** tab **>** repository **> Settings >** toggle **off GitHub Comments.** +This ensures that Trunk always tests against the latest state of your target branch and never merges a PR that would conflict with a commit that landed externally. -#### Make the switch +#### Why complete the migration -Once you have [configured settings](administration/advanced-settings.md) and tested out the workflow quietly, turn off other merge tools (like [GitHub merge queue](migrating-from-github-merge-queue.md#turn-off-github-merge-queue)), re-enable GitHub comments in the Trunk web app under the **Merge Queue** tab **>** repository **> Settings >** toggle **on GitHub Comments** +The handling above is correct, but every restart cancels in-flight test runs and re-tests against the new target branch head. With both queues active and busy, in-flight PRs from both sides will preempt each other, and your team will see slower merge times overall. That is why dual mode is a verification step, not a long-term mode. {% hint style="info" %} -It is important that a repository is configured to use ONLY Trunk Merge Queue and no other merge queue tools for best results. +A repository should be configured to use ONLY Trunk Merge Queue. Running both queues long-term degrades the merge experience for the whole team. {% endhint %} -#### Share the news +*** + +### Dev-facing announcement copy + +Once you've cut over, share the change with your team. Below is a template admins can adapt for Slack or email. -Now that you have migrated to Trunk Merge Queue, be sure to share the workflow with your team, [using-the-queue](using-the-queue/ "mention")as a great place to start. +> **Heads up: we're moving to Trunk Merge Queue.** +> +> Starting \[date], pull requests on `[repo]` will merge through Trunk Merge Queue instead of GitHub's. The day-to-day flow is the same: open a PR, get required checks green, then post `/trunk merge` on the PR instead of clicking GitHub's "Merge when ready" button. +> +> Trunk will leave a comment on each PR with its queue position and status. The full developer workflow is documented at \[link to Trunk's Using the Queue page]. +> +> Questions? Reply in this thread or DM \[admin contact]. *** ### Getting help -If you or your team are running into issues be sure to join the [Trunk Slack community](https://slack.trunk.io/) for assistance. +If you or your team are running into issues, join the [Trunk Slack community](https://slack.trunk.io/) for assistance. From 3f6eefbed07d184518c4d22dc87234bd7e31f5e6 Mon Sep 17 00:00:00 2001 From: Sam Gutentag <1404219+samgutentag@users.noreply.github.com> Date: Mon, 18 May 2026 09:53:19 -0700 Subject: [PATCH 2/2] docs(merge-queue): reframe migration page around same-day switch as default Push Pattern A (clean same-day switch) as the recommended path and demote Pattern B (admin-driven validation) to a smaller "Cautious route" section. Anti-pattern (long-term dual mode) is now a single warning callout instead of its own subsection. Moves the "Trunk handles external merges gracefully" claim into the Cautious route section, where it is genuinely a safety net for accidental collisions during validation, not a feature that supports long-term coexistence. Co-Authored-By: Claude Opus 4.7 (1M context) --- .../migrating-from-github-merge-queue.md | 59 ++++++++----------- 1 file changed, 26 insertions(+), 33 deletions(-) diff --git a/merge-queue/migrating-from-github-merge-queue.md b/merge-queue/migrating-from-github-merge-queue.md index 2406aef4..2c599610 100644 --- a/merge-queue/migrating-from-github-merge-queue.md +++ b/merge-queue/migrating-from-github-merge-queue.md @@ -1,19 +1,20 @@ --- description: >- - Move a repository from GitHub Merge Queue to Trunk Merge Queue with a brief - dual-mode validation followed by a full switch. + Move a repository from GitHub Merge Queue to Trunk Merge Queue with a clean + same-day switch. Optional cautious route for teams that want to validate + first. --- # Migrate from GitHub Merge Queue -For teams switching from [GitHub Merge Queues](https://docs.github.com/en/pull-requests/collaborating-with-pull-requests/incorporating-changes-from-a-pull-request/merging-a-pull-request-with-a-merge-queue) to Trunk Merge Queue, the recommended path is a short dual-mode validation followed by a full switch to Trunk. +For teams switching from [GitHub Merge Queues](https://docs.github.com/en/pull-requests/collaborating-with-pull-requests/incorporating-changes-from-a-pull-request/merging-a-pull-request-with-a-merge-queue) to Trunk Merge Queue, the recommended path is a clean same-day switch: set up Trunk, disable GitHub Merge Queue, and announce to your team. {% hint style="success" %} Looking for a more detailed comparison between Trunk and GitHub's Merge Queues? [Learn more](https://trunk.io/trunk-vs-github-merge-queue) {% endhint %} {% hint style="warning" %} -Running both queues for an extended period is not recommended. Use dual mode only to verify Trunk's settings against a few real PRs, then disable GitHub Merge Queue and run on Trunk only. See [Why complete the migration](#why-complete-the-migration) for the reasoning. +Don't run both queues for an extended period. Long-term dual mode means in-flight PRs from both sides preempt each other and your team will see slower merge times overall. Pick one queue. {% endhint %} *** @@ -22,62 +23,54 @@ Running both queues for an extended period is not recommended. Use dual mode onl The recommended sequence for admins moving a repository from GitHub Merge Queue to Trunk Merge Queue. -#### 1. Enable Trunk Merge Queue alongside GitHub +#### 1. Set up Trunk Merge Queue -Follow [Getting Started](getting-started/) to install Trunk and configure your repository. Leave GitHub Merge Queue enabled for now. +Follow [Getting Started](getting-started/) to install Trunk and configure your repository. Configure branch protection rules to include Trunk's status checks, and review [Advanced settings](administration/advanced-settings.md) such as timeouts, batching, and optimistic merging for your repo. -Before opting your team in, turn off Trunk's automatic PR comments so developers aren't confused by comments from a queue they don't yet know about. +Keep Trunk's automatic PR comments off for now so developers aren't surprised by comments from a queue they don't yet know about. This setting is under **Merge Queue** tab **>** repository **> Settings >** toggle **off GitHub Comments.** -This setting is under **Merge Queue** tab **>** repository **> Settings >** toggle **off GitHub Comments.** +#### 2. Disable GitHub Merge Queue -#### 2. Verify settings in dual mode - -With both queues enabled, run a few real PRs through Trunk to confirm: - -* Branch protection rules trigger the required checks you expect. -* Test orchestration policies match your repo's CI. -* [Advanced settings](administration/advanced-settings.md) such as timeouts, batching, and optimistic merging behave correctly for your repo. - -Dual mode exists for this validation step only. The goal is to confirm Trunk's configuration before committing to the switch, not to run both queues indefinitely. See [What happens during dual mode](#what-happens-during-dual-mode) for behavior details. - -#### 3. Turn off GitHub Merge Queue - -Once you've validated Trunk's configuration, disable GitHub Merge Queue. In the GitHub repository, navigate to **Settings > Branches >** branch rule **>** toggle **off Require merge queue.** Click **Save changes** to confirm. +In the GitHub repository, navigate to **Settings > Branches >** branch rule **>** toggle **off Require merge queue.** Click **Save changes** to confirm. {% hint style="info" %} Only users with GitHub admin permissions can manage merge queues for pull requests targeting selected branches of a repository. See GitHub's [managing merge queues](https://docs.github.com/en/repositories/configuring-branches-and-merges-in-your-repository/managing-protected-branches/managing-a-branch-protection-rule#creating-a-branch-protection-rule) documentation for details. {% endhint %} -#### 4. Re-enable Trunk's GitHub comments and announce +#### 3. Turn on Trunk's PR comments + +Turn Trunk's automatic PR comments back on under **Merge Queue** tab **>** repository **> Settings >** toggle **on GitHub Comments.** This is when Trunk becomes visible to your team on every PR. -Turn Trunk's automatic PR comments back on under the **Merge Queue** tab **>** repository **> Settings >** toggle **on GitHub Comments.** +#### 4. Announce to your team Share the change with your team. See [Dev-facing announcement copy](#dev-facing-announcement-copy) for a template you can paste into Slack or email, and [Using the Queue](using-the-queue/) for the full developer workflow. *** -### What happens during dual mode +### Cautious route: validate first -While both queues are enabled, Trunk Merge Queue detects when a PR is merged outside of its queue (for example, by GitHub's merge queue or a direct push to the target branch): +If you want to confirm Trunk's configuration on a few real PRs before disabling GitHub Merge Queue, run a short validation window before doing step 2 above. -* **If the PR is also in Trunk's queue**: Trunk automatically marks it as merged on its side. -* **If the PR is not in Trunk's queue**: Trunk restarts any PRs currently in its queue so they can test on top of the new commit. +1. Complete step 1 (set up Trunk Merge Queue, GitHub Comments toggled off). +2. As an admin, post `/trunk merge` on a handful of representative PRs to confirm Trunk processes them as expected. Watch for required checks running, optimistic merging behavior, timeouts, and any anti-flake protections behaving as you'd expect. +3. Once confident, continue with steps 2 through 4 above. -This ensures that Trunk always tests against the latest state of your target branch and never merges a PR that would conflict with a commit that landed externally. +During this window, most PRs continue merging through GitHub's queue as normal. Only PRs where the admin explicitly posts `/trunk merge` enter Trunk's queue. -#### Why complete the migration +{% hint style="info" %} +**Safety net.** If a PR ends up enqueued in both queues at once, or if a commit lands on your target branch from outside Trunk while Trunk has in-flight PRs, Trunk handles it correctly: -The handling above is correct, but every restart cancels in-flight test runs and re-tests against the new target branch head. With both queues active and busy, in-flight PRs from both sides will preempt each other, and your team will see slower merge times overall. That is why dual mode is a verification step, not a long-term mode. +* A queued PR merged externally is marked as merged on Trunk's side. +* An external commit on the target branch restarts any of Trunk's in-flight PRs so they re-test on the new target branch head. -{% hint style="info" %} -A repository should be configured to use ONLY Trunk Merge Queue. Running both queues long-term degrades the merge experience for the whole team. +These are safeguards against accidental collisions during validation, not features that support long-term coexistence. {% endhint %} *** ### Dev-facing announcement copy -Once you've cut over, share the change with your team. Below is a template admins can adapt for Slack or email. +Once you've switched, share the change with your team. Below is a template admins can adapt for Slack or email. > **Heads up: we're moving to Trunk Merge Queue.** >