merge queue: checking #12694 on main (a49aada), stacked on #12695 and #12687

src/content/docs/api/usage.mdx

@@ -84,8 +84,7 @@ The `scope` field tells you which of the two scopes above the key holds.
 As an alternative to application keys, you can authenticate to the Mergify
 API using a **GitHub Personal Access Token (PAT)** as a Bearer
 token. This is useful when integrating with tools that already have a
-GitHub token available, such as CI environments or
-the [Mergify CLI](/cli/usage).
+GitHub token available, such as CI environments.
 
 You must have logged in to
 the [Mergify dashboard](https://dashboard.mergify.com) at least

src/content/docs/cli/agents.mdx

@@ -49,7 +49,7 @@ of them is useful:
    `brew install mergifyio/tap/mergify-cli`. For Linux, Windows, and CI
    runners, see the [CLI installation guide](/cli/usage).
 
-2. A token is available to it. See [Authentication](#authentication) below.
+2. It is authenticated. See [Authentication](#authentication) below.
 
 These skills only work in a terminal agent that can run the binary, such as
 Claude Code, Codex, or Cursor. A browser-only chat cannot run it, so the skills
@@ -88,28 +88,49 @@ Check the result with `npx skills list`.
 
 ## Authentication
 
-The CLI resolves a token in this order: the `--token` option on the command,
-then `MERGIFY_TOKEN`, then `GITHUB_TOKEN`. Stacks commands fall back once more
-to `gh auth token`. Set an environment variable rather than passing `--token`,
-so the agent does not have to put a secret on a command line:
+Most of what the skills do goes through the Mergify API. Sign in once and every
+skill inherits the credential:
 
 ```bash
-export MERGIFY_TOKEN=your_token_here
+mergify auth login
 ```
 
-Which token to use depends on what you want the agent to do.
+That stores a [Mergify user token](/api/usage#using-a-mergify-user-token)
+outside the agent's reach, so no secret has to go on a command line or into the
+project. Where the operating system has no credential store, which is the usual
+case in a container, the CLI writes a restricted file in your configuration
+directory instead. See [Authentication](/cli/usage#authentication) for both
+paths.
+
+Stacks is the exception. It creates and updates pull requests through the GitHub
+API, so it needs a GitHub token of its own. Install the
+[GitHub CLI](https://cli.github.com/), run `gh auth login`, and Stacks commands
+pick up its token on their own.
+
+:::caution
+  Letting the CLI authenticate to the Mergify API with a GitHub token is
+  deprecated. `GITHUB_TOKEN` and the `gh auth token` fallback still work, and
+  the CLI warns when it uses one, but run `mergify auth login` instead. Stacks
+  is unaffected: it needs a GitHub token either way.
+:::
+
+**A Mergify application key** is the alternative when the agent runs unattended
+and cannot complete an interactive sign-in. Create one from your
+[dashboard](https://dashboard.mergify.com) and export it, so the agent does not
+have to put a secret on a command line:
+
+```bash
+export MERGIFY_TOKEN=your_token_here
+```
 
-**A GitHub token** covers everything except CI result uploads and setting
-[Merge Queue Scopes](/merge-queue/scopes), which need a `ci` application key.
-Stacks needs one specifically, because it creates and updates pull requests
-through the GitHub API, and the Mergify API accepts a GitHub personal access
-token too. If you already have the [GitHub CLI](https://cli.github.com/)
-installed and authenticated, Stacks commands pick up its token on their own and
-you can skip this.
+An `admin` key covers queue status, the Activity Log, and freezes; CI Insights
+uploads and Merge Queue Scopes need a `ci` key instead. No single key covers
+both, so pick the one that matches what you want the agent to do.
 
-**A Mergify application key** covers the commands that call the Mergify API:
-queue status, Activity Log, freezes, and CI Insights uploads. Create one from
-your [dashboard](https://dashboard.mergify.com). It will not work for Stacks.
+An application key does not work for Stacks. An unattended agent that pushes
+stacks needs a GitHub token in `GITHUB_TOKEN`, which is not deprecated: the
+deprecation above is only about using a GitHub token to reach the Mergify
+API.
 
 Application keys come with either the `admin` scope or the `ci` scope, and
 neither is read-only. `admin` covers the API except result uploads and Merge

src/content/docs/cli/usage.mdx

@@ -80,49 +80,121 @@ installed as the `mergify_cli_version` output:
 
 ## Authentication
 
-The CLI needs an authentication token to interact with your repositories.
-Depending on the command, this can be a GitHub token or a Mergify API token.
+The CLI talks to two APIs, and they take different credentials:
 
-Most commands that need one resolve it in the same order: the `--token`
-option, then the `MERGIFY_TOKEN` environment variable, then `GITHUB_TOKEN`.
-Stacks commands fall back once more to `gh auth token`. There is no global
-`--token` on `mergify` itself, so pass it to the subcommand:
+- The **Mergify API** backs `mergify queue`, `mergify events`, `mergify freeze`,
+  `mergify ci`, `mergify tests`, and `mergify config simulate`.
+  (`mergify config validate` needs no credential: it fetches the public schema
+  and checks your file locally.)
+
+- The **GitHub API** backs [Stacks](/stacks), which creates and updates pull
+  requests on GitHub directly.
+
+`mergify auth login` covers the Mergify half. Stacks still needs a GitHub token
+of its own.
+
+### Sign in to Mergify
 
 ```bash
-mergify <command> --token your_token_here
+mergify auth login
 ```
 
-Each command's entry in the [CLI reference](/cli) lists the options it accepts,
-`--token` included.
+The CLI prints a URL and a short code. Open the URL, type the code in, give the
+token a name so you recognize the machine later, and authorize. The CLI picks up
+its credential and stores it. This is an [OAuth 2.0 device authorization
+grant](https://www.rfc-editor.org/rfc/rfc8628), so nothing listens on a local
+port and the browser does not have to be on the same machine. It works over SSH
+and inside containers.
 
-### GitHub token
+What you get is a [Mergify user token](/api/usage#using-a-mergify-user-token).
+It identifies you, reaches exactly what your dashboard session reaches, and is
+never sent to GitHub.
 
-Stacks commands act on pull requests through the GitHub API and need a GitHub
-token specifically. If you have the [GitHub CLI](https://cli.github.com/)
-(`gh`) installed and authenticated, the Mergify CLI uses its token
-automatically. No extra configuration needed.
+The CLI stores it in your operating system's credential store: Keychain on
+macOS, the Secret Service on Linux, Credential Manager on Windows. Where none is
+available, on a headless container for instance, it falls back to a file in
+your configuration directory, restricted to your user. On a container image or
+a shared runner, treat that file as the secret it is.
 
-Otherwise, create a [personal access
-token](https://docs.github.com/en/authentication/keeping-your-account-and-data-secure/managing-your-personal-access-tokens)
-and set it as an environment variable:
+`mergify auth status` reports whether this machine holds a credential:
 
 ```bash
-export GITHUB_TOKEN=your_token_here
+mergify auth status
+```
+
+`mergify auth logout` revokes it on the server, not just on this machine:
+
+```bash
+mergify auth logout
+```
+
+You can also list and revoke your tokens under **Settings > Developer > CLI
+Tokens** in the [dashboard](https://dashboard.mergify.com). That list is
+personal, not per-organization: it shows the same tokens whichever organization
+you have selected. A token lasts a year, and you can hold 20 at a time. At that
+ceiling the approval page refuses the new login and tells you to revoke one, so
+watch the browser rather than the terminal if a sign-in never completes.
+
+#### On-premise installations
+
+All three commands take `--api-url`, and so does every other command that calls
+the Mergify API:
+
+```bash
+mergify auth login --api-url https://mergify.example.com
+```
+
+Credentials are stored per API URL, so one machine can hold a login for the
+hosted service and one for an [on-premise installation](/enterprise) at the same
+time. That also means the URL has to match afterwards. A command that resolves a
+different API URL does not find the credential you stored, and falls through to
+the next source in the list below. Set `MERGIFY_API_URL` once instead of passing
+`--api-url` every time:
+
+```bash
+export MERGIFY_API_URL=https://mergify.example.com
 ```
 
+`mergify auth logout` and `mergify auth status` are per URL too, so signing out
+of one installation leaves the other's credential in place.
+
+### How Mergify API commands find a token
+
+Commands that call the Mergify API resolve a credential in this order:
+
+1. The `--token` option on the command.
+2. The `MERGIFY_TOKEN` environment variable.
+3. The credential stored by `mergify auth login`, for that API URL.
+4. `GITHUB_TOKEN`. Deprecated.
+5. `gh auth token`, from the GitHub CLI. Deprecated.
+
+There is no global `--token` on `mergify` itself, so pass it to the subcommand:
+
+```bash
+mergify <command> --token your_token_here
+```
+
+Each command's entry in the [CLI reference](/cli) lists the options it accepts,
+`--token` included.
+
+The stored credential deliberately outranks `GITHUB_TOKEN`, so a `GITHUB_TOKEN`
+left exported in a shell cannot quietly override the account you signed in as.
+`--token` and `MERGIFY_TOKEN` stay above it, so a CI job that sets either keeps
+working unchanged.
+
 :::caution
-  Stacks commands read `MERGIFY_TOKEN` before `GITHUB_TOKEN`, and a Mergify
-  application key is not a GitHub token. If `MERGIFY_TOKEN` holds an
-  application key, pass `--token` to your Stacks commands, or keep that key
-  out of `MERGIFY_TOKEN`.
+  Letting the CLI authenticate to the Mergify API with a GitHub token is
+  deprecated. Both `GITHUB_TOKEN` and the `gh auth token` fallback still work,
+  and the CLI warns when it uses one. Run `mergify auth login` instead, or set
+  `MERGIFY_TOKEN` to an application key. This says nothing about Stacks, which
+  needs a GitHub token and reads it exactly as before.
 :::
 
-### Mergify token
+### Application keys for CI
 
-Commands that call the Mergify API, such as `mergify queue`, `mergify events`,
-`mergify freeze`, and `mergify ci`, accept a Mergify application key. Create
-one from your [dashboard](https://dashboard.mergify.com) and set it as
-`MERGIFY_TOKEN`:
+`mergify auth login` is interactive, which makes it the wrong tool for a CI job.
+Unattended runs use an application key instead. Create one from your
+[dashboard](https://dashboard.mergify.com) and set it as `MERGIFY_TOKEN`:
 
 ```bash
 export MERGIFY_TOKEN=your_token_here
@@ -131,11 +203,42 @@ export MERGIFY_TOKEN=your_token_here
 An application key carries either the `admin` scope or the `ci` scope, and
 belongs to a GitHub account rather than to a single repository. See
 [Application Key Scopes](/api/usage#application-key-scopes) for what each one
-covers. The Mergify API also accepts a GitHub personal access token, so one
-GitHub token serves most commands. Two exceptions need a `ci` application key.
-`mergify ci junit-process` (and the deprecated `mergify ci junit-upload`) never
-falls back to `GITHUB_TOKEN`. `mergify ci scopes-send` reads `GITHUB_TOKEN`, but
-posts to an endpoint that rejects anything other than a `ci` key.
+covers. `mergify ci junit-process` (and the deprecated `mergify ci junit-upload`)
+and `mergify ci scopes-send` post to endpoints that accept nothing but a `ci`
+key, so those commands need one specifically. A user token from
+`mergify auth login` does not work for them.
+
+### GitHub token for Stacks
+
+Stacks commands act on pull requests through the GitHub API, so they need a
+GitHub token specifically. `mergify auth login` does not cover them, and a
+Mergify application key does not work here either.
+
+They resolve that token on their own, in this order:
+
+1. The `--token` option on the command.
+2. The `MERGIFY_TOKEN` environment variable.
+3. `GITHUB_TOKEN`.
+4. `gh auth token`, from the GitHub CLI.
+
+Nothing here is deprecated: a GitHub token is what the GitHub API takes.
+
+If you have the [GitHub CLI](https://cli.github.com/) (`gh`) installed and
+authenticated, Stacks picks up its token automatically. Nothing else to
+configure. Otherwise, create a [personal access
+token](https://docs.github.com/en/authentication/keeping-your-account-and-data-secure/managing-your-personal-access-tokens)
+and set it as an environment variable:
+
+```bash
+export GITHUB_TOKEN=your_token_here
+```
+
+:::caution
+  Stacks commands read `MERGIFY_TOKEN` before `GITHUB_TOKEN`, and a Mergify
+  application key is not a GitHub token. If `MERGIFY_TOKEN` holds an
+  application key, pass `--token` to your Stacks commands, or keep that key
+  out of `MERGIFY_TOKEN`.
+:::
 
 ## Exit Codes
 

src/content/docs/stacks/setup.mdx

@@ -46,11 +46,22 @@ CI Insights, config validation, and scheduled freezes. See
 ## 3. Configure GitHub
 
 Stacks creates and updates pull requests through the GitHub API, so it needs a
-GitHub token: a Mergify [application key](/api/usage) does not work here. Point
-`MERGIFY_TOKEN` or `GITHUB_TOKEN` at one, or install the
-[GitHub CLI](https://cli.github.com/) and run `gh auth login`. The CLI tries
-them in that order. See [Authentication](/cli/usage#authentication) for where
-each token comes from.
+GitHub token. Neither a Mergify [application key](/api/usage) nor
+`mergify auth login` helps here: those authenticate to the Mergify API, which
+Stacks never calls.
+
+The simplest option is the [GitHub CLI](https://cli.github.com/). Install it,
+run `gh auth login`, and Stacks picks up its token on its own. To manage the
+token yourself instead, export it as `GITHUB_TOKEN`. See
+[GitHub token for Stacks](/cli/usage#github-token-for-stacks) for the order
+Stacks tries them in.
+
+:::caution
+  Stacks reads `MERGIFY_TOKEN` before either of those. If you have set it to a
+  Mergify application key, as the CI Insights and Merge Queue Scopes pages tell
+  you to, Stacks picks that key up and GitHub rejects it. Pass `--token` to your
+  Stacks commands, or keep the application key out of `MERGIFY_TOKEN`.
+:::
 
 Enable "[Automatically delete head branches](https://docs.github.com/en/repositories/configuring-branches-and-merges-in-your-repository/configuring-pull-request-merges/managing-the-automatic-deletion-of-branches)"
 in your GitHub repository settings (Settings > General > Pull Requests). When

src/content/docs/stacks/team.mdx

@@ -33,7 +33,7 @@ A single developer can start using stacks today:
 
 1. [Install the CLI](/cli/usage) locally
 
-2. Give it a [GitHub token](/cli/usage#authentication), or authenticate the
+2. Give it a [GitHub token](/cli/usage#github-token-for-stacks), or authenticate the
    GitHub CLI
 
 3. Run [`mergify stack setup`](/stacks/setup) in their clone

src/pages/cli/index.astro

@@ -51,8 +51,10 @@ const isMuted = (name: string) => MAINTENANCE_GROUPS.has(name);
       <div class="cli-auth-summary">
         <p>
           The Mergify CLI brings the merge queue, stacked pull requests, and CI
-          Insights to your terminal and your pipelines. It reuses your existing
-          <code>gh</code> login, so most commands work the moment it's installed.
+          Insights to your terminal and your pipelines. Run
+          <code>mergify auth login</code> once and most commands work; Stacks
+          additionally needs a GitHub token, from <code>GITHUB_TOKEN</code> or
+          from a <code>gh</code> login if you have one.
         </p>
         <p>
           New to the CLI? <a href="/cli/usage">Install it and set up authentication</a>.