Token rotation cadence — PAT, OAuth, and OIDC tokens

A CI system holds tokens. The kind of token determines the rotation cadence, and the rotation cadence determines the window of exposure. This lesson walks the three token types a GitHub-centred workflow holds - PAT, OAuth app token, and OIDC token - and the discipline appropriate to each.

Three token types, three cadences

The tokens a workflow holds are not interchangeable:

• Personal access token (PAT). A user-issued string that authenticates as a user. Can be fine-grained (scoped to specific repositories and permissions) or classic (broader scope). Long-lived: valid for the lifetime the user chose at creation, up to one year.
• OAuth app token. An app-issued string that authenticates as an OAuth app installation. Refreshable: the app holds a long-lived refresh token and exchanges it for short-lived access tokens (typically one hour).
• OIDC token. A platform-issued, signed, short-lived token that proves the workflow’s identity to an external system (AWS, GCP, Azure). Valid for the duration of a single job - up to one hour - and discarded at job end.

flowchart TD
    A["CI workflow needs credential"] --> B{"Token type"}
    B --> C["PAT (long-lived)"]
    B --> D["OAuth app (refreshable)"]
    B --> E["OIDC (per-job)"]
    C --> F["Rotate quarterly or per policy"]
    D --> G["Refresh access token hourly"]
    E --> H["No rotation needed; token expires with job"]

The OIDC token is the right answer when the target platform supports federation. The OAuth app token is the right answer when the workflow needs to call a third-party API that does not yet accept OIDC. The PAT is the right answer only when no better option exists - and even then, the rotation cadence must be enforced.

Refreshing the gh CLI session

The gh CLI holds a long-lived credential (a PAT or an OAuth token) on disk in the credential helper. The session can be refreshed in place.

gh auth status
gh auth token --refresh
gh auth token --refresh --hostname github.example.com

The first command confirms which account the CLI is authenticated as. The second refreshes the active session and prints the new token to standard output. The third does the same for a GitHub Enterprise Server host. The refresh fails if the underlying credential is a PAT that has not been granted the workflow scope; OAuth app tokens refresh silently because the refresh token is stored alongside the access token.

The cadence for each type

The rotation cadence is a function of the token’s lifetime and the leak surface:

• PAT. Rotate quarterly at minimum. A PAT used by a single CI workflow can be scoped narrowly enough that the blast radius of a leak is small, but the credential is still long-lived and still benefits from regular retirement.
• OAuth app token. The access token rotates automatically on each refresh; the long-lived component is the refresh token. Rotate the refresh token annually or on the underlying app’s policy.
• OIDC token. No rotation cadence is required because the token expires at job end. The discipline is to ensure the trust policy on the receiving side accepts short-lived tokens and rejects long-lived static credentials.

The OIDC pattern is the long-term replacement for the PAT. A team that has migrated its deploy workflow to OIDC has eliminated a category of long-lived credential entirely.

Why PATs persist

The reason PATs are still common is that some workflows genuinely need a long-lived credential: a cron job that runs outside the Actions environment, a script that pushes back to the repository from a developer’s laptop, an automation that calls an API outside the federation chain. For these cases, the PAT is the right tool, and the discipline is to:

1. Scope the PAT narrowly (one repository, the minimum set of permissions).
2. Set the shortest expiry the platform allows.
3. Store the PAT in a secret manager, not in shell environment files.
4. Rotate on a fixed cadence regardless of whether a leak is suspected.
5. Audit the PAT list quarterly and revoke any PAT that is no longer used.

Production discipline

1. Prefer OIDC over PAT or OAuth app tokens. Short-lived tokens expire by design.
2. Rotate PATs quarterly at minimum. A PAT without a rotation date is a PAT that has been forgotten.
3. Scope PATs to one repository and the minimum set of permissions. Broad-scope PATs are broad-blast-radius PATs.
4. Audit the PAT list quarterly. Unused PATs are leaked PATs.
5. Treat refresh as maintenance, not rotation. Refresh extends lifetime; rotation retires it.

Cross-course references

• This course, Part XLIII-04 (OIDC in AWS) covers the cloud-side OIDC trust policy that consumes the OIDC token.
• This course, Part XXXIV-03 (HTTPS tokens and PATs) covers the PAT storage and helper mechanics.
• This course, Part XCII-03 (Environment secrets and isolation) covers the scoping rules that determine which token a workflow actually receives.

Quiz