Workload identity for GitHub Actions

Contents

Note: PostHog doesn't accept GitHub Actions tokens yet. This page describes how it works so you can plan for it. Until then, use a personal API key.

hog isn't released yet

hog is PostHog's new CLI. It isn't released yet. Every hog command on this page is a beta preview of how it works once hog is released, and the details can change. Until then, use posthog-cli with a personal API key, as its authentication docs describe.

A GitHub Actions job can trade the OIDC token GitHub issues for each run for a short-lived PostHog token. You don't store a personal API key as a repository secret, and the token only works on one project. The overview covers trust policies, requests, and the token exchange for every provider.

What the job needs

  • The id-token: write permission, so GitHub issues an OIDC token to the job
  • A trusted workload in your PostHog project that matches the repository and the runs you pick
  • HOG_HOST and HOG_PROJECT_ID in the job's environment

PostHog trusts GitHub's issuer, https://token.actions.githubusercontent.com. GitHub Enterprise Cloud can issue tokens from an issuer URL that includes your enterprise's slug. PostHog doesn't accept those issuers.

How the job gets a token

When a job has id-token: write, GitHub sets ACTIONS_ID_TOKEN_REQUEST_URL and ACTIONS_ID_TOKEN_REQUEST_TOKEN in its environment. Once hog is released, it uses them to ask GitHub for an OIDC token whose audience is your PostHog host, then exchanges that token at /oauth/token/.

GitHub's OIDC tokens live about 5 minutes, and the PostHog token never outlives the token it came from. hog keeps the PostHog token in memory and exchanges a new GitHub token when it's close to expiring, or after a 401, so a long job keeps working.

See GitHub's OpenID Connect docs and OIDC reference for how GitHub issues these tokens.

Which runs a policy matches

A policy identifies the repository with two claims, and both must match:

  • repository_id - the repository's numeric ID. It never changes, so a repository that is deleted and created again with the same name doesn't match.
  • repository - the repository's full name, such as acme/web. If you rename the repository, update the policy.

Conditions narrow which runs in that repository get a token. A policy sets at least one.

ClaimWhat it holdsExample value
refThe Git ref the run is forrefs/heads/main
environmentThe deployment environment the job usesproduction
ref_protectedWhether branch protection rules or rulesets cover the reftrue
event_nameThe event that started the workflowpush
workflow_refThe workflow file and the ref it ran fromacme/web/.github/workflows/deploy.yml@refs/heads/main
job_workflow_refThe reusable workflow the job called, and its refacme/ci/.github/workflows/release.yml@refs/heads/main
runner_environmentWhether the job ran on a GitHub-hosted or self-hosted runnergithub-hosted

Presets in PostHog settings

Under Which runs can get a token, the settings page offers these presets:

PresetConditions it setsWhen to use it
Pushes to a branch (default)ref = refs/heads/<branch> and event_name = pushJobs that run after code lands on a branch, such as deploys from main
A deployment environmentenvironment = <environment>Jobs that deploy through a GitHub environment, which can require a reviewer before the job runs
Protected branches onlyref_protected = trueJobs on any branch that your branch protection rules or rulesets cover
CustomAny claim from the table above, with an exact valueAnything the presets don't cover

Why the default is safe

Pushes to a branch pins both the branch and the event, because the branch alone isn't enough.

A workflow that runs on pull_request_target can get an OIDC token when the pull request comes from a fork, and its ref is the base branch. A policy that only pins ref = refs/heads/main would give that run a token. Requiring event_name = push means only code pushed to the branch matches.

Workflows that run on pull_request from a fork don't get an OIDC token at all.

Set up a trusted workload

Only organization admins and owners can add a trusted workload. Anyone else in the project can ask an admin for one.

In PostHog settings

  1. In your project settings, go to Trusted workloads and add a trusted workload.
  2. Pick GitHub Actions as the provider.
  3. In Repository, enter owner/repo and click Find. If PostHog can't find the repository, enter its ID in the field that appears. You can get the ID with the GitHub CLI: gh api repos/<owner>/<repo> --jq .id.
  4. Under Which runs can get a token, keep Pushes to a branch and enter the branch, or pick another preset.
  5. Pick the scopes the job needs.
  6. Save, then copy the workflow snippet PostHog shows.

With hog ci setup (beta)

Once hog is released, run this in your repository:

Terminal
hog ci setup --branch main --scope annotation:write

hog reads owner/repo from your git remote, looks up the repository ID, and applies the Pushes to a branch preset for main. Use --environment production instead for the deployment environment preset. Repeat --scope for each scope the job needs.

hog then creates a policy request and waits for an admin to approve it. If you stop waiting, run hog ci setup --wait to pick it up again. After approval, hog prints the workflow snippet.

Add the workflow snippet

Add these keys to the job that calls PostHog:

YAML
permissions:
id-token: write
contents: read
env:
HOG_HOST: https://us.posthog.com
HOG_PROJECT_ID: "12345"
steps:
- run: hog <command>
  • id-token: write lets the job ask GitHub for an OIDC token. Setting permissions turns off every permission you don't list, so contents: read keeps actions/checkout working.
  • HOG_HOST is the PostHog instance the policy lives on, such as https://eu.posthog.com for EU Cloud. hog sends requests there and uses it as the token's audience.
  • HOG_PROJECT_ID is your project's ID: the number in your project URL, such as 12345 in https://us.posthog.com/project/12345.

Remove any personal API key from the job's environment. hog uses a personal API key ahead of the workload token.

Troubleshooting

ProblemLikely causeWhat to do
hog can't get an OIDC tokenThe job doesn't have id-token: write, or the run is a pull_request from a forkAdd the permission to the job. Fork pull requests can't get a token.
workload_issuer_not_allowedYour enterprise issues tokens from an issuer URL with its slugAsk an enterprise owner to switch back to GitHub's default issuer.
workload_token_invalidThe token's audience isn't the host hog sends it to, or the token expiredSet HOG_HOST to the PostHog instance the policy lives on.
workload_no_matching_policyThe run doesn't match the policy, for example a pull request, a tag, a manual run, or another branch. A renamed or recreated repository, or the wrong HOG_PROJECT_ID, also cause it.Compare the run's event and ref with the policy's conditions, and check the repository name and ID.
workload_policy_request_pendingAn admin hasn't approved the request yetSend the approval link from the error to an admin.
workload_no_usable_scopesThe policy only grants scopes a workload can't useAsk an admin to add scopes the job can use.
workload_rate_limitedToo many exchanges for this repository in a short timeWait, then retry the job.
A call fails with 403The policy doesn't grant the scope the call needsThe WWW-Authenticate header names the scope. Ask an admin to add it.

See errors in the overview for every error code.

Still have questions?

Was this page useful?