Skip to main content

Documentation Index

Fetch the complete documentation index at: https://trunk-4cab4936-sam-gutentag-mergify-migration.mintlify.app/llms.txt

Use this file to discover all available pages before exploring further.

For teams moving off Mergify, the migration is usually motivated by platform reliability, per-target test selection, or both. The biggest conceptual change: Mergify rules decide both whether a PR enters the queue and what gets tested, while Trunk splits those concerns — GitHub rulesets decide admission, and Trunk decides testing once a PR is in the queue.

​
Migration sequence

Recommended order. Each step is independent; you can pause between any of them.

​
1. Inventory existing Mergify rules

Catalog your current .mergify.yml:
  • Admission rules (which PRs enter the queue) → these become GitHub rulesets.
  • Status-check requirements (which checks are required) → these become required_statuses in trunk.yaml, possibly aggregated by a workflow if Mergify used OR-logic.
  • Priority rules → these become labels + the submit API, or /trunk merge --high-priority.
  • Per-rule testing conditionals → these become setImpactedTargets calls in CI.
See the construct mapping below for the full detail on each.

​
2. Configure GitHub rulesets

Move admission logic out of Mergify and into GitHub rulesets first. Verify rulesets behave as expected with a small group of PRs before enabling Trunk.

​
3. Enable Trunk Merge Queue

Follow the Getting Started guide to install the Trunk GitHub App, configure trunk.yaml, and connect your repository.

​
4. Turn off Mergify

Once Trunk is handling your queue traffic cleanly, uninstall the Mergify GitHub App from the repository and remove (or comment out) your .mergify.yml so its rules can’t re-activate if the app is ever re-installed.
Configure a repository to use ONLY one merge queue tool at a time. Running Trunk and Mergify simultaneously on overlapping PRs is not a supported configuration — both systems target PR admission and merging, and their behaviors can conflict.

​
5. Share the rollout

Point your team at Using the Queue so they know how to interact with the new merge flow.

​
Mapping Mergify constructs to Trunk

Reference detail for each Mergify construct and where it lives in Trunk.

​
queue_rules → Trunk queue settings + GitHub rulesets

Mergify queue_rules typically combine admission criteria (which PRs can enter), batching behavior, and merge conditions. In Trunk these split across two surfaces:
  • Admission criteria move to GitHub branch protection rules or rulesets. Required status checks, required reviews, and merge restrictions all live there.
  • Queue behavior (batching, parallel queues, priority) is configured in the Trunk web app or via advanced queue settings.

​
required_status_checks with OR-clauses → rulesets + an aggregator action

Mergify natively supports OR-clauses on required status checks (for example, “require either ci-fast or ci-full to pass”). Trunk’s trunk.yaml required_statuses is a flat list with implicit AND semantics, so Mergify users with conditional check logic need to handle the OR upstream:
  • Use GitHub rulesets to define conditional admission. Rulesets support per-pattern and per-condition rules that can encode OR-logic at the GitHub layer.
  • For check-level conditional logic that rulesets can’t express, write an aggregator action: a GitHub Actions workflow that runs the conditional logic and emits a single status check Trunk can require. This is a one-time setup cost but keeps trunk.yaml simple.
Aggregator actions are the migration tax for teams with complex Mergify rules. Teams with straightforward AND-only required checks won’t need them.

​
priority_rules → labels + the submit API

Mergify priority rules map to two Trunk mechanisms:
  • Manual priority via /trunk merge --high-priority on a PR comment, or the equivalent action in the Trunk web app.
  • Label-driven priority via the submit Pull Request endpoint with a priority field. Use this when you want automation (a GitHub Action, an external service) to set priority based on PR metadata.

​
Per-rule conditional testing → impacted_targets API

In Mergify, per-rule conditionals often gate which tests run for which PRs. In Trunk this is handled by the setImpactedTargets API: your CI computes the set of targets affected by a PR and reports them to Trunk, which uses that set to decide what to test in the queue. This is a different concept from Mergify’s rule-level conditionals — it operates per-PR based on actual file changes, not per-rule based on PR metadata. For most teams this is a strict upgrade in precision; for teams that used Mergify rules to encode “if PR touches folder X, run test Y,” the equivalent is computing impacted targets in CI and POSTing them before the PR enters the queue.

​
Observability and reliability

The other common migration driver is platform observability. Trunk’s surface here:
  • status.trunk.io — public status page with subscriber push notifications. Status changes also surface in the Trunk web app UI directly.
  • Stalled-queue response — Trunk treats stalled queues as all-hands incidents. Multiple internal stall-pattern alerts fire across the team simultaneously, not a single on-call paged in isolation.
  • Testing-timeout safety net — Trunk enforces a configurable test-timeout so a single hung test can’t stall the queue indefinitely.
  • Public scrapeable metrics endpoint — Trunk exposes a Prometheus-style metrics endpoint you can point your monitoring stack at for customer-side alerting on queue depth, throughput, and per-PR latency.
The metrics endpoint is the recommended path for teams who want their existing dashboards (Grafana, Datadog) to alert on Trunk queue health alongside their other infrastructure.

​
Getting help

If you or your team are running into issues, contact support@trunk.io for assistance.