Skip to content

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.

MethodWhen to Use
OIDC federation (recommended)Default for every workflow: no stored token, identity tied to the repository and deployment environment
Service identity tokenOnly where the job cannot request an OIDC token. The token is a long-lived secret; see Static Token (Fallback)
REST APINon-shell contexts such as JavaScript actions; see the Britive API documentation

Prerequisites

RequirementDetails
OIDC identity provider in BritiveIssuer https://token.actions.githubusercontent.com, an allowed audience, and an attribute map on sub (below)
Service identitiesOne per repository and GitHub environment, matched on the token’s sub
Britive profileActive, with an expiration and a policy granting the service identity access
GitHub environmentsDeployment environments (dev, prod, …) with protection rules for production
PyBritivePyBritive on the runner, or installed as a step

Configure Britive

Create the OIDC identity provider

In Britive, create an identity provider of type OIDC:

SettingValue
Issuer URLhttps://token.actions.githubusercontent.com
Attributes mapIdentity attribute sub = provider attribute sub, match type Exact
Allowed audiencesA 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
Responsesub for the dev environment
"use_immutable_subject": true<sub_claim_prefix>:environment:dev, e.g. repo:<org>@<owner-id>/<repo>@<repo-id>:environment:dev
Defaultrepo:<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.

.github/workflows/deploy.yml
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 --silent

Plain -P github requests GitHub’s default audience (https://github.com/<org>); use it only if the identity provider allows that audience.

pybritive checkout Flags

FlagRequiredDefaultDescription
PROFILE (argument)Yes—Profile as application name/environment name/profile name, or resources/<resource>/<profile> for Resource Manager profiles
-t, --tenantYesBRITIVE_TENANTTenant subdomain
-P, --federation-providerFor OIDC—github or github-<audience>
-m, --modeNotextOutput mode: env-nix (shell exports), json, integrate (write AWS credentials file), awscredentialprocess, gcloudauth, azlogin, and more
-s, --silentRecommended—Suppresses status lines; without it they precede -m json output on stdout
-j, --justificationNo—Justification string if the profile policy requires one
-b, --blocktimeNo3 / 60Seconds to wait before polling for credentials (60 for approval-gated profiles)
--ticket-type / --ticket-idNo—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

CloudCredential Variables Injected
AWSAWS_ACCESS_KEY_ID, AWS_SECRET_ACCESS_KEY, AWS_SESSION_TOKEN
GCPGOOGLE_APPLICATION_CREDENTIALS (path to a temp credentials file)
AzureAZURE_CLIENT_ID, AZURE_CLIENT_SECRET, AZURE_TENANT_ID
SnowflakeSNOWFLAKE_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 tenant line (with --silent) and the next command runs with the returned credentials.
  • A job in the dev environment that requests a production profile fails the checkout.
  • Britive’s audit shows the checkout under the service identity, not under a user.

Troubleshoot

SymptomCauseFix
Authenticated to tenant ... via federation provider authentication then could not login after 3 attemptsToken sub matches no service identityCheck 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 permissionsMissing id-token: writeAdd it under permissions:
Token rejected for audience-P audience differs from the identity provider’s allowed audienceUse -P github-<allowed-audience>
jq or parsing errors on -m json outputStatus lines on stdoutAdd --silent
Production job never gets a token from a feature branchEnvironment protection rulesExpected; 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.

.github/workflows/example.yml
- 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

PracticeWhy It Matters
Prefer OIDC federationNo stored Britive secret to leak or rotate
One service identity per repository and environmentA pipeline can reach only its own environment’s profiles
Protect production environmentsBranch 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 durationsMatch the checkout duration to the job’s expected runtime
Use ::add-mask:: for secret valuesPrevents credentials from appearing in workflow logs

Related

Last updated on