GitLab Pipelines

Overview

This page covers how to check out Britive profiles from within GitLab CI/CD pipelines so that jobs receive short-lived cloud credentials at runtime instead of relying on long-lived secrets stored as GitLab CI variables.

The two supported methods are:

Method	When to Use
Britive CLI (PyBritive)	Standard approach for most pipelines — shell-based `script` blocks, `before_script`, reusable `.gitlab-ci.yml` includes
REST API	When calling from a custom Docker image entrypoint or a non-shell runtime — see the Britive API documentation

Prerequisites

Requirement	Details
Britive service identity	Create a service identity in the Britive console; generate a token
Britive profile	The profile must be active, have an expiration set, and have a policy granting the service identity access
GitLab CI/CD variables	Store `BRITIVE_API_TOKEN` and `BRITIVE_TENANT` as masked, protected CI/CD variables at the project or group level
Britive CLI (if using CLI method)	Install PyBritive in the pipeline runner or add an install step to `before_script`

Environment Variables

Variable	Required	Where to Set	Description
`BRITIVE_API_TOKEN`	Yes	GitLab CI/CD variable (masked, protected)	Service identity token — PyBritive reads this automatically
`BRITIVE_TENANT`	Yes	GitLab CI/CD variable	Britive tenant subdomain (see Finding Your Tenant Name)
`BRITIVE_PROFILE`	No	`.gitlab-ci.yml` `variables` block	Profile to check out, as `Application/Environment/Profile`

CLI Usage

Installing the CLI

Add an install step in before_script or bake PyBritive into your runner image:

.gitlab-ci.yml

before_script:
  - pip install pybritive==2.3.2   # pin to your tested version

Checkout Step

pybritive checkout with -m env-nix prints export statements; eval them, then use the credentials in the same job:

.gitlab-ci.yml

deploy:
  variables:
    BRITIVE_PROFILE: "AWS Production/Prod Account/ci-deploy"
  script:
    - eval "$(pybritive checkout "$BRITIVE_PROFILE" -m env-nix)"
    - aws sts get-caller-identity

BRITIVE_API_TOKEN and BRITIVE_TENANT are picked up from the CI/CD variables automatically — no flags needed.

`pybritive checkout` Flags

Flag	Required	Default	Description
`PROFILE` (argument)	Yes	—	Profile as `application name/environment name/profile name`
`-m, --mode`	No	`text`	Output mode: `env-nix` (shell exports), `json`, `integrate` (write AWS credentials file), `awscredentialprocess`, `gcloudauth`, `azlogin`, and more
`-j, --justification`	No	—	Justification string if the profile policy requires one
`-b, --blocktime`	No	3 / 60	Seconds to wait before polling for credentials (60 for approval-gated profiles)
`-a, --alias`	No	—	Save an alias for shorter future checkouts
`--ticket-type` / `--ticket-id`	No	—	ITSM ticket details if the profile requires a ticket

Environment variables set in one script line survive to subsequent lines in the same job, but not to other jobs. Run eval and the commands that use the credentials in the same job, or write to a dotenv artifact to pass them forward.

REST API Usage

When a shell isn’t available (custom Docker entrypoints, non-shell runtimes), call the Britive REST API directly. Authenticate with the service identity token in the Authorization: TOKEN <token> header. See the Britive API documentation for endpoint details.

Credential Injection

After checkout with -m env-nix and eval, credentials are exported into the job’s environment. The variables depend on the target cloud:

Cloud	Credential Variables Injected
AWS	`AWS_ACCESS_KEY_ID`, `AWS_SECRET_ACCESS_KEY`, `AWS_SESSION_TOKEN`
GCP	`GOOGLE_APPLICATION_CREDENTIALS`
Azure	`AZURE_CLIENT_ID`, `AZURE_CLIENT_SECRET`, `AZURE_TENANT_ID`
Snowflake	`SNOWFLAKE_USER`, `SNOWFLAKE_PASSWORD`, `SNOWFLAKE_ACCOUNT`

Security Considerations

Practice	Why It Matters
Mark `BRITIVE_API_TOKEN` as masked	Prevents the token from appearing in job logs
Mark `BRITIVE_API_TOKEN` as protected	Restricts the variable to protected branches and tags only
Use group-level variables sparingly	Prefer project-level variables to limit blast radius
Match checkout duration to job runtime	Short-lived credentials reduce exposure if a job is compromised

Last updated on July 8, 2026