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 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: writepermission, 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_HOSTandHOG_PROJECT_IDin 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 asacme/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.
| Claim | What it holds | Example value |
|---|---|---|
ref | The Git ref the run is for | refs/heads/main |
environment | The deployment environment the job uses | production |
ref_protected | Whether branch protection rules or rulesets cover the ref | true |
event_name | The event that started the workflow | push |
workflow_ref | The workflow file and the ref it ran from | acme/web/.github/workflows/deploy.yml@refs/heads/main |
job_workflow_ref | The reusable workflow the job called, and its ref | acme/ci/.github/workflows/release.yml@refs/heads/main |
runner_environment | Whether the job ran on a GitHub-hosted or self-hosted runner | github-hosted |
Presets in PostHog settings
Under Which runs can get a token, the settings page offers these presets:
| Preset | Conditions it sets | When to use it |
|---|---|---|
| Pushes to a branch (default) | ref = refs/heads/<branch> and event_name = push | Jobs that run after code lands on a branch, such as deploys from main |
| A deployment environment | environment = <environment> | Jobs that deploy through a GitHub environment, which can require a reviewer before the job runs |
| Protected branches only | ref_protected = true | Jobs on any branch that your branch protection rules or rulesets cover |
| Custom | Any claim from the table above, with an exact value | Anything 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
- In your project settings, go to Trusted workloads and add a trusted workload.
- Pick GitHub Actions as the provider.
- In Repository, enter
owner/repoand 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. - Under Which runs can get a token, keep Pushes to a branch and enter the branch, or pick another preset.
- Pick the scopes the job needs.
- Save, then copy the workflow snippet PostHog shows.
With hog ci setup (beta)
Once hog is released, run this in your repository:
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:
id-token: writelets the job ask GitHub for an OIDC token. Settingpermissionsturns off every permission you don't list, socontents: readkeepsactions/checkoutworking.HOG_HOSTis the PostHog instance the policy lives on, such ashttps://eu.posthog.comfor EU Cloud. hog sends requests there and uses it as the token's audience.HOG_PROJECT_IDis your project's ID: the number in your project URL, such as12345inhttps://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
| Problem | Likely cause | What to do |
|---|---|---|
| hog can't get an OIDC token | The job doesn't have id-token: write, or the run is a pull_request from a fork | Add the permission to the job. Fork pull requests can't get a token. |
workload_issuer_not_allowed | Your enterprise issues tokens from an issuer URL with its slug | Ask an enterprise owner to switch back to GitHub's default issuer. |
workload_token_invalid | The token's audience isn't the host hog sends it to, or the token expired | Set HOG_HOST to the PostHog instance the policy lives on. |
workload_no_matching_policy | The 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_pending | An admin hasn't approved the request yet | Send the approval link from the error to an admin. |
workload_no_usable_scopes | The policy only grants scopes a workload can't use | Ask an admin to add scopes the job can use. |
workload_rate_limited | Too many exchanges for this repository in a short time | Wait, then retry the job. |
A call fails with 403 | The policy doesn't grant the scope the call needs | The WWW-Authenticate header names the scope. Ask an admin to add it. |
See errors in the overview for every error code.





