Documentation Index
Fetch the complete documentation index at: https://docs.chainloop.dev/llms.txt
Use this file to discover all available pages before exploring further.
Chainloop interacts with GitHub in three different places, and each one has its own permission surface. This page is the consolidated reference.
Chainloop GitHub App
The Chainloop GitHub App is the integration installed from Repositories → Add Repositories → GitHub in the Chainloop Web UI. One installation covers every Chainloop feature that needs to talk to GitHub on your behalf — repository enrollment, AI session PR correlation, vulnerability auto-remediation, sandbox-backed agent runs, and the SCM Configuration Check.
What Chainloop persists vs. what it accesses transiently. Chainloop only persists repository metadata (ID and name). Some features — auto-remediation, the Vulnerabilities Agent, and other sandbox-backed scans (SAST, secrets, vulnerability scanning) — do clone your repository, but always into an isolated sandbox using a short-lived, repo-scoped token (1 h TTL), and the source is discarded when the run ends. See Scoped vs broad installation tokens below.
Cumulative permission set
Requested by the App manifest at install time. The “Where it’s used” column points to the per-feature breakdown below for detail.
| Scope | Access | Why | Where it’s used |
|---|
| Metadata | Read | Default GitHub App requirement; identifies the repository | Every feature |
| Contents | Read & Write | Read commit metadata for PR correlation and clone repo contents for analysis (read); commit auto-remediation fixes (write) | Trace, sandbox clone, SCM check, auto-remediation |
| Pull requests | Read & Write | Receive PR webhook payloads and read PR metadata (read); open auto-remediation PRs (write) | Trace, auto-remediation |
| Issues | Write | Post and update the Chainloop bot comment on PR conversations (GitHub treats PR conversation comments as issue comments) | Trace PR summary comment |
| Checks | Read & Write | Publish the Chainloop AI Policies check run on the PR head commit | Trace merge gate |
| Administration | Read | Read branch protection settings and rulesets | SCM Configuration Check |
| Members | Read | Detect account type at install time and list org members (including 2FA status) for SCM hardening checks | Install flow, SCM Configuration Check |
The write grants are used only to post Chainloop’s own comments, check runs, and auto-remediation PRs. Chainloop does not push to your default branch, modify code outside of remediation branches, or alter PR state authored by your team.
Subscribed webhook events
| Event | Why |
|---|
pull_request | Trigger AI session correlation; resolve auto-remediation PRs on merge |
issue_comment | Track engagement on remediation PR conversations |
pull_request_review | Track engagement on remediation PRs |
pull_request_review_comment | Track engagement on remediation PRs |
opened, synchronize, closed, labeled, and unlabeled.
Per-feature breakdown
| Feature | Scopes used | Token type | Docs |
|---|
| Repository import (after install) | Read: Metadata | Installation token | — |
| Keyless attestations (repo enrollment) | Read: Metadata | Installation token | Guide |
| Chainloop Trace — AI session correlation | Read: Contents, Pull requests
Write: Issues | Installation token | Guide |
| Chainloop Trace — AI policy check run | Write: Checks | Installation token | Guide |
| Auto-remediation — open PR with the fix | Read: Metadata
Write: Contents, Pull requests | Installation token | Concept |
| Auto-remediation — resolve on merge | None (webhook payload only) | n/a | Concept |
| Sandbox source clone (auto-assessment, vulnerability scan, SAST, secrets scan) | Read: Contents, Metadata
(scoped to one repo) | Scoped installation token, 1 h TTL | Vulnerability Management |
| SCM Configuration Check | Read: Administration, Contents, Metadata, Members
(scoped to one repo) | Scoped installation token, 1 h TTL | Branch Protection Policies |
| GitHub Actions OIDC verification | None — public JWKS only | OIDC JWT (no GitHub API call) | Guide |
Scoped vs broad installation tokens
Two features — sandbox source clone and SCM Configuration Check — handle credentials destined for untrusted or short-lived environments. For these, Chainloop mints a scoped installation token narrowed to a single repository, with only the permissions strictly needed for that call, and a 1-hour TTL. The broad installation token is used only for control-plane PR processing and auto-remediation PR creation, where the controlplane itself is the consumer.
After the sandbox clones the repo, it rewrites the origin remote to the bare HTTPS URL so the short-lived credential never persists on disk.
GitHub Enterprise Server (GHES)
Every code path supports GitHub Enterprise Server. The App’s BaseURL and UploadURL switch to <ghes-host>/api/v3 and <ghes-host>/api/uploads, and the clone URL is built from the installation’s host field. The set of requested permissions is identical to github.com.
GitHub Actions workflow permissions
These are the permissions: blocks you add to your own workflow YAML when running Chainloop CLI steps. They are GitHub-native scopes on the workflow’s GITHUB_TOKEN — Chainloop never sees this token directly, it just relies on the OIDC token GitHub mints when id-token: write is set.
Keyless attestations
The minimum block for a workflow that runs chainloop attestation init / push against a keyless-enrolled repository:
permissions:
id-token: write # Mint an OIDC token Chainloop uses to identify your org
| Permission | Why |
|---|
id-token: write | Required for keyless mode — the CLI exchanges the GitHub OIDC token for a Chainloop identity. Without it, the CLI falls back to expecting a CHAINLOOP_TOKEN. |
PR-policies control gate
When attesting pull request metadata for the PR-policies control gate, add read access to repo contents and the PR API:
permissions:
contents: read
id-token: write
pull-requests: read
| Permission | Why |
|---|
contents: read | Lets actions/checkout clone the repo so the CLI can compute commit-related evidence |
id-token: write | Keyless authentication to Chainloop (as above) |
pull-requests: read | Lets the PR-policies materials read PR metadata (author, labels, reviewers) needed by the bundled Rego policies |
SLSA provenance workflows
The SLSA guide workflows use the same id-token: write plus whatever scopes your build steps need (typically contents: read, and packages: write if you’re pushing artifacts). Chainloop itself only requires id-token: write — the other scopes belong to your build, not to Chainloop.
Runner Context (GitHub App or PAT)
Runner Context is a separate, customer-operated integration: you create a GitHub App (or PAT) in your own GitHub account so the Chainloop EE CLI can read repository security configuration during a CI run. This is a different identity from the Chainloop GitHub App above — Chainloop’s servers never see this token; it stays inside your runner.
Runner Context is a Chainloop EE feature. The token is yours, lives in your CI secrets, and is consumed by chainloop gather-runner-context inside the workflow run.
Recommended: Custom GitHub App
Permissions to configure when registering the app:
| Scope | Level | Access | Why |
|---|
| Administration | Repository | Read & Write | GitHub’s API requires write to return ruleset configuration details. The gatherer only reads — it does not modify settings. |
| Contents | Repository | Read | Repository metadata and basic information |
| Members | Organization | Read | Team member information for teams with repository access |
| Administration | Organization | Read | Discover org-level team grants not visible through repo-specific endpoints |
| Custom Organization Roles | Organization | Read | Resolve custom role names to their underlying permissions and base roles |
| Custom Repository Roles | Organization | Read | Resolve custom repository role names |
| Custom Enterprise Roles | Enterprise | Read | Enterprise accounts only. Retrieve enterprise-level custom roles assigned to teams or users |
| Custom Organization Roles | Enterprise | Read | Enterprise accounts only. Resolve enterprise-propagated org role definitions |
Alternative: Personal Access Token
If you can’t use a custom app, a fine-grained PAT works for non-enterprise accounts:
| Scope | Access | Why |
|---|
| Repository: Administration | Read & Write | Required by GitHub’s API for ruleset configuration access (read-only in practice) |
| Repository: Contents | Read | Repository metadata |
| Organization: Members | Read | Team member resolution |
| Organization: Administration | Read | Team access discovery |
read:enterprise scope — fine-grained tokens do not support enterprise-level API endpoints.
Quick summary by product feature
If you’re trying to figure out which permissions a specific Chainloop feature pulls in:
| Feature | Permissions required |
|---|
| Keyless attestations | Workflow id-token: write + Chainloop GitHub App reads Metadata |
| Chainloop Trace PR correlation | Chainloop GitHub App reads Contents, Pull requests; writes Issues, Checks. Subscribes to the pull_request webhook. |
| PR-policies control gate | Workflow contents: read, id-token: write, pull-requests: read |
| SLSA provenance | Workflow id-token: write (plus your own build scopes) |
| Vulnerability auto-remediation | Chainloop GitHub App reads Metadata; writes Contents, Pull requests (broad token). Uses the pull_request webhook for resolve-on-merge. |
| Sandbox-backed agent runs (vulnerability management, SAST, secrets scan) | Chainloop GitHub App reads Contents, Metadata (scoped per-repo token, 1 h TTL) |
| SCM Configuration Check (branch protection policies) | Chainloop GitHub App reads Administration, Contents, Metadata, Members (scoped per-repo token, 1 h TTL) |
| Runner Context | Customer-owned GitHub App or PAT — see above |
