docs(guides): add GitHub Actions JWT bearer token guide

[ssveta7ak]

Summary

Adds docs/guides/github-actions, a guide for letting a GitHub Actions workflow call a Pomerium-protected route using the OIDC token GitHub issues to every job, with no stored credentials.

The route uses bearer_token_format: jwt and trusts https://token.actions.githubusercontent.com through an identity_providers entry; the workflow requests a token for the route's audience and presents it as a bearer token. Authorization is entirely policy-driven on the token's claims, and the guide is explicit that any GitHub repository can mint a token from this issuer, so pinning claim/repository is the whole authorization boundary.

This is stacked on #2279 — it links to the identity_providers, per-route identity_providers, and bearer-token-access pages introduced there, so it cannot build against main until that merges.

Not yet released. The feature landed in pomerium/pomerium@69d7f68f (2026-08-10), after v0.32.5, so no tagged release supports this guide. Worth holding publication until a release includes it.

Verified against a live deployment rather than written from the reference alone: the guide's workflow, copied verbatim, returns Pomerium answered: HTTP 200, and Pomerium logs allow: true with allow-why-true: ["claim-ok"] and the identity github-actions/repo:.... Both the push and workflow_dispatch triggers were exercised.

An independent review pass against the Pomerium source and GitHub's OIDC documentation caught two errors that are fixed here:

• curl --fail only fails on status 400 and above, so a 302 sign-in redirect would have passed the workflow step silently. The call now also sends Accept: application/json so denials arrive as 401/403.
• The JWKS fetch is lazy (on first verification), not at config load; the diagram said otherwise.

The guide also avoids pinning the sub claim, because repositories created after 2026-07-15 get the immutable format embedding numeric owner and repository IDs — confirmed in the live token captured during testing.

Related

• Stacked on docs(bearer-tokens): machine-to-machine access with bearer tokens & JWTs #2279 (bearer-token access docs; provides this guide's link targets)
• Implements docs for config: create sessions from externally-issued JWT bearer tokens pomerium#6591 and config: support issuer: kubernetes:/// for in-cluster JWKS verification pomerium#6592

AI disclosure

Claude Code. The guide was AI-drafted, then fact-checked by a separate adversarial review pass against the Pomerium source and GitHub's current OIDC documentation, which produced the two corrections listed above. Every configuration snippet, status code, and log line was verified against a live Pomerium deployment before submission. Reviewed and edited by me.

Checklist

• reference any related issues
• updated docs
• updated UPGRADING.md — n/a, new guide
• updated CHANGELOG.md — n/a, new guide
• disclosed AI usage (or wrote "none") per AI_POLICY.md

[netlify]

✅ Deploy Preview for pomerium-docs ready!

Name	Link
🔨 Latest commit	2be9b21
🔍 Latest deploy log	https://app.netlify.com/projects/pomerium-docs/deploys/6a7dc88bfce88f0008f6aa20
😎 Deploy Preview	https://deploy-preview-2346--pomerium-docs.netlify.app
📱 Preview on mobile	Toggle QR Code... Use your smartphone camera to open QR code link.
🤖 Make changes	Run an agent on this branch

---

To edit notification comments on pull requests, go to your Netlify project configuration.

[greptile-apps]

Greptile Summary

Adds documentation for authenticating GitHub Actions and other machine workloads to Pomerium-protected routes using verified JWT bearer tokens.

• Adds a GitHub Actions OIDC workflow guide with claim-based repository and branch authorization.
• Documents JWT identity providers, per-route provider allowlists, bearer-token behavior, and Kubernetes service-account usage.
• Registers the bearer-token capability in the documentation sidebar and records why automated example validation is skipped.

Confidence Score: 5/5

The PR appears safe to merge.

No blocking failure remains.

Important Files Changed

Filename	Overview
content/docs/guides/github-actions.mdx	Adds the end-to-end GitHub Actions OIDC configuration, workflow, verification steps, troubleshooting, and security guidance.
content/docs/capabilities/bearer-token-access.mdx	Adds an overview of JWT bearer authentication with Kubernetes, SPIFFE, and GitHub Actions examples.
content/docs/reference/identity-providers.mdx	Documents global JWT identity-provider configuration, verification behavior, session derivation, and platform-specific syntax.
content/docs/reference/routes/identity-providers.mdx	Documents the per-route identity-provider allowlist for JWT bearer-token routes.
content/docs/reference/bearer-token-format.mdx	Extends the bearer-token reference with the JWT format and explains extraction, verification, session creation, and authorization.
sidebars.js	Adds the bearer-token capability page to the primary documentation sidebar.

Sequence Diagram

sequenceDiagram
  participant W as GitHub Actions workflow
  participant G as GitHub OIDC provider
  participant P as Pomerium
  participant U as Protected upstream
  W->>G: Request JWT for route audience
  G-->>W: Short-lived signed JWT
  W->>P: Request with Bearer JWT
  P->>G: Fetch and cache signing keys
  P->>P: Verify issuer, signature, expiry, and audience
  P->>P: Authorize repository and optional ref claims
  P->>U: Proxy authorized request
  U-->>W: Response

Loading

_{Reviews (4): Last reviewed commit: "docs(guides): mark github-actions guide ..." | Re-trigger Greptile}