OIDC Authentication
Write the trust policies that let CI jobs reach Mergify without a stored key, and read the ID token exchanges.
Learn more: OIDC trust policies from the CLI
mergify oidc trust-policies list #
List the organization's trust policies, line by line
mergify oidc trust-policies list [OPTIONS]
-v, --verbose
flag
Increase log verbosity: -v info, -vv debug, -vvv trace. Logs go to stderr so stdout stays clean for piping. RUST_LOG overrides this
--debug
flag
Shorthand for at least debug-level logging (like -vv)
--color
<COLOR>
auto | always | never
When to use color in terminal output
Values:
auto
always
never
-t, --token
<TOKEN>
string
Mergify token. Falls back to MERGIFY_TOKEN, then the credential mergify auth login stored for this API URL
-u, --api-url
<API_URL>
string
Mergify API URL. Falls back to MERGIFY_API_URL env var, then to the default
--org
<ORG>
string
GitHub organization. Defaults to the owner of the current repository
--json
flag
Emit what Mergify answered as a single JSON document
MERGIFY_API_URL
Base URL of the Mergify API. An API URL given on the command line or in a reporter's configuration takes precedence.
MERGIFY_TOKEN
The Mergify credential: an application key in CI. A GitHub Actions job granted id-token: write needs none: without it, the test reporters, mergify ci junit-process and mergify ci scopes-send exchange the job's ID token for a Mergify token, when a trust policy of the organization allows the job. Without either, the test reporters upload nothing. A mergify command takes it when --token is not given, over the credential mergify auth login stored, and mergify auth tells when it does. The mergify stack commands send it to GitHub as their GitHub token, ahead of GITHUB_TOKEN, unless it holds a Mergify user token (mut_…).
mergify oidc trust-policies show #
Show a trust policy, with who wrote and last edited it
mergify oidc trust-policies show [OPTIONS] <ID>
<ID>
string
required
ID, as list shows it
-v, --verbose
flag
Increase log verbosity: -v info, -vv debug, -vvv trace. Logs go to stderr so stdout stays clean for piping. RUST_LOG overrides this
--debug
flag
Shorthand for at least debug-level logging (like -vv)
--color
<COLOR>
auto | always | never
When to use color in terminal output
Values:
auto
always
never
-t, --token
<TOKEN>
string
Mergify token. Falls back to MERGIFY_TOKEN, then the credential mergify auth login stored for this API URL
-u, --api-url
<API_URL>
string
Mergify API URL. Falls back to MERGIFY_API_URL env var, then to the default
--org
<ORG>
string
GitHub organization. Defaults to the owner of the current repository
--json
flag
Emit what Mergify answered as a single JSON document
MERGIFY_API_URL
Base URL of the Mergify API. An API URL given on the command line or in a reporter's configuration takes precedence.
MERGIFY_TOKEN
The Mergify credential: an application key in CI. A GitHub Actions job granted id-token: write needs none: without it, the test reporters, mergify ci junit-process and mergify ci scopes-send exchange the job's ID token for a Mergify token, when a trust policy of the organization allows the job. Without either, the test reporters upload nothing. A mergify command takes it when --token is not given, over the credential mergify auth login stored, and mergify auth tells when it does. The mergify stack commands send it to GitHub as their GitHub token, ahead of GITHUB_TOKEN, unless it holds a Mergify user token (mut_…).
mergify oidc trust-policies create #
Create a trust policy.
A line no flag names is the default: every repository, any workflow, the CI events and any environment. --name alone therefore trusts every CI job of the organization's repositories.
mergify oidc trust-policies create [OPTIONS] --name <NAME>
--name
<NAME>
string
required
Name of the policy, unique in the organization
-r, --repository
<REPOSITORY>
string
Only jobs of this repository, repeatable: NAME or OWNER/NAME
--except-repository
<REPOSITORY>
string
Jobs of every repository but this one, repeatable
--all-repositories
flag
Jobs of every repository Mergify's GitHub App can access, new ones included
--workflow
<PATH>
string
Only jobs of a run started by this workflow file of their own repository, repeatable: .github/workflows/ci.yml. A reusable workflow the run calls, even one of the same repository, is a --reusable-workflow
--reusable-workflow
<WORKFLOW>
string
Only jobs running this reusable workflow, repeatable: OWNER/REPOSITORY/.github/workflows/FILE.yml, its repository one of the organization's. @REF pins it to a full ref (refs/heads/main, refs/tags/v1) or a commit sha: only a protected ref keeps someone who pushes a branch from editing the workflow that gets the token
--any-workflow
flag
Jobs running any workflow
--event
<EVENT>
string
Only jobs started by this event, repeatable. Replaces the default, the CI events: push, pull_request, merge_group, schedule and workflow_dispatch. pull_request_target, workflow_run and issue_comment run with the repository's identity for people who cannot push to it
--any-event
flag
Jobs started by any event
--environment
<ENVIRONMENT>
string
Only jobs running in this environment, repeatable
--any-environment
flag
Jobs running in any environment, or in none
-v, --verbose
flag
Increase log verbosity: -v info, -vv debug, -vvv trace. Logs go to stderr so stdout stays clean for piping. RUST_LOG overrides this
--debug
flag
Shorthand for at least debug-level logging (like -vv)
--color
<COLOR>
auto | always | never
When to use color in terminal output
Values:
auto
always
never
-t, --token
<TOKEN>
string
Mergify token. Falls back to MERGIFY_TOKEN, then the credential mergify auth login stored for this API URL
-u, --api-url
<API_URL>
string
Mergify API URL. Falls back to MERGIFY_API_URL env var, then to the default
--org
<ORG>
string
GitHub organization. Defaults to the owner of the current repository
--json
flag
Emit what Mergify answered as a single JSON document
MERGIFY_API_URL
Base URL of the Mergify API. An API URL given on the command line or in a reporter's configuration takes precedence.
MERGIFY_TOKEN
The Mergify credential: an application key in CI. A GitHub Actions job granted id-token: write needs none: without it, the test reporters, mergify ci junit-process and mergify ci scopes-send exchange the job's ID token for a Mergify token, when a trust policy of the organization allows the job. Without either, the test reporters upload nothing. A mergify command takes it when --token is not given, over the credential mergify auth login stored, and mergify auth tells when it does. The mergify stack commands send it to GitHub as their GitHub token, ahead of GITHUB_TOKEN, unless it holds a Mergify user token (mut_…).
mergify oidc trust-policies update #
Change the lines of a trust policy. Only the lines the flags name change; the others keep their values. A line's flags replace its values, they do not add to them.
mergify oidc trust-policies update [OPTIONS] <ID>
<ID>
string
required
ID of the policy, as list shows it
--name
<NAME>
string
New name of the policy
-r, --repository
<REPOSITORY>
string
Only jobs of this repository, repeatable: NAME or OWNER/NAME
--except-repository
<REPOSITORY>
string
Jobs of every repository but this one, repeatable
--all-repositories
flag
Jobs of every repository Mergify's GitHub App can access, new ones included
--workflow
<PATH>
string
Only jobs of a run started by this workflow file of their own repository, repeatable: .github/workflows/ci.yml. A reusable workflow the run calls, even one of the same repository, is a --reusable-workflow
--reusable-workflow
<WORKFLOW>
string
Only jobs running this reusable workflow, repeatable: OWNER/REPOSITORY/.github/workflows/FILE.yml, its repository one of the organization's. @REF pins it to a full ref (refs/heads/main, refs/tags/v1) or a commit sha: only a protected ref keeps someone who pushes a branch from editing the workflow that gets the token
--any-workflow
flag
Jobs running any workflow
--event
<EVENT>
string
Only jobs started by this event, repeatable. Replaces the default, the CI events: push, pull_request, merge_group, schedule and workflow_dispatch. pull_request_target, workflow_run and issue_comment run with the repository's identity for people who cannot push to it
--any-event
flag
Jobs started by any event
--environment
<ENVIRONMENT>
string
Only jobs running in this environment, repeatable
--any-environment
flag
Jobs running in any environment, or in none
-v, --verbose
flag
Increase log verbosity: -v info, -vv debug, -vvv trace. Logs go to stderr so stdout stays clean for piping. RUST_LOG overrides this
--debug
flag
Shorthand for at least debug-level logging (like -vv)
--color
<COLOR>
auto | always | never
When to use color in terminal output
Values:
auto
always
never
-t, --token
<TOKEN>
string
Mergify token. Falls back to MERGIFY_TOKEN, then the credential mergify auth login stored for this API URL
-u, --api-url
<API_URL>
string
Mergify API URL. Falls back to MERGIFY_API_URL env var, then to the default
--org
<ORG>
string
GitHub organization. Defaults to the owner of the current repository
--json
flag
Emit what Mergify answered as a single JSON document
MERGIFY_API_URL
Base URL of the Mergify API. An API URL given on the command line or in a reporter's configuration takes precedence.
MERGIFY_TOKEN
The Mergify credential: an application key in CI. A GitHub Actions job granted id-token: write needs none: without it, the test reporters, mergify ci junit-process and mergify ci scopes-send exchange the job's ID token for a Mergify token, when a trust policy of the organization allows the job. Without either, the test reporters upload nothing. A mergify command takes it when --token is not given, over the credential mergify auth login stored, and mergify auth tells when it does. The mergify stack commands send it to GitHub as their GitHub token, ahead of GITHUB_TOKEN, unless it holds a Mergify user token (mut_…).
mergify oidc trust-policies delete #
Delete a trust policy. The jobs only it allowed get no token from then on, and the tokens already given expire within the hour.
mergify oidc trust-policies delete [OPTIONS] <ID>
<ID>
string
required
ID, as list shows it
-v, --verbose
flag
Increase log verbosity: -v info, -vv debug, -vvv trace. Logs go to stderr so stdout stays clean for piping. RUST_LOG overrides this
--debug
flag
Shorthand for at least debug-level logging (like -vv)
--color
<COLOR>
auto | always | never
When to use color in terminal output
Values:
auto
always
never
-t, --token
<TOKEN>
string
Mergify token. Falls back to MERGIFY_TOKEN, then the credential mergify auth login stored for this API URL
-u, --api-url
<API_URL>
string
Mergify API URL. Falls back to MERGIFY_API_URL env var, then to the default
--org
<ORG>
string
GitHub organization. Defaults to the owner of the current repository
--json
flag
Emit what Mergify answered as a single JSON document
MERGIFY_API_URL
Base URL of the Mergify API. An API URL given on the command line or in a reporter's configuration takes precedence.
MERGIFY_TOKEN
The Mergify credential: an application key in CI. A GitHub Actions job granted id-token: write needs none: without it, the test reporters, mergify ci junit-process and mergify ci scopes-send exchange the job's ID token for a Mergify token, when a trust policy of the organization allows the job. Without either, the test reporters upload nothing. A mergify command takes it when --token is not given, over the credential mergify auth login stored, and mergify auth tells when it does. The mergify stack commands send it to GitHub as their GitHub token, ahead of GITHUB_TOKEN, unless it holds a Mergify user token (mut_…).
mergify oidc exchanges list #
List the latest exchanges
mergify oidc exchanges list [OPTIONS]
--result
<RESULT>
allowed | refused
Only the exchanges that got a token, or only those refused
Values:
allowed
refused
-r, --repository
<REPOSITORY>
string
Only the exchanges of this repository: NAME or OWNER/NAME
--policy
<ID>
string
Only the exchanges this policy allowed, by its ID as trust-policies list shows it. A refused exchange names instead the line of each policy the job did not match
--since
<DURATION>
string
How far back to look: an integer with a unit, s, m, h, d or w (e.g. 1h, 7d). The report keeps 90 days
--limit
<N>
string
Stop after the latest N exchanges
-v, --verbose
flag
Increase log verbosity: -v info, -vv debug, -vvv trace. Logs go to stderr so stdout stays clean for piping. RUST_LOG overrides this
--debug
flag
Shorthand for at least debug-level logging (like -vv)
--color
<COLOR>
auto | always | never
When to use color in terminal output
Values:
auto
always
never
-t, --token
<TOKEN>
string
Mergify token. Falls back to MERGIFY_TOKEN, then the credential mergify auth login stored for this API URL
-u, --api-url
<API_URL>
string
Mergify API URL. Falls back to MERGIFY_API_URL env var, then to the default
--org
<ORG>
string
GitHub organization. Defaults to the owner of the current repository
--json
flag
Emit what Mergify answered as a single JSON document
MERGIFY_API_URL
Base URL of the Mergify API. An API URL given on the command line or in a reporter's configuration takes precedence.
MERGIFY_TOKEN
The Mergify credential: an application key in CI. A GitHub Actions job granted id-token: write needs none: without it, the test reporters, mergify ci junit-process and mergify ci scopes-send exchange the job's ID token for a Mergify token, when a trust policy of the organization allows the job. Without either, the test reporters upload nothing. A mergify command takes it when --token is not given, over the credential mergify auth login stored, and mergify auth tells when it does. The mergify stack commands send it to GitHub as their GitHub token, ahead of GITHUB_TOKEN, unless it holds a Mergify user token (mut_…).
mergify oidc exchanges show #
Show an exchange, by the ID a refused job's log names
mergify oidc exchanges show [OPTIONS] <ID>
<ID>
string
required
ID, as list shows it
-v, --verbose
flag
Increase log verbosity: -v info, -vv debug, -vvv trace. Logs go to stderr so stdout stays clean for piping. RUST_LOG overrides this
--debug
flag
Shorthand for at least debug-level logging (like -vv)
--color
<COLOR>
auto | always | never
When to use color in terminal output
Values:
auto
always
never
-t, --token
<TOKEN>
string
Mergify token. Falls back to MERGIFY_TOKEN, then the credential mergify auth login stored for this API URL
-u, --api-url
<API_URL>
string
Mergify API URL. Falls back to MERGIFY_API_URL env var, then to the default
--org
<ORG>
string
GitHub organization. Defaults to the owner of the current repository
--json
flag
Emit what Mergify answered as a single JSON document
MERGIFY_API_URL
Base URL of the Mergify API. An API URL given on the command line or in a reporter's configuration takes precedence.
MERGIFY_TOKEN
The Mergify credential: an application key in CI. A GitHub Actions job granted id-token: write needs none: without it, the test reporters, mergify ci junit-process and mergify ci scopes-send exchange the job's ID token for a Mergify token, when a trust policy of the organization allows the job. Without either, the test reporters upload nothing. A mergify command takes it when --token is not given, over the credential mergify auth login stored, and mergify auth tells when it does. The mergify stack commands send it to GitHub as their GitHub token, ahead of GITHUB_TOKEN, unless it holds a Mergify user token (mut_…).
Was this page helpful?
Thanks for your feedback!