CI with GitHub Actions

Give a workflow secrets without storing a token in GitHub

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, or org in .enveil.toml. ENVEIL_ORG wins. Only that organization's policies are matched, so another tenant registering a policy for your workflow can neither receive its credentials nor block them.
yaml
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.sh

This 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

  1. With no ENVEIL_TOKEN and no keychain login, the CLI sees ACTIONS_ID_TOKEN_REQUEST_URL and asks GitHub for an OIDC token with the server URL as audience (ENVEIL_AUDIENCE overrides it).
  2. It posts the token and the organization to POST /api/v1/oidc/token.
  3. 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.
  4. 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.

yaml
- 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 > .env

The 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.