GitLab CI variables from Crunu, bound with id_tokens

What Crunu does in GitLab CI

A job runs your command through crunu run. The crunu agent signs in with a service token, checks signatures, decrypts the variables in 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. With a CI binding (OIDC), GitLab issues the job a token with your Crunu server as its audience, and the Crunu token works only together with it, for the project path, ref and environment you set. crunu reads the GitLab token from CRUNU_ID_TOKEN by itself.

Set it up

1. In Crunu, open Service tokens and choose New service token. Grant the environments the job needs. The token is shown only once.
2. In GitLab, open Settings → CI/CD → Variables and add CRUNU_TOKEN as a masked, protected variable.
3. Add CRUNU_SERVER, CRUNU_VERSION, CRUNU_INSTALL_URL, CRUNU_INSTALL_SHA256 and CRUNU_BINARY_SHA256 with the values from the CI setup block on the token page. In the cloud, CRUNU_SERVER is https://app.crunu.com.
4. Optional: add a CI binding (OIDC) on the token page. Choose the GitLab provider and set project_path, ref, ref_type and, for a production token, environment.

Example job

The job image needs sh and curl or wget. The node, python and alpine images have them.

test:
  image: node:24
  id_tokens:
    CRUNU_ID_TOKEN:
      aud: https://app.crunu.com   # your Crunu server; only if the token has a CI binding (OIDC)
  script:
    - curl -sSf "$CRUNU_INSTALL_URL" -o /tmp/crunu-install.sh
    - echo "$CRUNU_INSTALL_SHA256  /tmp/crunu-install.sh" | sha256sum -c -
    - sh /tmp/crunu-install.sh --version "$CRUNU_VERSION" --sha256 "$CRUNU_BINARY_SHA256" --user-install
    - crunu run --env web-app/staging -- npm test

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

• project_path: kiteline/web-app
• ref: main
• ref_type: branch
• environment: production

The .crunu job templates

The install steps also come as a template file with two hidden jobs. Your jobs inherit them with extends:

• .crunu installs a pinned crunu in before_script, checks the SHA-256 of the installer and of the binary, and prints crunu version;
• .crunu-oidc does the same and adds id_tokens, for tokens with a CI binding.

Keep a copy of the template in your repository, so changes to it are reviewed with your code. If you include it from another GitLab project instead, pin ref to a commit, not a branch.

include:
  - local: ci/crunu.gitlab-ci.yml

test:
  image: node:24
  extends: .crunu
  script:
    - crunu run --env web-app/staging -- npm test

deploy:
  image: node:24
  extends: .crunu-oidc        # the production token has an OIDC rule: project_path, ref, environment
  environment: production
  rules:
    - if: $CI_COMMIT_BRANCH == "main"
  script:
    - crunu run --env web-app/production -- npm run deploy

A job's own before_script replaces the template's, because extends doesn't merge command lists. Add the template's steps back explicitly:

test:
  extends: .crunu
  before_script:
    - !reference [.crunu, before_script]
    - npm ci
  script:
    - crunu run --env web-app/staging -- npm test

What gets checked

• The installer's checksum is compared before it runs. On a mismatch the job stops and crunu isn't installed.
• The installer checks the binary's checksum and runs it once before putting it in place.
• Malformed values, such as a missing checksum or an address that isn't https://, are refused before anything is downloaded.

Runners and checksums

crunu runs on Linux and macOS, on amd64 and arm64. There's no Windows build. The checksum in the CI setup block is for Linux amd64; for arm64 runners, set per-platform checksums from the release's manifest.json.

Revoking

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

Related

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