GitHub Actions secrets with Crunu and OIDC

What Crunu does in GitHub Actions

A workflow step runs your command through crunu run. The crunu agent signs in with a service token, checks the signatures on everything the server sends, decrypts the variables in its own memory and starts the command with them. Nothing is written to disk.

crunu run --env web-app/staging -- npm test

The token gets only the environments you grant it. With a CI binding (OIDC), it also needs a fresh GitHub token for the repository, branch and deployment environment you set, so a leaked CRUNU_TOKEN can't sign in on its own. crunu requests that GitHub token by itself, and the server rejects one that's been used before.

Set it up

1. In Crunu, open Service tokens and choose New service token. Give it a name such as github-actions-web-app, grant web-app / staging and keep the default lease of 30 days. The token stops working if no run uses it for longer than the lease, and every run extends it.
2. The token is shown only once. Store it right away as the repository secret CRUNU_TOKEN.
3. Copy the values from the CI setup block on the token page into repository variables: CRUNU_SERVER, CRUNU_VERSION, CRUNU_INSTALL_URL, CRUNU_INSTALL_SHA256 and CRUNU_BINARY_SHA256. They come from the signed release manifest. In the cloud, CRUNU_SERVER is https://app.crunu.com.
4. Optional: add a CI binding (OIDC) on the token page. Choose the GitHub provider and set repository, ref and, for a production token, environment.

Example workflow

This job installs a pinned crunu, checks the installer's SHA-256 before running it, and runs the tests with staging variables.

jobs:
  test:
    runs-on: ubuntu-latest
    permissions:
      id-token: write     # only if the token has a CI binding (OIDC)
      contents: read
    steps:
      - uses: actions/checkout@v4
      - name: Install crunu
        run: |
          curl -sSf "${{ vars.CRUNU_INSTALL_URL }}" -o /tmp/crunu-install.sh
          echo "${{ vars.CRUNU_INSTALL_SHA256 }}  /tmp/crunu-install.sh" | sha256sum -c -
          sh /tmp/crunu-install.sh --version "${{ vars.CRUNU_VERSION }}" --sha256 "${{ vars.CRUNU_BINARY_SHA256 }}" --user-install
      - name: Tests
        env:
          CRUNU_TOKEN: ${{ secrets.CRUNU_TOKEN }}
          CRUNU_SERVER: ${{ vars.CRUNU_SERVER }}
        run: exec crunu run --env web-app/staging -- npm test

For a production token, the CI binding (OIDC) might require:

• repository: kiteline/web-app
• ref: refs/heads/main
• environment: production

The audience is your Crunu server's address. crunu asks GitHub for a token with that audience, which is why the job needs id-token: write.

The setup-crunu action

The same install steps also come as a small composite action, setup-crunu. It isn't published on GitHub Marketplace. Keep a copy of its two files in .github/actions/setup-crunu/ of your repository, so the code that touches your pipeline's secrets goes through the same review as the rest of your code. If you publish it as a separate repository instead, pin it to a full commit SHA, not a tag.

      - uses: actions/checkout@v4
      - uses: ./.github/actions/setup-crunu
        with:
          version: ${{ vars.CRUNU_VERSION }}
          install-url: ${{ vars.CRUNU_INSTALL_URL }}
          install-sha256: ${{ vars.CRUNU_INSTALL_SHA256 }}
          sha256: ${{ vars.CRUNU_BINARY_SHA256 }}
      - env:
          CRUNU_TOKEN: ${{ secrets.CRUNU_TOKEN }}
          CRUNU_SERVER: ${{ vars.CRUNU_SERVER }}
        run: exec crunu run --env web-app/staging -- npm test

The action doesn't contact the Crunu server. It only installs crunu and adds it to PATH for the next steps.

Keep the token out of reach

• Set CRUNU_TOKEN in the env of the one step that runs crunu. Job-level and workflow-level variables reach every step.
• Start crunu with exec. The step's shell is then replaced by crunu, and the token isn't left in a process your command could read.
• The command under crunu run never receives crunu's own credentials, such as CRUNU_TOKEN or CRUNU_OIDC_TOKEN.

Runners and checksums

crunu runs on Linux and macOS runners, on amd64 and arm64, including self-hosted runners. Windows runners aren't supported. The checksum in the CI setup block is for Linux amd64. For arm64 or macOS runners, set per-platform checksums from the release's manifest.json, for example amd64=… and darwin-arm64=….

Production without CI

The setup Crunu recommends keeps production values out of the pipeline. The production server runs the crunu agent and fetches its own environment, and the workflow only delivers the code and restarts the service. See systemd.

Revoking

Open the token and choose Revoke. Its next sign-in is refused, and a step that's already running finishes with what it received. If the token may have leaked, revoke it, rotate the keys of the environments it was given, and reissue the values inside at their providers.

Related

• CI/CD in Crunu
• GitHub Actions in the docs
• Bind a token with OIDC
• Service tokens