GitHub Permissions - Chainloop Documentation

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	A GitHub org admin, once per repository	Repo enrollment, keyless attestations, Chainloop Trace, vulnerability auto-remediation, sandbox-backed agent runs, SCM Configuration Check
GitHub Actions workflow permissions	You, inside your own workflow YAML	Keyless attestation, PR-policies control gate, SLSA provenance
Custom GitHub App / PAT for Runner Context	A GitHub org or enterprise admin	`chainloop gather-runner-context` (CLI EE)

Chainloop GitHub App

The Chainloop GitHub App is the integration installed from Integrations → Connect 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

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 (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

Additional setup: uncheck Expire user authorization tokens and Webhook active when creating the app. Full step-by-step is in the Runner Context reference.

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	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

Chainloop Trace guide — full setup walkthrough and PR correlation behavior
Keyless attestations in GitHub — OIDC-based authentication from GitHub Actions
PR-policies control gate — enforce PR quality with Chainloop policies
CI/CD Runner Context — repository security configuration gathering

​Chainloop GitHub App

​Cumulative permission set

​Subscribed webhook events

​Per-feature breakdown

​Scoped vs broad installation tokens

​GitHub Enterprise Server (GHES)

​GitHub Actions workflow permissions

​Keyless attestations

​PR-policies control gate

​SLSA provenance workflows

​Runner Context (GitHub App or PAT)

​Recommended: Custom GitHub App

​Alternative: Personal Access Token

​Quick summary by product feature

​Related Resources

Chainloop GitHub App

Cumulative permission set

Subscribed webhook events

Per-feature breakdown

Scoped vs broad installation tokens

GitHub Enterprise Server (GHES)

GitHub Actions workflow permissions

Keyless attestations

PR-policies control gate

SLSA provenance workflows

Runner Context (GitHub App or PAT)

Recommended: Custom GitHub App

Alternative: Personal Access Token

Quick summary by product feature

Related Resources