Trusted publishers

TL;DR

1. Add the trusted publisher

1. In the portal, open the organisation and choose Keys and CI. The address /orgs/<handle>/ci opens it too.
2. Under Trusted publishers, choose Add trusted publisher.
3. Fill in the repository, such as acme/platform, and the workflow file name, such as diagrams.yml. The file name is the one in .github/workflows, with no folder.
4. Optionally name a deployment environment (only jobs that run in it may sign in) and a branch (main, or a ref pattern such as refs/tags/v*). Leave them blank for any.
5. Choose what its runs can do, and give it a name you will recognise in the usage, the call history and the audit log.

Plotwork asks GitHub for the ids of the repository and its owner when you save. A private repository's id is not public, so it is pinned by the first run instead, and the entry says so until then.

2. Use it in the workflow

Choose Workflow beside the entry to copy a file made for it. It looks like this:

1name: diagrams2
3on:4  pull_request:5  push:6    branches: [main]7
8permissions:9  contents: read10  id-token: write11
12jobs:13  diagrams:14    runs-on: ubuntu-latest15    steps:16      - uses: actions/checkout@v717        with:18          persist-credentials: false19      - uses: plotwork-official/plotwork-action@86ae8278fa771a422d9df60185182f14b8be4db9 # v1.1.020        with:21          command: generate22          mode: check23          report-drift: true

There is no env: and no secret. When the Action needs the API and finds no PLOTWORK_API_KEY, it asks GitHub for a token with the API's address as the audience, swaps it, and goes on. A key in PLOTWORK_API_KEY still works, and wins when both are there.

From the release after v1.2.0-beta.1, the output signed-in-as holds the organisation and publisher the run signed in as, such as {"organization":"acme","publisher":"Platform CI"}, and is empty when the run used a key or did not sign in. drift-url holds the Drift tab the run was sent to. A later step can check either.

Signing in by itself needs a release of the Action newer than v1.1.0. With v1.1.0, add this step before the Action's, and it passes the Plotwork token on as PLOTWORK_API_KEY:

1      - name: Sign in to Plotwork as a trusted publisher2        run: |3          id_token=$(curl -sS -H "Authorization: bearer $ACTIONS_ID_TOKEN_REQUEST_TOKEN" "$ACTIONS_ID_TOKEN_REQUEST_URL&audience=https://api.plotwork.dev" | jq -r .value)4          echo "::add-mask::$id_token"5          token=$(curl -sS -X POST https://api.plotwork.dev/oidc/token -H 'content-type: application/json' -d "{\"token\":\"$id_token\"}" | jq -r .token)6          echo "::add-mask::$token"7          echo "PLOTWORK_API_KEY=$token" >> "$GITHUB_ENV"

3. What a run can do

A run counts as the trusted publisher everywhere: its calls spend the owner's daily allowance and show in the usage and the call history under its name, a diagram it publishes names it as the publisher, and every policy of the organisation applies, including the networks keys may come from, the daily limits, secret scanning, classification and approval.

4. What is checked

Each token is checked against GitHub's published signing keys, and refused unless all of this holds:

The organisation's audit log records each sign-in as orgs.trusted_publisher.exchange, and a refused one as orgs.trusted_publisher.refused with the reason, at most once an hour for each entry.

5. Troubleshooting

See also