Skip to content

Add Migrate from Mergify page#50

Draft
samgutentag wants to merge 3 commits into
mainfrom
sam-gutentag/mergify-migration
Draft

Add Migrate from Mergify page#50
samgutentag wants to merge 3 commits into
mainfrom
sam-gutentag/mergify-migration

Conversation

@samgutentag
Copy link
Copy Markdown
Member

@samgutentag samgutentag commented May 20, 2026

Summary

  • New top-level Merge Queue page: merge-queue/migrating-from-mergify.mdx (sibling to migrating-from-github-merge-queue)
  • Covers the admission-vs-testing mental shift, Mergify→Trunk construct mapping (queue_rules, OR-clause status checks, priority_rules, per-rule conditional testing), observability surface, and a 6-step migration sequence
  • One-line docs.json nav entry added next to the existing GH MQ migration page

Why

Sourced from customer feedback mining (cluster mergify-migration-in-flight, verified as missing — no Mergify migration page existed). Content drawn from real Q&A in trunk-anchor's active POC: Phil's Slack thread covered the rulesets-driven admission, the OR-clause aggregator workaround, and the observability story in enough detail to lift directly into the page. The conditional-status-check ergonomic gap is acknowledged upfront rather than buried.

@samgutentag samgutentag added the needs review PR sourced from customer-feedback-mining; needs human scrutiny for accuracy before merge label May 20, 2026
@mintlify
Copy link
Copy Markdown
Contributor

mintlify Bot commented May 20, 2026 •
edited
Loading

Preview deployment for your docs. Learn more about Mintlify Previews.

Project Status Preview Updated (UTC)
trunk 🟢 Ready View Preview May 20, 2026, 11:03 PM

💡 Tip: Enable Workflows to automatically generate PRs for you.

@samgutentag
Copy link
Copy Markdown
Member Author

samgutentag commented May 26, 2026 •
edited
Loading

Verification status (2026-05-29): unknown

Could not determine rollout state from available signals. Chaining to verify-docs-against-code for content-accuracy check.

  • Flag state: LaunchDarkly not consulted per flag (no eng PR, no flag to read). LD MCP was reachable this sweep.
  • Eng PR: none referenced in PR body
  • Flag: n/a (no eng work to verify)
  • Signals checked:
    • No trunk-io/<repo>#NNN or PR URL references in PR body
    • No TRUNK-XXX Linear ticket linked
    • PR scope is content (Mergify migration guide), not a flag-gated new feature

This is a content-accuracy PR. The code-verification comment found a contradicted CLI flag (/trunk merge --high-priority should be --priority=<level>) plus several items needing eng review. Resolve those before merge. No rollout dependency to wait on.

@samgutentag samgutentag marked this pull request as draft May 26, 2026 18:39
@samgutentag
Copy link
Copy Markdown
Member Author

samgutentag commented May 26, 2026

Code verification (2026-05-26)

Verified factual claims in the Mergify migration guide against trunk-io/trunk2 source code.

