# CI Integration & OIDC Authentication {#oidc}

When using Takumi Guard linked to a Shisho Cloud organization from GitHub Actions, the **GitHub OIDC provider** is used to identify the origin of the workflow and verify that the request comes from a pre-approved GitHub organization. Upon successful verification, an access token is issued, and `npm install` download logs made with that token are recorded against the organization. No long-lived secrets need to be stored in your CI environment.

## Authentication Flow {#auth-flow}

GitHub Actions can issue an OIDC token at workflow runtime. This token contains information about the GitHub organization and repository that ran the workflow. Shisho Cloud's STS (Security Token Service) verifies the token's signature and origin, and if the request comes from a GitHub organization on the pre-configured allowlist, it issues a short-lived access token for Takumi Guard.

```mermaid
sequenceDiagram
    participant GH as GitHub Actions
    participant STS as Shisho Cloud STS
    participant GHOIDC as GitHub OIDC Provider
    participant Guard as Takumi Guard

    GH->>GH: Obtain OIDC token
    GH->>STS: Send OIDC token + Bot ID
    STS->>GHOIDC: Fetch public keys from JWKS endpoint
    GHOIDC-->>STS: Public key set (JWKS)
    STS->>STS: Verify signature, check if GitHub org is on allowlist
    STS-->>GH: Issue short-lived access token
    GH->>Guard: npm install with access token
    Guard->>Guard: Validate token, record download against organization
```

## Access Token {#access-token}

Upon successful verification, STS issues a short-lived access token. This token contains the Shisho Cloud organization to which downloads are attributed, as well as the GitHub repository and workflow where the job ran.

Takumi Guard validates this token and records downloads from `npm install` against the organization. The token expires automatically after the job completes, minimizing leak risk. The default access token lifetime is 30 minutes (configurable up to 24 hours).

## About Bot ID {#bot-id}

Bot ID is not a secret — it is a **public reference key** used to look up the allowlist. It can be committed directly to workflow files. Authentication relies on signature verification by the GitHub OIDC provider and matching against the allowlist, so a Bot ID alone cannot obtain an access token.