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 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 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: write permission, 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_HOST and HOG_PROJECT_ID in 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 as acme/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 match
  • forge - the forge that hosts the repository, github by default, so a repository on another forge with the same ID can't match

These are the conditions a Depot policy can use:

ClaimWhat it holdsExample value
org_idYour Depot organization ID1a2b3c4d
forgeThe forge that hosts the repositorygithub
refThe Git ref the run is forrefs/heads/main
event_nameThe event that started the workflowpush
workflow_refThe workflow file and the ref it ran fromacme/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:

PresetConditions it setsWhen to use it
Your Depot organization (required)org_id = <organization ID>Every Depot policy
Pushes to a branchref = refs/heads/<branch> and event_name = pushJobs that run after code lands on a branch, such as deploys from main
CustomAny claim from the table above, with an exact valueAnything the presets don't cover

Why the defaults are safe

  • Pinning org_id and forge means 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 = push means 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

  1. In your project settings, go to Trusted workloads and add a trusted workload.
  2. Pick Depot CI 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. For a GitHub repository, you can get the ID with the GitHub CLI: gh api repos/<owner>/<repo> --jq .id.
  4. Under Which runs can get a token, enter your Depot organization ID. Copy it from your Depot organization settings, without an org_ prefix.
  5. Also pick Pushes to a branch and enter the branch, or set a custom condition.
  6. Pick the scopes the job needs.
  7. 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. 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:

YAML
runs-on: depot-ubuntu-latest
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 Depot for an OIDC token. Setting permissions turns off every permission you don't list, so contents: read keeps 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: writeAdd the permission to the job.
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 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_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?