GitHub Actions
Overview
GitHub Actions jobs check out Britive profiles with the job’s own OIDC token. Britive verifies the token, matches its sub claim to a , and returns short-lived credentials for the profiles that identity’s policies allow. Nothing Britive-related is stored as a GitHub secret.
| Method | When to Use |
|---|---|
| OIDC federation (recommended) | Default for every workflow: no stored token, identity tied to the repository and deployment environment |
| Service identity token | Only where the job cannot request an OIDC token. The token is a long-lived secret; see Static Token (Fallback) |
| REST API | Non-shell contexts such as JavaScript actions; see the Britive API documentation |
Prerequisites
| Requirement | Details |
|---|---|
| OIDC identity provider in Britive | Issuer https://token.actions.githubusercontent.com, an allowed audience, and an attribute map on sub (below) |
| Service identities | One per repository and GitHub environment, matched on the token’s sub |
| Britive profile | Active, with an expiration and a policy granting the service identity access |
| GitHub environments | Deployment environments (dev, prod, …) with protection rules for production |
| PyBritive | PyBritive on the runner, or installed as a step |
Configure Britive
Create the OIDC identity provider
In Britive, create an identity provider of type OIDC:
| Setting | Value |
|---|---|
| Issuer URL | https://token.actions.githubusercontent.com |
| Attributes map | Identity attribute sub = provider attribute sub, match type Exact |
| Allowed audiences | A value of your choice, for example britive |
The audience must match what the workflow requests (-P github-<audience>, below).
Find the repository’s subject format
GitHub sets sub to <prefix>:environment:<env> for jobs that declare an environment:. The prefix depends on the repository’s OIDC subject setting:
gh api repos/<org>/<repo>/actions/oidc/customization/sub| Response | sub for the dev environment |
|---|---|
"use_immutable_subject": true | <sub_claim_prefix>:environment:dev, e.g. repo:<org>@<owner-id>/<repo>@<repo-id>:environment:dev |
| Default | repo:<org>/<repo>:environment:dev |
The immutable form includes the owner and repository IDs, so a renamed or re-created repository cannot match an existing service identity.
Create one service identity per repository and environment
For each environment, create a service identity (for example gha-<repo>-dev) federated to the identity provider with the exact sub from the previous step. Use Test matching on the identity provider to confirm the value resolves to the service identity.
Grant the service identity a profile
Add the service identity to the policy of each profile the pipeline needs. Keep one policy per environment so the dev identity cannot check out production profiles.
Workflow
The job needs id-token: write and a deployment environment:. PyBritive requests the OIDC token itself; -P github-<audience> sets the audience.
jobs:
deploy:
runs-on: ubuntu-latest
environment: dev
permissions:
id-token: write
contents: read
env:
BRITIVE_TENANT: <tenant> # tenant subdomain, not a secret
steps:
- name: Install PyBritive
run: pip install pybritive==2.3.2 # pin to your tested version
- name: Check out Britive profile and deploy
run: |
eval "$(pybritive checkout "AWS Production/Prod Account/ci-deploy" \
-t "$BRITIVE_TENANT" -P github-britive -m env-nix --silent)"
aws sts get-caller-identity
- name: Check in
if: always()
run: pybritive checkin "AWS Production/Prod Account/ci-deploy" -t "$BRITIVE_TENANT" -P github-britive --silentPlain -P github requests GitHub’s default audience (https://github.com/<org>); use it only if the identity provider allows that audience.
pybritive checkout Flags
| Flag | Required | Default | Description |
|---|---|---|---|
PROFILE (argument) | Yes | — | Profile as application name/environment name/profile name, or resources/<resource>/<profile> for Resource Manager profiles |
-t, --tenant | Yes | BRITIVE_TENANT | Tenant subdomain |
-P, --federation-provider | For OIDC | — | github or github-<audience> |
-m, --mode | No | text | Output mode: env-nix (shell exports), json, integrate (write AWS credentials file), awscredentialprocess, gcloudauth, azlogin, and more |
-s, --silent | Recommended | — | Suppresses status lines; without it they precede -m json output on stdout |
-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) |
--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.
Injecting Credentials into Subsequent Steps
| 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 |
For Kubernetes and OpenShift, a Resource Manager profile can return a per-run service account token instead; see Per-Run Pipeline Credentials.
Verify
- The checkout step logs no
Credentials for tenantline (with--silent) and the next command runs with the returned credentials. - A job in the
devenvironment that requests a production profile fails the checkout. - Britive’s audit shows the checkout under the service identity, not under a user.
Troubleshoot
| Symptom | Cause | Fix |
|---|---|---|
Authenticated to tenant ... via federation provider authentication then could not login after 3 attempts | Token sub matches no service identity | Check the subject format (gh api .../oidc/customization/sub) and the service identity’s sub |
the codebase is not executing in a github environment and/or the action is not set to use oidc permissions | Missing id-token: write | Add it under permissions: |
| Token rejected for audience | -P audience differs from the identity provider’s allowed audience | Use -P github-<allowed-audience> |
jq or parsing errors on -m json output | Status lines on stdout | Add --silent |
| Production job never gets a token from a feature branch | Environment protection rules | Expected; the prod environment limits branches before GitHub issues the token |
Static Token (Fallback)
Where OIDC is not available, a service identity token can be stored as a GitHub secret and read by PyBritive from BRITIVE_API_TOKEN. The token is long-lived: scope it to the minimum profiles, store it as an environment-level secret, and rotate it.
- name: Check out Britive profile (static token)
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 --silent)"Security Considerations
| Practice | Why It Matters |
|---|---|
| Prefer OIDC federation | No stored Britive secret to leak or rotate |
| One service identity per repository and environment | A pipeline can reach only its own environment’s profiles |
| Protect production environments | Branch policies (and required reviewers where available) gate the OIDC token itself |
Check in with if: always() | Ends the session even when the job fails or is cancelled |
| Set short expiration durations | Match the checkout duration to the job’s expected runtime |
Use ::add-mask:: for secret values | Prevents credentials from appearing in workflow logs |