Workload identity for Depot CI
Contents
Note: PostHog doesn't accept Depot CI 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 Depot CI job can trade the OIDC token Depot issues for each job for a short-lived PostHog token. You don't store a personal API key as a 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 Depot issues an OIDC token to the job - A Depot runner, such as
depot-ubuntu-latest - A trusted workload in your PostHog project that matches your Depot organization, the repository, and the runs you pick
HOG_HOSTandHOG_PROJECT_IDin the job's environment
PostHog trusts Depot's issuer, https://identity.depot.dev.
How the job gets a token
When a job has id-token: write, Depot puts the same token request variables in its environment that GitHub Actions does. Once hog is released, it uses them to ask Depot for an OIDC token whose audience is your PostHog host, then exchanges that token at /oauth/token/.
Depot's OIDC tokens live 5 minutes, and the PostHog token never outlives the token it came from. hog keeps the PostHog token in memory and exchanges a new Depot token when it's close to expiring, or after a 401, so a long job keeps working.
See Depot's OIDC docs for how Depot issues these tokens and what each claim holds.
Which runs a policy matches
A policy identifies the repository with two claims, and both must match:
repository_id- the repository's ID, assigned by the forge that hosts it. For a GitHub repository, this is the GitHub repository ID.repository- the repository's full name, such asacme/web. If you rename the repository, update the policy.
Depot repository IDs are only unique within one forge. So every Depot policy also pins two conditions:
org_id- your Depot organization ID, so only jobs your organization runs can matchforge- the forge that hosts the repository,githubby default, so a repository on another forge with the same ID can't match
These are the conditions a Depot policy can use:
| Claim | What it holds | Example value |
|---|---|---|
org_id | Your Depot organization ID | 1a2b3c4d |
forge | The forge that hosts the repository | github |
ref | The Git ref the run is for | refs/heads/main |
event_name | The event that started the workflow | push |
workflow_ref | The workflow file and the ref it ran from | acme/web/ci.yaml@refs/heads/main |
Depot tokens don't carry environment or protected-branch claims, so a Depot policy can't pin those.
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 |
|---|---|---|
| Your Depot organization (required) | org_id = <organization ID> | Every Depot policy |
| Pushes to a branch | ref = refs/heads/<branch> and event_name = push | Jobs that run after code lands on a branch, such as deploys from main |
| Custom | Any claim from the table above, with an exact value | Anything the presets don't cover |
Why the defaults are safe
- Pinning
org_idandforgemeans only jobs your Depot organization runs, for the repository on that forge, can match. - Pushes to a branch pins both the branch and the event. Requiring
event_name=pushmeans runs that other events start, such as pull requests, don't match. Only code pushed to the branch gets a token.
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 Depot CI 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. For a GitHub repository, you can get the ID with the GitHub CLI:gh api repos/<owner>/<repo> --jq .id. - Under Which runs can get a token, enter your Depot organization ID. Copy it from your Depot organization settings, without an
org_prefix. - Also pick Pushes to a branch and enter the branch, or set a custom condition.
- 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. 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. Every Depot policy pins your organization, so check its Depot organization ID before you approve the request.
Add the workflow snippet
Add these keys to the job in your Depot CI workflow that calls PostHog:
id-token: writelets the job ask Depot for an OIDC token. Settingpermissionsturns off every permission you don't list, socontents: readkeeps checkout working.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 | Add the permission to the job. |
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 manual run, or another branch. A different Depot organization or forge, a renamed 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 organization ID, forge, and repository. |
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.





