Skip to content

GitHub failure reference page #298

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Merged
pv72895 merged 4 commits into from
Jul 22, 2026
Merged

GitHub failure reference page #298

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
4 commits
Select commit Hold shift + click to select a range
18a6a5c
GitHub failure reference page
pv72895 Jul 21, 2026
2472beb
wording fixes
pv72895 Jul 21, 2026
511e116
script fix
pv72895 Jul 21, 2026
89c5469
address review comments
pv72895 Jul 21, 2026
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
30 changes: 8 additions & 22 deletions docs.json
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -44,9 +44,7 @@
"tabs": [
{
"tab": "Overview",
"pages": [
"index"
]
"pages": ["index"]
},
{
"tab": "Merge Queue",
Expand Down Expand Up @@ -124,9 +122,7 @@
},
{
"group": "Metrics Endpoints",
"pages": [
"GET /getMergeQueueMetrics"
]
"pages": ["GET /getMergeQueueMetrics"]
},
{
"group": "Queue Endpoints",
Expand All @@ -153,7 +149,8 @@
"root": "merge-queue/reference/index",
"pages": [
"merge-queue/reference/common-problems",
"merge-queue/reference/troubleshooting"
"merge-queue/reference/troubleshooting",
"merge-queue/reference/github-api-failures"
]
},
"merge-queue/changelog"
Expand All @@ -170,9 +167,7 @@
{
"group": "Overview",
"root": "flaky-tests/overview",
"pages": [
"flaky-tests/dashboard"
]
"pages": ["flaky-tests/dashboard"]
},
{
"group": "Getting Started",
Expand Down Expand Up @@ -304,9 +299,7 @@
},
{
"group": "Recipes",
"pages": [
"flaky-tests/recipes/alert-on-test-escalation"
]
"pages": ["flaky-tests/recipes/alert-on-test-escalation"]
},
{
"group": "Agents",
Expand Down Expand Up @@ -726,9 +719,7 @@
},
{
"group": "October",
"pages": [
"changelog/2025-10-09-plugins-1-7-3"
]
"pages": ["changelog/2025-10-09-plugins-1-7-3"]
},
{
"group": "September",
Expand Down Expand Up @@ -1016,12 +1007,7 @@
}
},
"contextual": {
"options": [
"copy",
"view",
"chatgpt",
"claude"
]
"options": ["copy", "view", "chatgpt", "claude"]
},
"footer": {
"socials": {
Expand Down
2 changes: 1 addition & 1 deletion merge-queue/getting-started/index.mdx
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -99,7 +99,7 @@ If your test PR doesn't merge automatically:

- **Check the status comments for the PR in** the [Trunk Dashboard](https://app.trunk.io/) to see what it's waiting for
- **Stuck in "Queued"**: Usually means branch protection rules haven't passed (missing required status checks or code review) or there are merge conflicts. If the status looks correct but the PR still won't enter the queue, try [removing](../using-the-queue/reference#submitting-and-cancelling-pull-requests) and re-adding by commenting `/trunk merge` again on the PR.
- **Fails when attempting to merge**: Check that squash merges are enabled for your repository in GitHub settings (`Settings > General > Allow squash merging`). Trunk Merge Queue requires squash merges to be enabled.
- **Fails when attempting to merge**: Check that the [merge method](/merge-queue/administration/advanced-settings#merge-method) your queue is configured to use (squash by default) is enabled for your repository in GitHub settings (`Settings > General`).
- **"Permission denied" errors**: Review the [Branch Protection](./configure-branch-protection) guide to make sure `trunk-temp/*` and `trunk-merge/*` branches aren't protected by wildcard rules like `*/*`.
- **Status checks not running**: Verify your CI is configured to run on draft PRs (or `trunk-merge/**` branches if using push-triggered mode). See the [Branch Protection](./configure-branch-protection) guide for details.

Expand Down
26 changes: 21 additions & 5 deletions merge-queue/reference/common-problems.mdx
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -13,6 +13,7 @@ og:title: "Trunk Merge Queue FAQ"
First, check the Trunk web app to see what Trunk is waiting on before putting your PR into the merge queue.

Next, if something on that page doesn't look right, for example, it says that GitHub is still checking the mergeability of the PR, comment `/trunk merge` again in the PR.

</Accordion>

<Accordion title="Why aren't my required checks triggering, even though my pull request is being tested in queue?">
Expand All @@ -33,6 +34,7 @@ og:title: "Trunk Merge Queue FAQ"
<Info>
**Note:** The merge method applies to the entire repository, not on a per-PR basis. See [Merge Method documentation](/merge-queue/administration/advanced-settings#merge-method) for detailed information on each option and how to configure your preference.
</Info>

</Accordion>

<Accordion title="How does Trunk handle commit messages">
Expand All @@ -45,6 +47,7 @@ og:title: "Trunk Merge Queue FAQ"
You can override the merge commit title for any PR by adding `merge-commit-title: Your Custom Title` on its own line in the PR body. See the FAQ below for details.

You can configure your preferred merge method in [Advanced Settings](../administration/advanced-settings#merge-method).

</Accordion>

<Accordion title="Can I customize the merge commit title for a pull request?">
Expand All @@ -63,9 +66,10 @@ og:title: "Trunk Merge Queue FAQ"
```markdown
## Description
This PR adds user authentication.

merge-commit-title: feat(auth): add OAuth2 login flow [PROJ-123]
```

</Accordion>

<Accordion title="Do Optimistic Merging or Batching ever merge multiple pull requests into a single commit?">
Expand All @@ -75,6 +79,7 @@ og:title: "Trunk Merge Queue FAQ"

- [Optimistic Merging](../optimizations/optimistic-merging) uses the successful test of a pull request later in the queue to validate all the PRs ahead of it in the queue, allowing the entire sequence to be merged without waiting for the earlier PRs to finish testing.
- [Batching](../optimizations/batching) allows the queue to _test_ multiple PRs in a single CI job to save time and resources. After the test passes, the PRs in the batch are still merged one by one.

</Accordion>
</AccordionGroup>

Expand All @@ -85,12 +90,14 @@ og:title: "Trunk Merge Queue FAQ"
To create an additional queue, click **New Queue** from the Merge Queue dashboard and select the same repository with a different target branch. See [Multiple queues per repository](../administration/advanced-settings#multiple-queues-per-repository) for details.

For validating significant changes to your CI process or queue configuration without impacting your primary workflow, you can use a fork of your repository. Set up and test a separate merge queue on the fork to make sure your changes work as expected before applying them to your primary repository.

</Accordion>

<Accordion title="What are trunk-temp/* branches, and should CI run on them?">
No, you should configure your CI to completely ignore `trunk-temp/*` branches. Running workflows on them will only create unnecessary or canceled builds.

The `trunk-temp/*` branch is a temporary, intermediate branch that the merge queue uses to assemble the necessary commits for a test run. Once the build is prepared, this branch is immediately renamed to a `trunk-merge/*` branch.

</Accordion>
</AccordionGroup>

Expand All @@ -103,6 +110,7 @@ og:title: "Trunk Merge Queue FAQ"
```

The `urgent` priority is the only level that will interrupt currently testing PRs. Your PR will immediately begin testing, and other PRs will restart after yours completes.

</Accordion>

<Accordion title="How do I merge an emergency pull request right now?">
Expand All @@ -113,6 +121,7 @@ og:title: "Trunk Merge Queue FAQ"
```

The `urgent` priority is the only level that will interrupt currently testing PRs. Your PR will immediately begin testing, and other PRs will restart after yours completes.

</Accordion>
</AccordionGroup>

Expand All @@ -123,22 +132,29 @@ og:title: "Trunk Merge Queue FAQ"
<Frame>
![Example of a Trunk bot PR comment, detailing a failed status check that caused the PR to be removed from the merge queue.](/assets/merge-queue/reference/Screenshot_2025-10-09_at_3.28.03_PM.png)
</Frame>

</Accordion>

<Accordion title='Why does my pull request consistently fail during testing due to "GitHub errors"?'>
Most likely, you have a [branch protection rule](../getting-started/configure-branch-protection) that affects merge branches.

For example, the wild card rule `*/*` applies to `trunk-merge/...`. The Trunk GitHub app does not have admin privileges, so it fails to do some actions on protected branches. To resolve this, you must remove this rule or contact [support@trunk.io](mailto:support@trunk.io) if that is not possible.
</Accordion>

<Accordion title="Why does my pull request keep failing to merge in the queue?">
The two most likely problems are that you are restricting **who can merge** or that you have **disabled squash merges** into your repo. Trunk Merge Queue needs to use squash merges. To fix this, turn on `'allow squash merges'` for this repo in your GitHub setup.
</Accordion>

<Accordion title="Why does my pull request keep failing to merge in the queue?">
The two most likely problems are that you are restricting **who can merge** or
that the [merge method](../administration/advanced-settings#merge-method) your
queue uses (squash by default) is **disabled in your repo's GitHub settings**.
To fix this, enable that merge method under **Settings → General** in GitHub,
or configure the queue to use a method your repo allows.
</Accordion>

<Accordion title="Why do Dependabot and Renovate pull requests keep getting kicked from the queue?">
By default, both [dependabot](https://docs.github.com/en/code-security/dependabot/working-with-dependabot/managing-pull-requests-for-dependency-updates#changing-the-rebase-strategy-for-dependabot-pull-requests) and [renovate](https://docs.renovatebot.com/updating-rebasing/#updating-and-rebasing-branches) both will rebase their PRs whenever other PRs merge into their base branch. If that rebase happens when those PRs are in the queue, they will get kicked since they were updated. There are two ways to mitigate this:

1. Both dependabot and renovate can be configured to not automatically rebase, while renovate can specifically be configured to only rebase if there's a merge conflict ([dependabot](https://docs.github.com/en/code-security/dependabot/dependabot-version-updates/configuration-options-for-the-dependabot.yml-file#rebase-strategy), [renovate](https://docs.renovatebot.com/configuration-options/#rebasewhen))
2. Their PRs can be manually merged, and anything currently in the merge queue will restart with those merged changes

</Accordion>
</AccordionGroup>
</AccordionGroup>
Loading
Loading