KERNEL_API_KEY secret in the repository, and a fork or another workflow can’t use your access.
Before you start
- You’re an organization admin in KERNEL.
- You can edit workflow files in the repository.
- Your workflow uses the TypeScript, Python, or Go SDK. For anything else, see Exchange the token yourself.
Connect the workflow
1
Register GitHub as an issuer
In the dashboard, open Keys > Workload identity, click Connect workload, and select the GitHub Actions tile. GitHub has one fixed issuer,
https://token.actions.githubusercontent.com, so there’s nothing to enter except an optional Name. Click Apply and continue.Trusting GitHub’s issuer accepts no workflow by itself. Each rule names the repository, workflow, and branch or environment it allows. If your organization already registered GitHub, select Use a registered issuer instead.2
Describe the workflow in a rule
Fill in the Match conditions:
Set a branch, an environment, or both. A job must match every value you set.Under Authorization, choose the Project, the Permissions, and the Token lifetime.
3
Pick a service account and enable
Choose or create a service account, click Create rule, then turn on the issuer and the rule in the Test step. Copy the rule ID (
wifr_...).4
Update the workflow
Give the job permission to request an identity token, and set the rule ID. The rule ID isn’t a secret, so it can live in the workflow file:Your script constructs the client with no arguments:
.github/workflows/e2e.yml
5
Run it and remove the old secret
Push to the branch or run the workflow by hand. The exchange appears in the wizard and on the Authentication events tab.If the repository has a
KERNEL_API_KEY secret, stop passing it to this job. The SDK uses the API key whenever it’s set. Then delete the secret and the key. See Move a workload from an API key.What the SDK does
WhenKERNEL_FEDERATION_RULE_ID is set and the runner exposes ACTIONS_ID_TOKEN_REQUEST_URL, the SDK:
- Asks the runner for an identity token with the audience
https://auth.onkernel.com. - Exchanges it at
https://auth.onkernel.com/token. - Sends the access token on each API request, and requests a new identity token for each refresh.
id-token: write, the runner sets no token endpoint, so the SDK finds no identity token source and the client fails with a missing-credentials error. Add the permission to the workflow or the job.
To select GitHub explicitly instead of relying on detection, set KERNEL_IDENTITY_TOKEN_SOURCE=github_actions, or configure it in code:
What the token looks like
A GitHub identity token carries claims like these. Your rule is checked against them:subnow embeds numeric IDs. GitHub’s subject looks likerepo:owner@id/name@id:ref:.... KERNEL rules match therepository_idandrepository_owner_idclaims, notsub, so you don’t write subject patterns for GitHub.repository_idandrepository_owner_idare strings. If you create rules through the API, send them as strings of digits.
How a rule matches
A GitHub Actions rule accepts a token only when all of these hold:repository_idandrepository_owner_idequal the rule’s IDs.event_nameis one of the rule’s allowed events.- If the rule sets a branch,
refequals it. The dashboard storesmainasrefs/heads/main. - If the rule sets an environment,
environmentequals it. - If the rule sets a workflow path,
workflow_refequals<repository>/<workflow path>@<ref>. The workflow file must come from the same ref the job runs on.
Find the repository IDs yourself
The dashboard’s Look up IDs button does this for you. From a terminal:Exchange the token yourself
Without an SDK, request the token from the runner and post it to the token endpoint:Next steps
- Reference: every GitHub Actions match field
- Troubleshooting: what a refused exchange means
- Move a workload from an API key