View as Markdown

OIDC Trust Policies from the CLI

Write the OIDC trust policies of your organization and read its ID token exchanges with the mergify oidc commands of the Mergify CLI.


The mergify oidc commands of the Mergify CLI, on its latest release, write the trust policies and read the exchanges of OIDC Authentication as the dashboard does, from a script or a coding agent as well as from your terminal.

Sign in with mergify auth login as a GitHub organization Owner or a user holding the CI Admin delegated role, or set MERGIFY_TOKEN to an admin application key. A MERGIFY_TOKEN that is set wins over the login, and a ci key or a token from an ID token in it gets the commands refused.

The commands act on the owner of the current repository, which they read from GITHUB_REPOSITORY when it is set, as in a GitHub Actions job, and from the origin remote otherwise. Pass --org to name the organization instead, as in a checkout of a fork.

list prints each policy line by line:

Terminal windowbash
mergify oidc trust-policies list
0b6f3c2e-5f1d-4c7a-9e2b-8d4a1f0c3e57 CI on every repository
repositories every repository
workflows any workflow
events push, pull_request, merge_group, schedule, workflow_dispatch
environments any environment, or none
last used 40m ago

create takes the policy’s name and a flag for each value of a line. A line that no flag names keeps its default, so --name alone creates a policy with the lines of Trust CI on Every Repository. This command creates a narrower policy, which allows the ci.yml workflow of two repositories on the CI events, and prints it with its ID, 7d2e9a41-3c8b-4f60-a1d5-2b9e0c7f4a18:

Terminal windowbash
mergify oidc trust-policies create --name "Tests of api and web" \
--repository api --repository web \
--workflow .github/workflows/ci.yml
  • Repositories: --repository for only the ones it names, --except-repository for all but those, by name or owner/name; --all-repositories.

  • Workflows: --workflow for a workflow file of the job’s own repository, such as .github/workflows/ci.yml; --reusable-workflow for a reusable workflow, such as acme/shared/.github/workflows/test.yml@refs/heads/main, where the @ part (a full ref or a commit SHA) is optional; --any-workflow.

  • Events: --event for each event, such as push; --any-event.

  • Environments: --environment for each environment, such as production; --any-environment.

Repeat a flag for each value, as --repository above.

Before you delete the broad policy, CI on every repository, check that the narrower one allows every job the broad one does. Once your workflows have run with both, --policy with the broad policy’s ID lists the exchanges it allowed, and one whose allowed by line lacks the narrower policy’s ID is a job that the deletion would refuse:

Terminal windowbash
mergify oidc exchanges list --policy 0b6f3c2e-5f1d-4c7a-9e2b-8d4a1f0c3e57
Exchanges of acme since 2026-11-10 14:34 UTC, latest first:
✓ 5c8e2f17-9a3d-4b6e-b1f0-7e2d4c9a8b35 acme/api 20m ago
event push on refs/heads/main
workflow acme/api/.github/workflows/ci.yml@refs/heads/main
environment none
allowed by 0b6f3c2e-5f1d-4c7a-9e2b-8d4a1f0c3e57, 7d2e9a41-3c8b-4f60-a1d5-2b9e0c7f4a18
✓ a94d6b20-3e7c-4d18-9f5a-6c1b8e2d0f73 acme/web 7h ago
event schedule on refs/heads/main
workflow acme/web/.github/workflows/nightly.yml@refs/heads/main
environment none
allowed by 0b6f3c2e-5f1d-4c7a-9e2b-8d4a1f0c3e57

The broad policy alone allows the nightly workflow of acme/web. update changes only the lines its flags name, and replaces their values rather than adding to them, so name both workflows:

Terminal windowbash
mergify oidc trust-policies update 7d2e9a41-3c8b-4f60-a1d5-2b9e0c7f4a18 \
--workflow .github/workflows/ci.yml --workflow .github/workflows/nightly.yml

Then delete the broad policy:

Terminal windowbash
mergify oidc trust-policies delete 0b6f3c2e-5f1d-4c7a-9e2b-8d4a1f0c3e57

mergify oidc trust-policies show <id> prints a policy with who created it and who last edited it.

mergify oidc exchanges list prints the latest 20 exchanges of the past week. --result refused keeps the refused ones, --repository those of one repository, --policy those a policy allowed, --since 30d looks further back (up to the 90 days the report keeps), and --limit prints more or fewer. A refused exchange names the line of each policy the job did not match:

Terminal windowbash
mergify oidc exchanges list --result refused
Exchanges of acme since 2026-11-10 14:34 UTC, latest first:
✗ e3a1c9d2-6b4f-4f0e-8a7c-1d5b2e9f0a46 acme/web 5m ago
event pull_request_target on refs/heads/main
workflow acme/web/.github/workflows/label.yml@refs/heads/main
environment none
refused no trust policy matches the job
policy 7d2e9a41-3c8b-4f60-a1d5-2b9e0c7f4a18 events: pull_request_target is not one of its events

Read Trust policies before you add pull_request_target to a policy.

When no trust policy matches a job, the job’s log names its exchange, and mergify oidc exchanges show <id> prints that exchange with the job’s run and attempt.

Every command takes --json to print its result as one JSON document, for a script or an agent to read. The CLI reference lists every flag.

Was this page helpful?