> ## 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.
# GitHub Permissions
> Every GitHub permission Chainloop requests, where it's requested, and which part of the product uses it.
Chainloop interacts with GitHub in three different places, and each one has its own permission surface. This page is the consolidated reference.
| Integration | Who installs / configures it | Where it's used |
| ------------------------------------------------------------------------------- | --------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
| [Chainloop GitHub App](#chainloop-github-app) | A GitHub org admin, once per repository | Repo enrollment, [keyless attestations](/guides/github-keyless), [Chainloop Trace](/guides/chainloop-trace), [vulnerability auto-remediation](/concepts/vulnerability-management#assessment-and-auto-remediation-using-ai), sandbox-backed agent runs, SCM Configuration Check |
| [GitHub Actions workflow permissions](#github-actions-workflow-permissions) | You, inside your own workflow YAML | [Keyless attestation](/guides/github-keyless), [PR-policies control gate](/guides/pr-policies-control-gate), [SLSA provenance](/guides/slsa) |
| [Custom GitHub App / PAT for Runner Context](#runner-context-github-app-or-pat) | A GitHub org or enterprise admin | [`chainloop gather-runner-context`](/reference/runner-context) (CLI EE) |
## 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](/concepts/vulnerability-management#assessment-and-auto-remediation-using-ai), 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](#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](#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](/guides/chainloop-trace), sandbox clone, [SCM check](/reference/branch-protection-policies), [auto-remediation](/concepts/vulnerability-management#assessment-and-auto-remediation-using-ai) |
| **Pull requests** | Read & Write | Receive PR webhook payloads and read PR metadata (read); open auto-remediation PRs (write) | [Trace](/guides/chainloop-trace), [auto-remediation](/concepts/vulnerability-management#assessment-and-auto-remediation-using-ai) |
| **Issues** | Write | Post and update the Chainloop bot comment on PR conversations (GitHub treats PR conversation comments as issue comments) | [Trace PR summary comment](/guides/chainloop-trace#summary-comment) |
| **Checks** | Read & Write | Publish the `Chainloop AI Policies` check run on the PR head commit | [Trace merge gate](/guides/chainloop-trace#chainloop-ai-policies-check-run) |
| **Administration** | Read | Read branch protection settings and rulesets | [SCM Configuration Check](/reference/branch-protection-policies) |
| **Members** | Read | Detect account type at install time and list org members (including 2FA status) for SCM hardening checks | Install flow, [SCM Configuration Check](/reference/branch-protection-policies) |
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 |
PR processing is further filtered to actions `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](/guides/github-keyless) (repo enrollment) | Read: Metadata | Installation token | [Guide](/guides/github-keyless) |
| [Chainloop Trace](/guides/chainloop-trace) — AI session correlation | Read: Contents, Pull requests
Write: Issues | Installation token | [Guide](/guides/chainloop-trace) |
| [Chainloop Trace](/guides/chainloop-trace) — AI policy check run | Write: Checks | Installation token | [Guide](/guides/chainloop-trace) |
| [Auto-remediation](/concepts/vulnerability-management#assessment-and-auto-remediation-using-ai) — open PR with the fix | Read: Metadata
Write: Contents, Pull requests | Installation token | [Concept](/concepts/vulnerability-management) |
| Auto-remediation — resolve on merge | None (webhook payload only) | n/a | [Concept](/concepts/vulnerability-management) |
| 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](/guides/vulnerability-management) |
| SCM Configuration Check | Read: Administration, Contents, Metadata, Members
*(scoped to one repo)* | **Scoped** installation token, 1 h TTL | [Branch Protection Policies](/reference/branch-protection-policies) |
| [GitHub Actions OIDC verification](/guides/github-keyless) | None — public JWKS only | OIDC JWT (no GitHub API call) | [Guide](/guides/github-keyless) |
### 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 `/api/v3` and `/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](/guides/github-keyless) repository:
```yaml theme={"dark"}
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](/guides/pr-policies-control-gate), add read access to repo contents and the PR API:
```yaml theme={"dark"}
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](/guides/slsa) 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](/reference/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 |
Additional setup: uncheck **Expire user authorization tokens** and **Webhook active** when creating the app. Full step-by-step is in the [Runner Context reference](/reference/runner-context).
### 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 |
**Enterprise GitHub accounts** must use a **Classic PAT** with the additional `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](/guides/github-keyless) | Workflow `id-token: write` + Chainloop GitHub App reads Metadata |
| [Chainloop Trace PR correlation](/guides/chainloop-trace) | Chainloop GitHub App reads Contents, Pull requests; writes Issues, Checks. Subscribes to the `pull_request` webhook. |
| [PR-policies control gate](/guides/pr-policies-control-gate) | Workflow `contents: read`, `id-token: write`, `pull-requests: read` |
| [SLSA provenance](/guides/slsa) | Workflow `id-token: write` (plus your own build scopes) |
| [Vulnerability auto-remediation](/concepts/vulnerability-management) | 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](/guides/vulnerability-management), SAST, secrets scan) | Chainloop GitHub App reads Contents, Metadata (scoped per-repo token, 1 h TTL) |
| SCM Configuration Check ([branch protection policies](/reference/branch-protection-policies)) | Chainloop GitHub App reads Administration, Contents, Metadata, Members (scoped per-repo token, 1 h TTL) |
| [Runner Context](/reference/runner-context) | Customer-owned GitHub App or PAT — see [above](#runner-context-github-app-or-pat) |
## Related Resources
* [Chainloop Trace guide](/guides/chainloop-trace) — full setup walkthrough and PR correlation behavior
* [Keyless attestations in GitHub](/guides/github-keyless) — OIDC-based authentication from GitHub Actions
* [PR-policies control gate](/guides/pr-policies-control-gate) — enforce PR quality with Chainloop policies
* [CI/CD Runner Context](/reference/runner-context) — repository security configuration gathering