CI variables, secrets and id_tokens

Forge stores pipeline secrets as encrypted project variables. It can also sign short-lived id_tokens so a job can prove its identity to a cloud provider. This page is for project administrators who manage variables and for developers who use them in .gitlab-ci.yml.

Variables belong to a project. Project administrators create, replace and revoke them.

Add a variable

Open the project’s CI secrets panel and add a variable.

Setting	Meaning
Name and value	A value is 8 to 4096 UTF-8 bytes
Type	An environment variable, or a file that the job receives as a file
Environment scope	`*` for every environment (the default), or the exact name of one environment
Protected	The value is withheld from pipelines on unprotected branches
Masked	The value is replaced with `[REDACTED]` in job logs
Hidden	The panel does not show the value

A project can have 64 active variables, with at most 64 KiB of names and values together. Values are encrypted with AES-256-GCM.

Replacing a value saves a new immutable version, and the older versions stay as history. A replace based on an outdated version is refused as a conflict. Revoking a variable stops its delivery, and a job that already received the old values is cancelled.

Schedules can have their own encrypted variables, as environment variables or files, with the same scopes.

When a job receives variables

Forge delivers variables only to a pipeline that runs the CI configuration committed at the head of the default branch. It also checks the person the pipeline runs as. Other pipelines get no values.

If Forge cannot open the stored values, the job fails with “CI secret encryption is unavailable” instead of running without them. Retry the job once the problem is fixed.

Masking

Masking replaces the exact value in the job log, including when a log chunk ends in the middle of the value. It does not cover transformed values, such as an encoded copy, and it does not cover artifacts.

Scripts, images and runner operators that you trust can still read the values. Bytes that were already delivered to a job cannot be recalled.

Get an id_token in a job

An id_token is a signed JWT that proves which project, branch and environment a job runs for. A cloud provider or a secrets service can trust it, so you do not store a long-lived key.

deploy:
  id_tokens:
    CLOUD_ID_TOKEN:
      aud: https://cloud.example.com
  script:
    - ./deploy.sh   # reads $CLOUD_ID_TOKEN

id_tokens works per job or under default:. A job can have up to 8 tokens, each with one or more audiences.
Forge mints each token for that one execution and delivers it as a masked job variable. The token’s exp is the job timeout plus 5 minutes.
Forge refuses a token with a reserved name, no aud, extra keys, variables or spaces.
The job card lists the id_tokens that the job will receive.

Claims

Claim	Value
`iss`	The issuer that publishes the discovery document
`sub`	`project_path:<project>/<repository>:ref_type:…:ref:…`
`aud`	The audience or audiences you set
`exp`, `iat`, `nbf`, `jti`	Expiry, issue time, not-before time and token id
`ref`, `ref_type`, `ref_protected`, `sha`	The branch or tag, whether it is protected, and the commit
`environment`, `environment_protected`, `deployment_tier`	Only on jobs that deploy to an environment

The token also identifies the project, repository, pipeline, job, execution, runner and user.

Trust Forge in your cloud

Tokens are RS256 JWTs. Your provider reads the issuer from the token’s iss claim, then fetches /.well-known/openid-configuration and the keys from /oauth/discovery/keys on that address. Vault, cloud providers and other OIDC verifiers can use them. In the trust rule, match on aud and on claims such as sub and ref_protected.

Signing key rotation

Orbit rotates the signing key, and project administrators do not manage it. A new key signs from then on. Retired keys stay in the key list for a week, so tokens that were already issued still verify.

Secrets from external providers

The secrets: keyword for external secret providers is not supported. Use an id_token to sign in to such a provider from the job. Group variables do not exist because Orbit has no groups.