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

# Repository Integration

> Connect GitHub or GitLab so Chainloop can list repositories, run managed workflows, and act on your pull and merge requests.

<Note>
  This feature is only available on Chainloop's platform [paid plans](https://chainloop.dev/pricing).
</Note>

**Repository Integration** connects a Chainloop organization to a source-code provider so Chainloop can list your repositories, onboard projects and workflows from them, and act on their pull/merge requests. This page is the entry point; it links out to the detailed setup, permissions, and attestation guides.

<Note>
  Only **GitHub** and **GitLab** are supported. Other providers (e.g. Bitbucket) are not available.
</Note>

## What you get, tier by tier

The integration's capabilities are layered — they are **not** all enabled the moment you connect. **Connecting alone scans nothing.**

| Tier                    | Action                                                                                                                              | What it enables                                                                                                                                                     |
| ----------------------- | ----------------------------------------------------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| **1. Connect**          | Install the GitHub App (GitHub) or register a connection with an access token (GitLab), from **Integrations** (one-time, org-level) | Chainloop can **list** your repositories, live from the provider. Nothing runs yet.                                                                                 |
| **2. Managed delivery** | Link a repository to a project and set its delivery mode to **Managed**                                                             | Chainloop **auto-creates and runs** the scanning workflows (SAST, secret, vulnerability, IaC, GitHub-Actions, SCM-configuration-check), server-side, no CI changes. |
| **3. PR/MR events**     | (Automatic once connected)                                                                                                          | On each pull/merge request, Chainloop can post a **summary comment** and publish **checks/statuses**. See the table below for provider differences.                 |

See [Built-in & Managed Workflows](/get-started/projects/managed-workflows) for delivery modes, and [Connect GitHub & GitLab](/guides/connect-repository) for the hands-on connect flow.

## GitHub vs. GitLab

The two providers are genuinely asymmetric. The essentials:

| Aspect                              | GitHub                                                                   | GitLab                                                                                                      |
| ----------------------------------- | ------------------------------------------------------------------------ | ----------------------------------------------------------------------------------------------------------- |
| Auth model                          | GitHub **App** (installation tokens)                                     | **Access token** (personal, group, or service-account) with the `api` scope                                 |
| Connect action                      | Install the App                                                          | Register a connection with a host + access token                                                            |
| Repository visibility               | Repos **selected at install time** (installation-scoped)                 | Projects the token can access at **Developer** level or above, **shared org-wide** to all Chainloop members |
| Webhooks                            | Auto-provisioned by the App                                              | Chainloop registers a **per-project** hook on link, and removes it on disconnect                            |
| Webhook verification                | `X-Hub-Signature-256` (HMAC-SHA256)                                      | `X-Gitlab-Token` shared secret (auto-generated on install)                                                  |
| Managed workflows                   | GA                                                                       | GA                                                                                                          |
| PR/MR summary comment               | Posted as a **PR comment** (when AI traces are present)                  | Posted as an **MR note**; identical content                                                                 |
| PR quality checks (`pr-validation`) | Runs when a **managed `pr-validation` workflow** is enabled              | Same                                                                                                        |
| Check surface                       | Rich **Check Runs** (`Chainloop AI Policies`, `Chainloop PR Validation`) | **Commit statuses** (GitLab has no Check Runs) — pass/fail + link; full detail lives in the MR note         |
| Multiple connections                | one `github_app` per instance                                            | **multiple** token connections per org (different hosts, or distinct tokens for the same host)              |
| Self-managed host                   | GHES via `baseUrl`                                                       | self-managed via the connection's **host**                                                                  |

## Configuration

Configuration splits by **audience**, not by product edition:

<Tabs>
  <Tab title="Everyone (connect a repository)">
    On both Chainloop Cloud and self-hosted instances, an org admin connects the provider from **Integrations**, then links repositories to projects and picks a delivery mode. This is the same flow everywhere.

    See [Connect GitHub & GitLab](/guides/connect-repository).
  </Tab>

  <Tab title="On-prem operators (GitHub prerequisite)">
    On a self-hosted instance, an operator must first **create your own** GitHub App and wire it via Helm **before** the GitHub connect flow becomes available to org admins. **GitLab needs no operator setup** — connections are registered at runtime with an access token.

    * [GitHub App (self-hosted)](/guides/deployment/guides/github-app) — app creation + `backend.githubApp` Helm values.
    * [GitLab integration (self-hosted)](/guides/deployment/guides/gitlab-app) — no prerequisite; optional `backend.gitlab.webhookSecret` (auto-generated).
  </Tab>
</Tabs>

## Must-knows

<Note>
  **Connecting alone scans nothing.** You must link a repository to a project **and** choose **Managed** delivery mode for any workflow to run.
</Note>

* **PR feedback is gated.** The AI-trace summary comment only appears when there are AI coding sessions/traces (or a `pr-validation` run). PR quality checks only run when a **managed** `pr-validation` workflow exists.
* **GitLab connections are org-wide and token-backed.** Every Chainloop org member operates through the access token registered for the connection, so use a **group or service-account** token (not a personal one) to avoid tying access to an individual. Visible projects are those the token can reach at **Developer** level or above. You can register multiple connections per org.
* **On-prem has a GitHub operator prerequisite.** Until an operator creates the GitHub App and sets its Helm values, the GitHub connect flow does not appear. GitLab has no such step.
* **Built-in templates are hidden in the on-prem UI.** Self-hosted installs don't surface Chainloop's built-in workflow templates in the UI. You can manage custom, org-scoped templates via the CLI (`chainloop apply -f`), but only in **Manual** delivery mode.

## Related guides

<CardGroup cols={2}>
  <Card title="Connect GitHub & GitLab" icon="code-branch" href="/guides/connect-repository">
    The hands-on connect flow.
  </Card>

  <Card title="Built-in & Managed Workflows" icon="gear" href="/get-started/projects/managed-workflows">
    Delivery modes and what managed workflows do.
  </Card>

  <Card title="GitHub App (self-hosted)" icon="github" href="/guides/deployment/guides/github-app">
    Create the app and set Helm values.
  </Card>

  <Card title="GitLab integration (self-hosted)" icon="gitlab" href="/guides/deployment/guides/gitlab-app">
    Token-based connections; no operator setup.
  </Card>

  <Card title="GitHub permissions" icon="key" href="/reference/github-permissions">
    Exact scopes the Chainloop GitHub App requests.
  </Card>

  <Card title="GitHub keyless attestation" icon="shield" href="/guides/github-keyless">
    Attest from GitHub Actions via OIDC.
  </Card>

  <Card title="GitLab keyless attestation" icon="shield" href="/guides/gitlab-keyless">
    Attest from GitLab CI via OIDC.
  </Card>

  <Card title="Integrations catalog" icon="puzzle-piece" href="/concepts/integrations">
    All Chainloop integrations.
  </Card>
</CardGroup>