docs(cli): make mergify auth login the way to authenticate - #12687
Open
sileht wants to merge 1 commit into
Open
Conversation
Contributor
Merge Protections🔴 2 of 6 protections blocking · waiting on 👀 reviews
🔴 👀 Review RequirementsWaiting for
This rule is failing.
🔴 🔎 ReviewsWaiting for
This rule is failing.
Show 4 satisfied protections🟢 🤖 Continuous Integration
🟢 Enforce conventional commitMake sure that we follow https://www.conventionalcommits.org/en/v1.0.0/
🟢 📕 PR description
🟢 🚦 Auto-queueWhen all merge protections are satisfied, this pull request will be queued automatically. |
There was a problem hiding this comment.
🟡 Changes recommended
The updated /cli landing copy is slightly misleading about Stacks requiring a gh login rather than GitHub credentials more generally.
Once you've addressed the issues Copilot identified, you can request another Copilot review.
Pull request overview
This PR updates the Mergify CLI documentation to make mergify auth login (OAuth device flow + stored Mergify user token) the primary authentication path for Mergify API–backed commands, while explicitly clarifying that Stacks continues to require GitHub API credentials and is unaffected by the deprecation of GitHub-token auth to the Mergify API.
Changes:
- Rewrites CLI authentication docs to document
mergify auth loginas the default, and marksGITHUB_TOKEN/gh auth tokenas deprecated fallbacks for Mergify API calls. - Clarifies Stacks authentication requirements and updates links/anchors to point to a dedicated “GitHub token for Stacks” section.
- Removes the CLI as an example motivation for using a GitHub PAT directly against the Mergify API.
File summaries
| File | Description |
|---|---|
| src/pages/cli/index.astro | Updates /cli landing copy to lead with mergify auth login and mention Stacks’ GitHub auth needs. |
| src/content/docs/stacks/team.mdx | Updates onboarding step link to the new Stacks-specific GitHub token section. |
| src/content/docs/stacks/setup.mdx | Rewrites Stacks GitHub auth guidance and adds a caution about MERGIFY_TOKEN precedence. |
| src/content/docs/cli/usage.mdx | Major rewrite of authentication guidance; adds Mergify-vs-GitHub API split, device flow instructions, and token resolution order. |
| src/content/docs/cli/agents.mdx | Updates agent/skills authentication guidance to prefer mergify auth login and clarify Stacks exceptions. |
| src/content/docs/api/usage.mdx | Removes reference to the CLI as a reason to use a GitHub PAT for direct API calls. |
Review details
- Files reviewed: 6/6 changed files
- Comments generated: 1
- Review effort level: Lite
💡 Add a code-review agent skill or configure MCP servers for context-aware, tailored reviews. Learn more in the docs.
The CLI docs told everyone to hand it a GitHub token: `GITHUB_TOKEN`, or
whatever `gh auth token` returns. That credential is now the deprecated
path for the Mergify API, so every page that led with it was steering new
users onto it.
`mergify auth login` signs in through an OAuth 2.0 device grant and stores
a Mergify-issued user token in the OS credential store. Document it as the
way in, and mark `GITHUB_TOKEN` and the `gh auth token` fallback deprecated
where they back a Mergify API call.
Two things the rewrite is careful not to say. CI does not run an
interactive sign-in, so the application-key guidance stays exactly as it
was, and the `ci` commands still need a `ci` key that a user token will
not replace. And Stacks is a pure GitHub API client: it never calls
api.mergify.com, so a GitHub token is what it needs, `mergify auth login`
does nothing for it, and nothing about it is deprecated. Both pages that
cover Stacks now say so outright, since the old wording ("point
MERGIFY_TOKEN or GITHUB_TOKEN at a GitHub token") invited exactly the
mix-up the page below it warns about. Stacks still reads MERGIFY_TOKEN
first, and a dozen other pages tell readers to put an application key
there, so the setup page keeps that warning rather than dropping it with
the sentence that used to carry it.
cli/agents.mdx is in scope for the same reason as the other two: its
Authentication section opened by recommending a GitHub token, which after
this change would be the docs' loudest pointer at the deprecated path. So
is the `/cli` landing page, which sold the CLI on reusing your `gh` login.
api/usage.mdx loses half a sentence: a PAT is still a fine way to call the
API directly, but it is no longer a reason to reach for the CLI.
Details worth stating exactly, because each one was wrong in a first
draft and checked against the shipped engine and dashboard: the approval
page is a form you type the code into, not one that shows you a code, and
it asks for a token name; the 20-token ceiling is refused in the browser,
so a login that never completes is explained there and not in the
terminal; credentials are keyed by API URL, so an on-premise sign-in only
holds for commands that resolve the same URL; and `mergify config
validate` needs no credential at all, since it fetches the public schema
and checks the file locally.
No changelog entry. Deprecation is not the announcement, removal will be.
Fixes MRGFY-8704
Change-Id: Iab17a20075d1e8a8905a1fc0b04bd3b578c001b0
sileht
force-pushed
the
devs/sileht/mrgfy-8704-docs-auth-login/make-mergify-auth-login-way-authenticate--ab17a200
branch
from
September 4, 2026 15:35
84ce6ee to
c33ad8c
Compare
Member
Author
Revision history
|
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
The CLI docs told everyone to hand it a GitHub token:
GITHUB_TOKEN, orwhatever
gh auth tokenreturns. That credential is now the deprecatedpath for the Mergify API, so every page that led with it was steering new
users onto it.
mergify auth loginsigns in through an OAuth 2.0 device grant and storesa Mergify-issued user token in the OS credential store. Document it as the
way in, and mark
GITHUB_TOKENand thegh auth tokenfallback deprecatedwhere they back a Mergify API call.
Two things the rewrite is careful not to say. CI does not run an
interactive sign-in, so the application-key guidance stays exactly as it
was, and the
cicommands still need acikey that a user token willnot replace. And Stacks is a pure GitHub API client: it never calls
api.mergify.com, so a GitHub token is what it needs,
mergify auth logindoes nothing for it, and nothing about it is deprecated. Both pages that
cover Stacks now say so outright, since the old wording ("point
MERGIFY_TOKEN or GITHUB_TOKEN at a GitHub token") invited exactly the
mix-up the page below it warns about. Stacks still reads MERGIFY_TOKEN
first, and a dozen other pages tell readers to put an application key
there, so the setup page keeps that warning rather than dropping it with
the sentence that used to carry it.
cli/agents.mdx is in scope for the same reason as the other two: its
Authentication section opened by recommending a GitHub token, which after
this change would be the docs' loudest pointer at the deprecated path. So
is the
/clilanding page, which sold the CLI on reusing yourghlogin.api/usage.mdx loses half a sentence: a PAT is still a fine way to call the
API directly, but it is no longer a reason to reach for the CLI.
Details worth stating exactly, because each one was wrong in a first
draft and checked against the shipped engine and dashboard: the approval
page is a form you type the code into, not one that shows you a code, and
it asks for a token name; the 20-token ceiling is refused in the browser,
so a login that never completes is explained there and not in the
terminal; credentials are keyed by API URL, so an on-premise sign-in only
holds for commands that resolve the same URL; and
mergify config validateneeds no credential at all, since it fetches the public schemaand checks the file locally.
No changelog entry. Deprecation is not the announcement, removal will be.
Fixes MRGFY-8704