An evl_ token in GitHub Actions secrets is a long-lived credential sitting in someone else's database, readable by anyone who can change a workflow, and valid until someone remembers to rotate it. That is the arrangement enveil exists to replace.
Instead, register a trust policy. GitHub mints an OIDC token for every run that says which repository, branch and workflow it is. The CLI trades that token for a machine identity that expires in minutes. Nothing durable is stored on the CI side.
Register a trust policy
In the dashboard, open Identities and expand CI federation. Registering a policy needs the admin or owner role: it is a standing grant to whoever controls the matching workflow.
| Field | Value |
|---|---|
| Issuer | https://token.actions.githubusercontent.com (prefilled). Must be https. |
| Subject | Which workflows are trusted, from the token's sub claim. See below. |
| Audience | The server URL, e.g. https://enveil.oxidt.com. The CLI requests exactly that, without a trailing slash. A token minted for another service carries another audience and is refused. |
| Project, environment | The project the minted identity may use: every environment (the default, current and future ones), or just one, such as prod. An identity scoped to one environment is refused everywhere else. |
| Capability | Proxy only, Read or Read and write. Pick the least the job needs. |
Identities minted from a dashboard policy live 15 minutes.
Subject patterns
GitHub subjects look like repo:acme/api:ref:refs/heads/main, repo:acme/api:environment:production or repo:acme/api:pull_request. A policy accepts one of two forms:
- An exact subject. Only that branch, environment or event.
- A prefix ending in
:*.repo:acme/api:*covers every branch, tag and environment of that one repository.
The wildcard must come right after a :. repo:acme/api* is refused because it would also match repo:acme/api-staging: a different repository, possibly with different people allowed to push to it. A * anywhere else, or a bare * or :*, is refused too. So is a wildcard right after the kind of subject, such as repo:*: it names no owner and would admit every repository on GitHub. The same holds for project_path:*, organization:* and system:serviceaccount:*. A policy registered before this rule matches nothing; the dashboard marks it and says why, so remove it and add a narrower one.
Prefer the narrowest subject that works. repo:acme/api:environment:production together with a GitHub environment's protection rules means only an approved deployment gets production secrets.
Configure the workflow
The job needs two things:
permissions: id-token: write, so GitHub will mint the OIDC token. Without it the CLI finds no credential and exits 2.- The organization whose policies apply:
ENVEIL_ORG, ororgin.enveil.toml.ENVEIL_ORGwins. Only that organization's policies are matched, so another tenant registering a policy for your workflow can neither receive its credentials nor block them.
name: deploy
on:
push:
branches: [main]
permissions:
contents: read
id-token: write # the only credential this job needs
jobs:
deploy:
runs-on: ubuntu-latest
env:
ENVEIL_ORG: acme
steps:
- uses: actions/checkout@v4
- name: Install enveil
run: |
curl --proto '=https' --tlsv1.2 -LsSf \
https://github.com/hauju/enveil/releases/latest/download/enveil-cli-installer.sh | sh
echo "$HOME/.cargo/bin" >> "$GITHUB_PATH"
- run: enveil whoami
- run: enveil run -e prod -- ./deploy.shThis assumes a committed .enveil.toml names the server and project. Without one, pass -p acme-api --server https://enveil.oxidt.com to each command.
enveil whoami is optional, but it prints which identity the run became and what it may do, which is the first thing you want when a step is refused.
What happens on each command
- With no
ENVEIL_TOKENand no keychain login, the CLI seesACTIONS_ID_TOKEN_REQUEST_URLand asks GitHub for an OIDC token with the server URL as audience (ENVEIL_AUDIENCEoverrides it). - It posts the token and the organization to
POST /api/v1/oidc/token. - The server checks the signature against the issuer's published keys, then issuer, audience and expiry, and only then compares the subject with the organization's policies. Each OIDC token can be exchanged once.
- A matching policy mints a short-lived machine identity, named after the subject, with the policy's scope. The CLI uses it for that command and keeps nothing.
Every failure gets the same answer, No trust policy accepts this token., so nobody can probe which workflows an organization trusts. If you see it, check the subject, the audience and ENVEIL_ORG.
Withdrawing trust
Deleting a policy revokes every identity it issued that is still alive. A running job loses access at once, not when its token expires.
Without the CLI
For tooling that cannot run enveil, do the exchange with curl. The policy needs Read or above, since a proxy-only identity cannot export.
- name: Fetch secrets
run: |
ID_TOKEN=$(curl -sSf -G \
-H "Authorization: Bearer $ACTIONS_ID_TOKEN_REQUEST_TOKEN" \
--data-urlencode "audience=https://enveil.oxidt.com" \
"$ACTIONS_ID_TOKEN_REQUEST_URL" | jq -r .value)
ENVEIL_TOKEN=$(jq -n --arg token "$ID_TOKEN" --arg org acme '{token: $token, org: $org}' |
curl -sSf -X POST -H 'content-type: application/json' --data @- \
https://enveil.oxidt.com/api/v1/oidc/token | jq -r .token)
echo "::add-mask::$ENVEIL_TOKEN"
umask 077
curl -sSf -H "Authorization: Bearer $ENVEIL_TOKEN" \
https://enveil.oxidt.com/api/v1/projects/acme-api/environments/prod/export > .envThe exchange answers with token, expires_at and identity (the new identity's id). The export is .env text, one KEY=value per line, and is recorded like any other read. Prefer enveil run where you can: it keeps the values out of files entirely.
Don't fall back to an evl_ token in Actions secrets because an exchange is refused. Compare the policy's subject and audience with what the workflow sends, and check ENVEIL_ORG.