GitLab CI Integration

If your project builds with pure build in GitLab CI, you don’t need a stored API key at all. GitLab mints a short-lived, per-job id_token that Pure can verify directly — connect it once on the dashboard, and every pipeline run on the branch you connected authenticates on its own.

This is the same OIDC mechanism pure login itself uses for this project’s own CI, described in full in Authentication → OIDC. This page is the setup walkthrough; that page is the protocol reference.

Why OIDC instead of an API key

• No secret to store. No PURE_API_KEY CI/CD variable to create, mark masked/protected, or rotate — nothing to leak if a job log or a fork’s merge request exposes CI variables.
• Scoped to a branch, automatically. GitLab only issues an id_token with ref_protected: true for a protected branch or tag — an unprotected branch (e.g. an arbitrary merge request from a fork) can never authenticate as your connected project, even if someone reads the pipeline’s own YAML.
• Revocable from the dashboard, same as a key — no need to touch GitLab’s CI/CD settings to cut off access.

A connection belongs to you, not your org

Pure doesn’t verify that you actually control the GitLab project you connect — the same way an AWS IAM role trust policy doesn’t require the trusted account to prove anything to the trusting one. So more than one person, in your org or a different one, can independently connect the exact same GitLab project/branch, each billing to whichever org they choose. To make that unambiguous, a connection is identified by two IDs, both shown on its row on the Integrations page once you create it:

• Account ID — your Pure user id. Identifies which connection (yours, specifically) a pipeline should authenticate against.
• Org ID — the org that connection bills to. Pure cross-checks this against the connection’s own org and rejects a mismatch, so a typo here fails loudly instead of silently billing the wrong org.

Both travel alongside the id_token in every request — neither is a secret, so it’s fine to write them directly into .gitlab-ci.yml.

1. Protect the branch in GitLab

Pure only accepts an id_token whose ref_protected claim is true. If the branch you want CI to build from (commonly main) isn’t already protected:

GitLab → your project → Settings → Repository → Protected branches → add it.

2. Connect the project on the dashboard

1. Open the dashboard and go to Integrations.
2. Under GitLab, click Connect a project.
3. Enter the project path exactly as it appears in GitLab (e.g. my-group/my-project) and the protected branch from step 1.
4. Save.
5. Copy the Account ID and Org ID shown on the new row — you’ll need both in the next step.

You can connect the same project/branch again later (e.g. to bill a different org) — the only thing rejected is you connecting the exact same project/branch twice; revoke the existing one first if that’s what you meant to do.

3. Request an id_token in .gitlab-ci.yml

Add an id_tokens block to the job that runs pure build, with aud set to https://api.pure.dev, and pass it via --oidc-token (or the PURE_OIDC_TOKEN environment variable) along with --account/--org (or PURE_ACCOUNT_ID/PURE_ORG_ID) from step 2:

compile:
  id_tokens:
    PURE_ID_TOKEN:
      aud: https://api.pure.dev
  script:
    - curl -fsSL https://apt.pure.dev/install.sh | sh
    - pure build src/main.ts \
        --oidc-token "$PURE_ID_TOKEN" \
        --account <your-account-id> --org <your-org-id>

No pure login, no PURE_API_KEY to configure. The job authenticates as long as it runs on the branch you connected in step 2, using the account and org you named.

Troubleshooting

| Error code | Fix | |---|---| | MISSING_ACCOUNT | --account and/or --org (or their env var equivalents) weren’t set — see step 3. | | REF_NOT_PROTECTED | The branch/tag this job ran on isn’t protected in GitLab yet — see step 1. | | NOT_CONNECTED | No connection made by --account’s user matches this project path + branch — see step 2. Check for typos in the project path and the account ID. | | CREDENTIAL_REVOKED | The connection was revoked from the dashboard. Reconnect it on the Integrations page if this was unintentional. | | ORG_MISMATCH | The connection matching --account bills to a different org than --org claimed — check the org ID shown on that connection’s row. | | INVALID_TOKEN | The token failed verification — usually means aud in .gitlab-ci.yml doesn’t exactly match https://api.pure.dev, or the job didn’t actually request PURE_ID_TOKEN under id_tokens. |

See the full error reference in Authentication → auth.error message.