Claims checked:

  • ✅ required_statuses in trunk.yaml as a flat list — confirmed in proto (merge_instance.proto: repeated string required_statuses = 21), Terraform provider, Prisma schema, and frontend settings
  • ✅ setImpactedTargets API endpoint — confirmed in openapi.json as POST /setImpactedTargets, and impacted_targets field in proto (merge_graph.proto), ClickHouse schema
  • ✅ status.trunk.io public status page — confirmed in frontend (merge-graph-maintenance-banner.tsx links to https://status.trunk.io/...)
  • ✅ Prometheus-style metrics endpoint — confirmed via ts/packages/merge-metrics/ package and ts/apps/merge-metrics-prototype-server/ (currently prototype stage, exposes Prometheus format)
  • ❌ /trunk merge --high-priority CLI flag — docs say --high-priority, but the actual flag is --priority=<level> (e.g., --priority=high, --priority=urgent). See merge-queue/optimizations/priority-merging.mdx for the correct syntax.
  • ⚠️ "Label-driven priority via the submit Pull Request endpoint with a priority field" — the submit endpoint exists but the specific "priority field" on the submit API could not be located in the proto (messages.proto SubmitPullRequestRequest does not show a priority field in the search results). May be set via a different mechanism.
  • ⚠️ "AND semantics" for required_statuses — the field is repeated string in proto (a list), which is consistent with AND semantics, but the explicit AND behavior is architectural, not directly expressed in code as a named concept.
  • ⚠️ Aggregator action pattern for OR-clauses — this is a recommended workaround, not a Trunk feature. Unverifiable against code, but conceptually sound.

Verdict: needs eng review

The --high-priority flag reference is incorrect. The actual CLI syntax is /trunk merge --priority=<level> or -p <level>. This should be corrected before merge.

@samgutentag samgutentag added the needs eng review verify-docs-against-code: at least one claim contradicts source. label May 26, 2026
samgutentag and others added 3 commits May 26, 2026 11:58
@samgutentag @claude
docs(merge-queue): add Migrate from Mergify page
acdbcfb 
Net-new page mapping Mergify constructs to Trunk equivalents:
queue_rules + GH rulesets, required_status OR-clauses + aggregator
actions, priority_rules + label-driven submit API, and per-rule
conditional testing + impacted_targets API.

Sourced from clustered customer Q&A (cluster_id mergify-migration-in-flight,
verdict missing, 2 pairs from trunk-anchor active POC). Page sits as a
top-level MQ sibling to migrating-from-github-merge-queue, matching the
existing flat structure.

Acknowledges the conditional-status-check ergonomic gap upfront rather
than burying it — Phil's Slack thread to the trunk-anchor team was honest
about the tradeoff, so the docs should be too.

Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>
@samgutentag @claude
docs(merge-queue): apply review fixes to mergify migration page
e9b0173 
Remove the bogus comparison Tip link (placeholder URL) and tighten the
Getting help section to match the sibling migrating-from-github-merge-queue
page's support email pattern.

Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>
@samgutentag @claude
docs(merge-queue): restructure mergify migration to action-first
77a6879 
Move the migration sequence to be the first section after the intro.
Dissolve the "mental shift" section into a single sentence in the intro
so the admission-vs-testing split lands before step 1 without a separate
preamble section. Mapping Mergify constructs and Observability move below
the sequence as reference appendices.

Drop the optional "run both in parallel" step. Phil's actual advice in
the trunk-anchor thread was straight cutover (turn off Mergify rules,
configure GitHub rulesets, enable Trunk) — no parallel-running recommended.
The sibling GH MQ migration page's parallel-run pattern works because
GH MQ activates per branch protection setting, but Mergify and Trunk
would both target the same PRs and conflict. Replaced with an Info
callout: configure a repo to use only one merge queue tool at a time.

Also tighten step 4 (Turn off Mergify): say "uninstall the Mergify
GitHub App and remove or comment out .mergify.yml" rather than the
vaguer "disable the Mergify app."

Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>
@samgutentag samgutentag force-pushed the sam-gutentag/mergify-migration branch from 1857a34 to 77a6879 Compare May 26, 2026 18:58
@samgutentag Claude
Copy link
Copy Markdown
Member Author

samgutentag commented May 31, 2026

Verification status (May 31, 2026): unknown

Migrate-from-Mergify guide, but internal content contradictions prevent confident auto-verification.

  • Flag state: not consulted
  • Eng PR: none found
  • Flag: none
  • Signals: migration guide content appears editorial, but review flagged contradictions requiring human check before publish

Next action: author or reviewer to resolve content contradictions and confirm accuracy, then merge.

Generated by Claude Code

@samgutentag Claude
Copy link
Copy Markdown
Member Author

samgutentag commented Jun 1, 2026

Docs Verify Sweep · June 1, 2026 · ❓ unknown

Could not determine feature status — no linked eng PR or feature flag found, or signals were unclear. Manual review required.

Unchanged from previous sweep (May 31, 2026).

Generated by Claude Code

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Reviewers

No reviews

Assignees

No one assigned

Labels

needs eng review verify-docs-against-code: at least one claim contradicts source. needs review PR sourced from customer-feedback-mining; needs human scrutiny for accuracy before merge

Milestone

No milestone

Development

Successfully merging this pull request may close these issues.

1 participant

@samgutentag