Skip to main content
Every GitHub Actions job can ask GitHub for a signed identity token that says which repository, workflow, and branch it’s running. With workload identity federation, your job exchanges that token for a KERNEL access token. You don’t store a 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:
.github/workflows/e2e.yml
Your script constructs the client with no arguments:
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

When KERNEL_FEDERATION_RULE_ID is set and the runner exposes ACTIONS_ID_TOKEN_REQUEST_URL, the SDK:
  1. Asks the runner for an identity token with the audience https://auth.onkernel.com.
  2. Exchanges it at https://auth.onkernel.com/token.
  3. Sends the access token on each API request, and requests a new identity token for each refresh.
A job of any length stays authenticated, because each refresh uses a new GitHub token. GitHub tokens are always single-use in KERNEL: one token, one exchange. If the job doesn’t have 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:
Two details to make note of:
  • sub now embeds numeric IDs. GitHub’s subject looks like repo:owner@id/name@id:ref:.... KERNEL rules match the repository_id and repository_owner_id claims, not sub, so you don’t write subject patterns for GitHub.
  • repository_id and repository_owner_id are 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_id and repository_owner_id equal the rule’s IDs.
  • event_name is one of the rule’s allowed events.
  • If the rule sets a branch, ref equals it. The dashboard stores main as refs/heads/main.
  • If the rule sets an environment, environment equals it.
  • If the rule sets a workflow path, workflow_ref equals <repository>/<workflow path>@<ref>. The workflow file must come from the same ref the job runs on.
Every GitHub rule needs the repository and owner IDs, a workflow restriction, and a branch or an environment. KERNEL rejects a rule without them, so you can’t create a rule that trusts a whole GitHub organization by accident.
Use an environment when the job must be approved. A rule that requires environment: production only matches jobs that GitHub let into that environment, so your environment’s protection rules and required reviewers gate KERNEL access too.

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:
The access token lasts for the rule’s token lifetime, 300 seconds by default. For a longer job, repeat both requests: each exchange needs a new GitHub token.

Next steps