diff --git a/docs.json b/docs.json index 51458a7e..639bca3b 100644 --- a/docs.json +++ b/docs.json @@ -97,7 +97,7 @@ "merge-queue/using-the-queue/monitor-queue-status", "merge-queue/using-the-queue/handle-failed-pull-requests", "merge-queue/using-the-queue/emergency-pull-requests", - "merge-queue/using-the-queue/force-merge" + "merge-queue/using-the-queue/direct-to-queue" ] }, "merge-queue/integration-for-slack", @@ -1065,6 +1065,10 @@ } }, "redirects": [ + { + "source": "/merge-queue/using-the-queue/force-merge", + "destination": "/merge-queue/using-the-queue/direct-to-queue" + }, { "source": "/merge-queue/chrome-extension", "destination": "/merge-queue/browser-extensions" diff --git a/merge-queue/getting-started/configure-branch-protection.mdx b/merge-queue/getting-started/configure-branch-protection.mdx index 10f4f140..1ef809d0 100644 --- a/merge-queue/getting-started/configure-branch-protection.mdx +++ b/merge-queue/getting-started/configure-branch-protection.mdx @@ -122,7 +122,7 @@ Splitting them keeps Trunk's bypass scope minimal: GitHub bypass permissions app 2. Target the same protected branch (e.g., `main`) with the same single-include targeting. 3. Under **Rules** → **Branch rules**, add the rules that gate mergeability — typically **Require a pull request before merging** and **Require status checks to pass**. Add others (signed commits, linear history, etc.) as your team requires. 4. **Do not** add the Trunk GitHub App (`trunk-io`) to the bypass list. The queue relies on GitHub reporting the PR as not-yet-ready until these rules pass. -5. Optionally, add **Trunk Sudo** to the bypass list as **Exempt** if you use [Force merge](../using-the-queue/force-merge). See the [Trunk Sudo page](../../setup-and-administration/trunk-sudo-app) for the full guidance. +5. Optionally, add **Trunk Sudo** to the bypass list as **Exempt** if you use [Direct to queue](../using-the-queue/direct-to-queue). See the [Trunk Sudo page](../../setup-and-administration/trunk-sudo-app) for the full guidance. 6. Save. @@ -186,7 +186,7 @@ For each Branch ruleset whose **Branch targeting criteria** could match `trunk-t - Ruleset #2 targets only your protected branch and does **not** bypass Trunk. - Every other Branch ruleset visible at the organization level and on this repository either does not match `trunk-temp/**/*`/`trunk-merge/**/*`, or explicitly excludes both patterns. - (If using [Trunk Sudo](../../setup-and-administration/trunk-sudo-app)) Trunk Sudo is on Ruleset #1's bypass list as **Exempt**. -- (If using [Trunk Sudo](../../setup-and-administration/trunk-sudo-app) **and** Force merge) Trunk Sudo is also on Ruleset #2's bypass list as **Exempt**. +- (If using [Trunk Sudo](../../setup-and-administration/trunk-sudo-app) **and** Direct to queue) Trunk Sudo is also on Ruleset #2's bypass list as **Exempt**. ### Migrating from Classic rules to Rulesets @@ -199,7 +199,7 @@ If you already use Classic branch protection, GitHub provides an **Import a rule ### Option B — Classic branch protection -Classic branch protection still works with Trunk Merge Queue, but is no longer the recommended path. Some Classic rules (required status checks and "Require branches to be up to date") cannot be bypassed by any GitHub App, which limits features like [Force merge](../using-the-queue/force-merge). Use Rulesets when you can. +Classic branch protection still works with Trunk Merge Queue, but is no longer the recommended path. Some Classic rules (required status checks and "Require branches to be up to date") cannot be bypassed by any GitHub App, which limits features like [Direct to queue](../using-the-queue/direct-to-queue). Use Rulesets when you can. **Configure push restrictions (required)** @@ -262,8 +262,8 @@ To verify and fix: - **Using Force merge or other bypass-dependent features?** Features like [Force - merge](../using-the-queue/force-merge) require the separate [Trunk Sudo GitHub + **Using Direct to queue or other bypass-dependent features?** Features like [Force + merge](../using-the-queue/direct-to-queue) require the separate [Trunk Sudo GitHub App](../../setup-and-administration/trunk-sudo-app), plus additional branch protection configuration to list Trunk Sudo as a bypass actor. That's documented on the Trunk Sudo page. diff --git a/merge-queue/optimizations/priority-merging.mdx b/merge-queue/optimizations/priority-merging.mdx index 905f82bb..730fc018 100644 --- a/merge-queue/optimizations/priority-merging.mdx +++ b/merge-queue/optimizations/priority-merging.mdx @@ -171,7 +171,7 @@ Don't use high priority for: **For true emergencies:** * If priority isn't fast enough → [Emergency pull requests](../using-the-queue/emergency-pull-requests) -* If branch protection is blocking an admin merge → [Force merge](../using-the-queue/force-merge) +* If branch protection is blocking an admin merge → [Direct to queue](../using-the-queue/direct-to-queue) * If you need to pause the queue → **Merge Queue** → **[your repository]** → **Settings** → **Merge Queue State**, then select **Paused** from the dropdown. **Monitor impact:** diff --git a/merge-queue/using-the-queue/direct-to-queue.mdx b/merge-queue/using-the-queue/direct-to-queue.mdx new file mode 100644 index 00000000..d9333fca --- /dev/null +++ b/merge-queue/using-the-queue/direct-to-queue.mdx @@ -0,0 +1,96 @@ +--- +title: "Direct to queue" +description: "Admins can send a pull request directly to Merge Queue even when GitHub branch protection rules aren't satisfied. The PR is still tested; only the final merge bypasses protection." +og:title: "Direct to queue in Trunk Merge Queue" +--- + +## What it is + +Direct to queue lets a GitHub repository admin send a pull request directly to the Trunk Merge Queue even when branch protection requirements are not satisfied. The PR is still tested by the queue exactly like any other PR — only the final protection gate is bypassed at merge time, using the [Trunk Sudo GitHub App](../../setup-and-administration/trunk-sudo-app). + + +**Direct to queue is admin-only and can only be triggered by a GitHub comment.** Trunk verifies admin identity via GitHub comment authorship, which is why other submission paths (CLI, checkbox, web app) don't support it. If a non-admin posts `/trunk merge --direct`, Trunk will reply on the PR with a rejection comment explaining that the command requires admin access. + + +## Why use it + +* **Unblock misconfigured protection.** Ship a PR when a required status check is broken or misconfigured, without disabling the rule for everyone else. +* **Merge emergency fixes safely.** You still get queue validation — predictive testing, batching, failure detection — instead of merging directly to `main` and hoping for the best. +* **Avoid direct-to-`main` bypass.** Direct to queue is strictly safer than pushing to the protected branch manually, because the PR is fully tested before it lands. + +## Prerequisites + +Before you can use direct to queue, make sure you have: + +* [Trunk Sudo GitHub App](../../setup-and-administration/trunk-sudo-app) installed and configured for this repository +* GitHub admin access on the repository + +## How to use it + +### Via GitHub comment + +On any pull request, post: + +``` +/trunk merge --direct +``` + + +`--force` is still accepted as an alias for `--direct`, so existing automation keeps working. + + +Trunk verifies admin identity through GitHub comment authorship, so the command is only accepted through the PR comment flow. + +## What happens step by step + +1. **Admission.** The PR enters the queue despite branch protection not being satisfied. Normally Trunk Merge Queue waits until GitHub marks a PR as ready to merge; `--direct` skips that wait. +2. **Testing.** The PR is tested normally. Batching, ordering, priority, and failure handling all behave exactly as they would for any other PR — nothing about the testing pipeline changes. +3. **Merge.** If tests pass, Trunk Sudo merges the PR, bypassing branch protection. Without Trunk Sudo installed and configured, this step will fail. +4. **Failure.** If tests fail, the PR is handled like any normal queue failure. See [Handle failed pull requests](./handle-failed-pull-requests). + +After a PR is sent directly to the queue, it shows a **Forced** badge in the Merge Queue dashboard PR list so you can identify which merges bypassed branch protection. + +## Combining with other flags + +Direct to queue can be combined with other `/trunk merge` flags. The most common combination is with [priority](../optimizations/priority-merging) when both urgency and protection bypass are needed — for example: + +``` +/trunk merge --direct --priority=urgent +``` + +## Tradeoffs and considerations + +### What you gain + +* **Queue validation is preserved** — tests still run before merge. +* **No direct-to-`main` push** — the PR goes through the same merge flow as every other PR. +* **Unblock stuck PRs** without weakening your default branch protection for everyone. + +### What you give up + +* **Bypasses the human review gate** if required reviews aren't satisfied. +* **Bypasses required status checks** that would otherwise block the merge. +* Because direct to queue bypasses protections that every other PR must satisfy, overuse erodes the value of those protections. + +### When NOT to use direct to queue + +* **Normal feature work.** If a PR is going to merge eventually, let it wait for reviews and checks. +* **"The required check is slow."** Fix the check or the CI configuration — direct to queue is not a substitute for unbreaking your pipeline. +* **Non-admin urgency.** If you aren't an admin, don't ask an admin to send your PR directly to the queue — escalate via the usual incident or on-call process. + +## Common misconceptions + +* **Misconception:** "Direct to queue skips testing." + * **Reality:** Tests still run normally. The PR goes through the full merge queue testing pipeline — only the branch protection gate is bypassed at merge time. +* **Misconception:** "Direct to queue is the same as emergency pull requests." + * **Reality:** [Emergency pull requests](./emergency-pull-requests) bypass the queue entirely and push directly to your merge branch. Direct to queue still goes through the queue and still tests the PR — it only bypasses branch protection at merge time. + +## Visibility in the queue dashboard + +Pull requests sent directly to the queue appear with a **Forced** badge in the merge queue PR list. This lets you identify which PRs bypassed branch protection at a glance without opening each PR individually. + +## Next steps + +* [Trunk Sudo GitHub App](../../setup-and-administration/trunk-sudo-app) — install and configure the app that powers direct to queue. +* [Emergency pull requests](./emergency-pull-requests) — when the queue itself needs to be bypassed, not just branch protection. +* [Priority merging](../optimizations/priority-merging) — fast-track a PR without bypassing any rules. diff --git a/merge-queue/using-the-queue/emergency-pull-requests.mdx b/merge-queue/using-the-queue/emergency-pull-requests.mdx index 6c8c918d..b0656444 100644 --- a/merge-queue/using-the-queue/emergency-pull-requests.mdx +++ b/merge-queue/using-the-queue/emergency-pull-requests.mdx @@ -25,4 +25,4 @@ The `urgent` priority is the only level that will interrupt currently testing PR ### See also -If the blocker is branch protection (not the queue) — for example, a broken required status check — admins can use [Force merge](./force-merge) instead. Force merge still goes through the queue and still tests the PR; only the branch protection gate is bypassed at merge time. +If the blocker is branch protection (not the queue) — for example, a broken required status check — admins can use [Direct to queue](./direct-to-queue) instead. Direct to queue still goes through the queue and still tests the PR; only the branch protection gate is bypassed at merge time. diff --git a/merge-queue/using-the-queue/force-merge.mdx b/merge-queue/using-the-queue/force-merge.mdx deleted file mode 100644 index d068450a..00000000 --- a/merge-queue/using-the-queue/force-merge.mdx +++ /dev/null @@ -1,93 +0,0 @@ ---- -title: "Force merge" -description: "Admins can push a pull request through Merge Queue even when GitHub branch protection rules aren't satisfied. The PR is still tested; only the final merge bypasses protection." -og:title: "Force merge in Trunk Merge Queue" ---- -## What it is - -Force merge lets a GitHub repository admin push a pull request through the Trunk Merge Queue even when branch protection requirements are not satisfied. The PR is still tested by the queue exactly like any other PR — only the final protection gate is bypassed at merge time, using the [Trunk Sudo GitHub App](../../setup-and-administration/trunk-sudo-app). - - -**Force merge is admin-only and can only be triggered by a GitHub comment.** Trunk verifies admin identity via GitHub comment authorship, which is why other submission paths (CLI, checkbox, web app) don't support `--force`. If a non-admin posts `/trunk merge --force`, Trunk will reply on the PR with a rejection comment explaining that the command requires admin access. - - -## Why use it - -* **Unblock misconfigured protection.** Ship a PR when a required status check is broken or misconfigured, without disabling the rule for everyone else. -* **Merge emergency fixes safely.** You still get queue validation — predictive testing, batching, failure detection — instead of merging directly to `main` and hoping for the best. -* **Avoid direct-to-`main` bypass.** Force merge is strictly safer than pushing to the protected branch manually, because the PR is fully tested before it lands. - -## Prerequisites - -Before you can use force merge, make sure you have: - -* [Trunk Sudo GitHub App](../../setup-and-administration/trunk-sudo-app) installed and configured for this repository -* GitHub admin access on the repository - -## How to use it - -### Via GitHub comment - -On any pull request, post: - -``` -/trunk merge --force -``` - -There is no CLI, checkbox, or web app equivalent. This is intentional: Trunk verifies admin identity through GitHub comment authorship, so the command is only accepted through the PR comment flow. - -## What happens step by step - -1. **Admission.** The PR enters the queue despite branch protection not being satisfied. Normally Trunk Merge Queue waits until GitHub marks a PR as ready to merge; `--force` skips that wait. -2. **Testing.** The PR is tested normally. Batching, ordering, priority, and failure handling all behave exactly as they would for any other PR — nothing about the testing pipeline changes. -3. **Merge.** If tests pass, Trunk Sudo merges the PR, bypassing branch protection. Without Trunk Sudo installed and configured, this step will fail. -4. **Failure.** If tests fail, the PR is handled like any normal queue failure. See [Handle failed pull requests](./handle-failed-pull-requests). - -After a PR is force-merged, the PR shows a **Forced** badge in the Merge Queue dashboard PR list so you can identify which merges bypassed branch protection. - -## Combining with other flags - -Force merge can be combined with other `/trunk merge` flags. The most common combination is with [priority](../optimizations/priority-merging) when both urgency and protection bypass are needed — for example: - -``` -/trunk merge --force --priority=urgent -``` - -## Tradeoffs and considerations - -### What you gain - -* **Queue validation is preserved** — tests still run before merge. -* **No direct-to-`main` push** — the PR goes through the same merge flow as every other PR. -* **Unblock stuck PRs** without weakening your default branch protection for everyone. - -### What you give up - -* **Bypasses the human review gate** if required reviews aren't satisfied. -* **Bypasses required status checks** that would otherwise block the merge. -* Because force merge bypasses protections that every other PR must satisfy, overuse erodes the value of those protections. - -### When NOT to use force merge - -* **Normal feature work.** If a PR is going to merge eventually, let it wait for reviews and checks. -* **"The required check is slow."** Fix the check or the CI configuration — force merge is not a substitute for unbreaking your pipeline. -* **Non-admin urgency.** If you aren't an admin, don't ask an admin to force merge your PR — escalate via the usual incident or on-call process. - -## Common misconceptions - -* **Misconception:** "Force merge skips testing." - * **Reality:** Tests still run normally. The PR goes through the full merge queue testing pipeline — only the branch protection gate is bypassed at merge time. -* **Misconception:** "I can force merge through the CLI." - * **Reality:** Force merge is comment-only and admin-only. The CLI, web app checkbox, and "Retry" button don't accept `--force`. -* **Misconception:** "Force merge is the same as emergency pull requests." - * **Reality:** [Emergency pull requests](./emergency-pull-requests) bypass the queue entirely and push directly to your merge branch. Force merge still goes through the queue and still tests the PR — it only bypasses branch protection at merge time. - -## Visibility in the queue dashboard - -Force-merged pull requests appear with a **Forced** badge in the merge queue PR list. This lets you identify which PRs bypassed branch protection at a glance without opening each PR individually. - -## Next steps - -* [Trunk Sudo GitHub App](../../setup-and-administration/trunk-sudo-app) — install and configure the app that powers force merge. -* [Emergency pull requests](./emergency-pull-requests) — when the queue itself needs to be bypassed, not just branch protection. -* [Priority merging](../optimizations/priority-merging) — fast-track a PR without bypassing any rules. diff --git a/setup-and-administration/github-app-permissions.mdx b/setup-and-administration/github-app-permissions.mdx index 57d83a0b..0a1bb835 100644 --- a/setup-and-administration/github-app-permissions.mdx +++ b/setup-and-administration/github-app-permissions.mdx @@ -10,7 +10,7 @@ You can install the Trunk GitHub App by navigating to **Settings** → **Organiz The Trunk GitHub App enables functionality for all of Trunk's tools. Not every permission is required for every feature of Trunk, and if you have only enabled one of our tools, we will only access the permissions pertaining to that tool. For complete documentation of the individual permissions the Trunk GitHub App requires, see the [GitHub developer docs](https://docs.github.com/en/rest/authentication/permissions-required-for-github-apps). Below, find an explanation of every permission the Trunk GitHub App requires and what Trunk uses it for. -**Looking for the Trunk Sudo app?** Trunk also provides a separate [Trunk Sudo GitHub App](./trunk-sudo-app), used by features that need to merge pull requests while bypassing GitHub branch protections (such as [Force merge](../merge-queue/using-the-queue/force-merge)). It's optional and only required if you use one of those features. +**Looking for the Trunk Sudo app?** Trunk also provides a separate [Trunk Sudo GitHub App](./trunk-sudo-app), used by features that need to merge pull requests while bypassing GitHub branch protections (such as [Direct to queue](../merge-queue/using-the-queue/direct-to-queue)). It's optional and only required if you use one of those features. ## **Repository permissions** diff --git a/setup-and-administration/trunk-sudo-app.mdx b/setup-and-administration/trunk-sudo-app.mdx index ffcece1a..689d51d5 100644 --- a/setup-and-administration/trunk-sudo-app.mdx +++ b/setup-and-administration/trunk-sudo-app.mdx @@ -5,7 +5,7 @@ og:title: "The Trunk Sudo GitHub App" --- Trunk Sudo is a second Trunk GitHub App, separate from the [main Trunk GitHub App](./github-app-permissions). Its only purpose is to programmatically merge pull requests while bypassing GitHub branch protections, on behalf of Trunk features that need that capability. -Trunk Sudo is a prerequisite for bypass-dependent features. Today the only such feature is [Force merge](../merge-queue/using-the-queue/force-merge). +Trunk Sudo is a prerequisite for bypass-dependent features. Today the only such feature is [Direct to queue](../merge-queue/using-the-queue/direct-to-queue). **Trunk Sudo is optional.** You only need to install it if you plan to use a feature that requires it. If you don't use any bypass-dependent features, you can skip this setup. @@ -118,6 +118,6 @@ Required so Trunk Sudo can merge PRs that modify files under `.github/`. GitHub ## Next steps -→ [**Force merge**](../merge-queue/using-the-queue/force-merge) — use the Trunk Sudo app to merge PRs through the queue that don't satisfy branch protection. +→ [**Direct to queue**](../merge-queue/using-the-queue/direct-to-queue) — use the Trunk Sudo app to merge PRs through the queue that don't satisfy branch protection. → For the main Trunk GitHub App and its permissions, see [Trunk GitHub App](./github-app-permissions).