---
title: OIDC Trust Policies from the CLI
description: Write the OIDC trust policies of your organization and read its ID token exchanges with the mergify oidc commands of the Mergify CLI.
---

> **Preview:** This feature is in Preview: every organization can use it, and it may change before it is generally available.

The `mergify oidc` commands of the [Mergify CLI](/cli/usage), on its latest release, write the
trust policies and read the exchanges of [OIDC Authentication](/integrations/gha/oidc) 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](/security#delegated-roles), or set `MERGIFY_TOKEN` to an `admin`
[application key](/api/usage#application-key-scopes). 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

`list` prints each policy line by line:

```bash
mergify oidc trust-policies list
```

```text
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**](/integrations/gha/oidc#write-a-trust-policy). 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`:

```bash
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:

```bash
mergify oidc exchanges list --policy 0b6f3c2e-5f1d-4c7a-9e2b-8d4a1f0c3e57
```

```text
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:

```bash
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:

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

## Read the exchanges

`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:

```bash
mergify oidc exchanges list --result refused
```

```text
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](/integrations/gha/oidc#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](/cli) lists every flag.
