Skip to main content

API · WORKLOAD IDENTITY

GitHub Actions workload access

GitHub Actions OIDC exchange is available only after an authorized workload identity has been configured. It is not human SSO or self-service repository registration.

1. Request a binding

Onboarding is currently managed. Email AppsCert support with configuration metadata only. The link opens your email client; it does not send automatically, confirm receipt or provision an identity.

  • The AppsCert organization and canonical GitHub repository (owner/name).
  • The numeric repository_id and repository_owner_id claims.
  • The exact permitted Git ref, full workflow reference ending in @refs/..., and environment name, or none.
  • The expected OIDC audience and minimum API operations/scopes. If the audience is unknown, ask support to provide it.

Bindings match these values exactly; do not request a wildcard or all-branches binding. Wait for confirmation that the identity and claims are active. Never email an OIDC JWT, workload token, API key, password, certificate or private key.

2. Configure the workflow

The integration example uses ref refs/heads/main, workflow reference OWNER/REPOSITORY/.github/workflows/appscert-plan.yml@refs/heads/main and environment appscert-release-read. If using its trusted-repository fallback without a GitHub Environment, request environment none instead.

A reusable workflow can supply job_workflow_ref; support must match the actual claim. This AppsCert binding protects the OIDC exchange only. The GitHub read token used earlier to download private releases needs GitHub's own secret access controls. Review the private-release prerequisites before storing it.

The requesting job needs id-token: write. This permits OIDC token retrieval, not general repository writes. Use the confirmed audience when requesting the assertion. See GitHub's OIDC permissions reference.

3. Exchange and introspect

Send JSON { "assertion": "$GITHUB_OIDC_JWT" } to POST /api/v1/auth/exchange, substituting the job's actual assertion securely. The response returns access_token, expires_in and the configured scope. Treat the token as a secret; do not print the response.

To check activity, send { "token": "$WORKLOAD_TOKEN" } to the same route with ?op=introspect. The token belongs in the JSON body, never the query string. Check active, not just HTTP 200: inactive tokens also receive a successful introspection response.

See OpenAPI for exact bodies, optional identity hints, response fields and rate-limit errors. An unregistered repository cannot provision itself through exchange.

c3209c7