> ## Documentation Index
> Fetch the complete documentation index at: https://recipe.uselettuce.dev/llms.txt
> Use this file to discover all available pages before exploring further.

# Integrations overview

> How Lettuce connects to your organization's GitHub, GitLab, and Bitbucket — what each provider asks you to authorize, and how the per-account webhook signing works.

Lettuce ships three first-class git-provider integrations: **GitHub App**,
**GitLab OAuth**, and **Bitbucket OAuth**. As the admin connecting your
organization to Lettuce, you'll see the same shape for all three —
**Connect → authorize → pick repos → done**.

This page is the one-screen map of what each provider asks for and what
Lettuce does with it. Each per-provider page walks you through the
click-by-click connect flow.

## Two ways to add a repo

| Flow                   | When to use                                                        | What you get                                                                                                                             |
| ---------------------- | ------------------------------------------------------------------ | ---------------------------------------------------------------------------------------------------------------------------------------- |
| **Connect a provider** | Your team's repos live on GitHub / GitLab / Bitbucket.             | A picker of every repo Lettuce can see, one-click add, push webhooks wired automatically.                                                |
| **Paste a git URL**    | Public repos, mirrors, anything that isn't on the three big hosts. | Manual `git clone` over HTTPS. Webhooks are off by default — wire them up via [Add a webhook](/cloud/overview) if you want auto-refresh. |

The two paths coexist. Even with all three providers connected, the
*Other (paste URL)* tab in the Add-repo dialog stays available for the
long tail.

## Shared per-account webhook secret

All three providers point at one URL per account, signed by one secret
per account:

```
https://diet.uselettuce.dev/v1/{provider}/webhook/{account_id}
```

The secret is auto-generated the first time your account adds a repo (or
opens the *Webhook* card under Account settings). Lettuce stores it once
and reuses it for every repo on every provider — so adding a fourth repo
to your GitHub install doesn't generate yet another secret to copy
around.

Signature schemes differ:

| Provider  | Header                | Algorithm                                    |
| --------- | --------------------- | -------------------------------------------- |
| GitHub    | `X-Hub-Signature-256` | HMAC-SHA256 over the request body            |
| GitLab    | `X-Gitlab-Token`      | Literal token compare (GitLab does not HMAC) |
| Bitbucket | `X-Hub-Signature`     | HMAC-SHA256 over the request body            |

Lettuce verifies the appropriate header for each delivery before doing
any work, so a forged delivery is rejected with `401`.

## Scopes at a glance

| Provider        | Scope / permission | Why                                                      |
| --------------- | ------------------ | -------------------------------------------------------- |
| GitHub App      | `contents:read`    | Read repo contents for clone + index.                    |
| GitHub App      | `metadata:read`    | List repos visible to the installation.                  |
| GitHub App      | `webhooks:write`   | Register the per-account push hook.                      |
| GitLab OAuth    | `api`              | OAuth-bound REST access (list projects, register hooks). |
| GitLab OAuth    | `read_repository`  | Git-over-HTTPS clone access.                             |
| GitLab OAuth    | `write_repository` | Required to register the push webhook.                   |
| Bitbucket OAuth | `repository`       | Read-only repo + clone access.                           |
| Bitbucket OAuth | `webhook`          | Register the push webhook on each added repo.            |

Lettuce never asks for write access to your code. The GitLab
`write_repository` scope is a quirk of GitLab's permission model — it's
needed only because the webhook-registration API is gated by it. We
don't push commits.

## Token lifecycle

| Provider        | What's stored on your account                                                                          | Refresh strategy                                                                                    |
| --------------- | ------------------------------------------------------------------------------------------------------ | --------------------------------------------------------------------------------------------------- |
| GitHub App      | The installation Lettuce holds against your org. Each clone re-mints a short-lived installation token. | No refresh needed — every clone re-mints.                                                           |
| GitLab OAuth    | Per-account access + refresh token. Access tokens last \~2h on gitlab.com.                             | Proactive refresh within 60s of expiry; the UI flags a **Reconnect** prompt if refresh ever fails.  |
| Bitbucket OAuth | Per-account access + refresh token. Access tokens last \~2h.                                           | Proactive refresh \~5 min before expiry; the UI flags a **Reconnect** prompt if refresh ever fails. |

If you (or another admin on your team) revoke Lettuce on the provider
side, or the upstream rotates secrets, the Add-repo dialog and the
**Settings → Connected integrations** row both surface a **Reconnect**
prompt instead of failing the whole add-repo flow.

## Disconnect

Owners can disconnect any provider from **Settings → Connected
integrations**. Existing repos keep their git URLs:

* Public repos still re-clone on schedule.
* Private repos break until you reconnect (Lettuce no longer has a token
  to mint a clone URL).

Disconnect is non-destructive on the provider side — Lettuce simply
forgets the OAuth grant. To fully revoke, also remove the App or OAuth
grant from your GitHub / GitLab / Bitbucket settings.

## Per-provider setup

* [GitHub App](/integrations/github) — install the Lettuce GitHub App
  on your org, pick repos.
* [GitLab OAuth](/integrations/gitlab) — authorize Lettuce on your
  GitLab account, pick projects.
* [Bitbucket OAuth](/integrations/bitbucket) — grant Lettuce access on
  Bitbucket, pick repos across workspaces.

<Note>
  **Self-hosted admin note.** If you run Lettuce inside your own
  infrastructure, the one-time registration of each provider's App /
  OAuth client lives in [Self-hosted install](/self-hosted/install) (§5).
  On Lettuce Cloud you don't have to think about that — the per-provider
  pages below describe what an org admin clicks through on the SaaS.
</Note>