GitHub Actions
Overview
This page covers how to check out Britive profiles from within GitHub Actions workflows so that jobs receive short-lived cloud credentials at runtime instead of using long-lived secrets stored in GitHub.
The two supported methods are:
| Method | When to Use |
|---|---|
| Britive CLI (PyBritive) | Standard approach for most workflows — simple shell steps, matrix jobs, reusable workflows |
| REST API | When you need more control over the response, or are calling from a non-shell context (e.g. a JavaScript action) — see the Britive API documentation |
Prerequisites
Before adding Britive to a GitHub Actions workflow, ensure the following are in place:
| 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 |
| GitHub repository secrets | Store BRITIVE_API_TOKEN and BRITIVE_TENANT as encrypted repository or organization secrets |
| Britive CLI (if using CLI method) | PyBritive must be installed in the runner environment, or added as a workflow step |
Environment Variables
These variables must be available to the Britive CLI or API call in the workflow job.
| Variable | Required | Where to Set | Description |
|---|---|---|---|
BRITIVE_API_TOKEN | Yes | GitHub encrypted secret | Service identity token — PyBritive reads this automatically |
BRITIVE_TENANT | Yes | GitHub encrypted secret | Britive tenant subdomain (see Finding Your Tenant Name) |
BRITIVE_PROFILE | No | Workflow env block | Profile to check out, as Application/Environment/Profile |
CLI Usage
Installing the CLI
Add a step to your workflow to install PyBritive before any checkout step. Pin the version so runner builds are reproducible:
- name: Install PyBritive
run: pip install pybritive==2.3.2 # pin to your tested versionCheckout Command
pybritive checkout with -m env-nix prints export statements; eval them in the same run: block, then use the credentials:
- name: Check out Britive profile and deploy
env:
BRITIVE_API_TOKEN: ${{ secrets.BRITIVE_API_TOKEN }}
BRITIVE_TENANT: ${{ secrets.BRITIVE_TENANT }}
run: |
eval "$(pybritive checkout "AWS Production/Prod Account/ci-deploy" -m env-nix)"
aws sts get-caller-identitypybritive 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 |
Variables exported with eval exist only in that run: block’s shell. To pass credentials to later steps, append them to $GITHUB_ENV — and call echo "::add-mask::$VALUE" on each secret value first so they never appear in logs.
REST API Usage
Use the Britive REST API directly when calling from a JavaScript action, Docker container action, or any context without a shell. Authenticate with the service identity token in the Authorization: TOKEN <token> header. See the Britive API documentation for endpoint details.
Injecting Credentials into Subsequent Steps
After a successful checkout, cloud credentials need to be available to the steps that follow. 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 (path to a temp credentials file) |
| Azure | AZURE_CLIENT_ID, AZURE_CLIENT_SECRET, AZURE_TENANT_ID |
| Snowflake | SNOWFLAKE_USER, SNOWFLAKE_PASSWORD, SNOWFLAKE_ACCOUNT |
Security Considerations
| Practice | Why It Matters |
|---|---|
Use ::add-mask:: for secret values | Prevents credentials from appearing in workflow logs |
| Scope service identity to minimum profiles | Least-privilege: the service identity should only access profiles it needs |
| Set short expiration durations | Match the checkout duration to the job’s expected runtime |
| Use environment-level secrets for prod | GitHub environment protection rules add an approval gate before secrets are exposed |