Bitbucket Pipelines

Overview

This page covers how to check out Britive profiles from within Bitbucket Pipelines so that steps receive short-lived cloud credentials at runtime instead of storing long-lived keys as Bitbucket repository variables.

The two supported methods are:

Method	When to Use
Britive CLI (PyBritive)	Standard approach for shell `script` steps and `after-script` cleanup
REST API	When calling from a custom Docker image 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
Bitbucket repository variables	Store `BRITIVE_API_TOKEN` and `BRITIVE_TENANT` as secured repository or workspace variables
Britive CLI (if using CLI method)	Install PyBritive in the pipeline `script` block or use a Docker image that bundles the CLI

Environment Variables

Variable	Required	Where to Set	Description
`BRITIVE_API_TOKEN`	Yes	Bitbucket secured repository variable	Service identity token — PyBritive reads this automatically
`BRITIVE_TENANT`	Yes	Bitbucket repository variable	Britive tenant subdomain (see Finding Your Tenant Name)
`BRITIVE_PROFILE`	No	`bitbucket-pipelines.yml` `variables`	Profile to check out, as `Application/Environment/Profile`

Secured variables in Bitbucket are masked in logs but are still available to all pipeline steps in the repository. Use workspace-level variables only for non-sensitive configuration shared across repositories.

CLI Usage

Installing the CLI

Install PyBritive at the start of the step, or use an image with it pre-installed:

bitbucket-pipelines.yml

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 step:

bitbucket-pipelines.yml

pipelines:
  branches:
    main:
      - step:
          name: Deploy with Britive JIT credentials
          image: python:3.12-slim
          script:
            - pip install pybritive==2.3.2 awscli
            - eval "$(pybritive checkout "AWS Production/Prod Account/ci-deploy" -m env-nix)"
            - aws sts get-caller-identity

BRITIVE_API_TOKEN and BRITIVE_TENANT are picked up from the repository 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 exported in one script line persist to subsequent lines within the same step, but not across steps. Keep the eval and the commands that use the credentials in the same step.

REST API Usage

When calling from a custom Docker image or a non-shell runtime, use 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

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
Use secured variables for `BRITIVE_API_TOKEN`	Masks the token in pipeline logs
Restrict deployment permissions in Bitbucket	Control which users can trigger pipelines that access production profiles
Prefer workspace variables only for non-sensitive config	Keeps blast radius small if a repository is compromised
Don’t echo checked-out credentials	Checked-out values are not covered by Bitbucket’s variable masking

Last updated on July 8, 2026