OIDC Authentication

Write the trust policies that let CI jobs reach Mergify without a stored key, and read the ID token exchanges.


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

Default: auto

-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.

Default: https://api.mergify.com

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

Default: auto

-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.

Default: https://api.mergify.com

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

Default: auto

-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.

Default: https://api.mergify.com

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

Default: auto

-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.

Default: https://api.mergify.com

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

Default: auto

-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.

Default: https://api.mergify.com

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

Default: 7d

--limit <N> string

Stop after the latest N exchanges

Default: 20

-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

Default: auto

-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.

Default: https://api.mergify.com

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

Default: auto

-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.

Default: https://api.mergify.com

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?