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.
Write policies
Section titled Write policieslist prints each policy line by line:
mergify oidc trust-policies list0b6f3c2e-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 agocreate 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:
mergify oidc trust-policies create --name "Tests of api and web" \ --repository api --repository web \ --workflow .github/workflows/ci.yml-
Repositories:
--repositoryfor only the ones it names,--except-repositoryfor all but those, by name orowner/name;--all-repositories. -
Workflows:
--workflowfor a workflow file of the job’s own repository, such as.github/workflows/ci.yml;--reusable-workflowfor a reusable workflow, such asacme/shared/.github/workflows/test.yml@refs/heads/main, where the@part (a full ref or a commit SHA) is optional;--any-workflow. -
Events:
--eventfor each event, such aspush;--any-event. -
Environments:
--environmentfor each environment, such asproduction;--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:
mergify oidc exchanges list --policy 0b6f3c2e-5f1d-4c7a-9e2b-8d4a1f0c3e57Exchanges 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-8d4a1f0c3e57The 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:
mergify oidc trust-policies update 7d2e9a41-3c8b-4f60-a1d5-2b9e0c7f4a18 \ --workflow .github/workflows/ci.yml --workflow .github/workflows/nightly.ymlThen delete the broad policy:
mergify oidc trust-policies delete 0b6f3c2e-5f1d-4c7a-9e2b-8d4a1f0c3e57mergify oidc trust-policies show <id> prints a policy with who created it and who last edited
it.
Read the exchanges
Section titled Read the exchangesmergify 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:
mergify oidc exchanges list --result refusedExchanges 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 eventsRead 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?
Thanks for your feedback!