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.
Lettuce ships three first-class git-provider integrations: GitHub App,
GitLab OAuth, and Bitbucket OAuth. They all surface the same
experience in the app — Connect → pick repos → done — but the
operator-side setup is one-time per provider and slightly different.
This page is the one-screen map. Each per-provider page has the click-by-
click setup.
Two ways to add a repo
| Flow | When to use | What you get |
|---|
| Connect a provider | You sign in to GitHub / GitLab / Bitbucket and have repos that live there. | 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 if you want auto-refresh. |
Shared per-account webhook secret
All three providers point at one URL per account, signed by one secret
per account:
{CODEWAZE_PUBLIC_URL}/v1/{provider}/webhook/{account_id}
| 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 |
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. |
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 | Storage | Refresh strategy |
|---|
| GitHub App | Long-lived App PEM on the operator, short-lived installation tokens minted per clone. | No refresh — every clone re-mints. |
| GitLab OAuth | Per-account access + refresh token. Access tokens last ~2h on gitlab.com. | Proactive refresh within 60s of expiry; meta.needs_reauth flagged on failure. |
| Bitbucket OAuth | Per-account access + refresh token. Access tokens last ~2h. | Proactive refresh ~5 min before expiry; meta.needs_reauth flagged on failure. |
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 the user reconnects (the worker has no token
to mint a clone URL).
Disconnect is non-destructive on the provider side — Lettuce simply
forgets the OAuth grant. To fully revoke, the user also removes the App
or OAuth grant from their GitHub / GitLab / Bitbucket settings.
Per-provider setup
- GitHub App — install a GitHub App once, users
pick repos.
- GitLab OAuth — register an OAuth application
on gitlab.com or self-hosted GitLab.
- Bitbucket OAuth — register an OAuth
consumer on a workspace or your personal account.
