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

# Self-hosted GitLab

> Connect Pipefort to a self-hosted GitLab instance instead of gitlab.com.

Pipefort treats the GitLab host as a per-installation value. Each row in
`installations` carries a `host` column (`gitlab.com` for SaaS, `gitlab.acme.com`
for your instance) so a single deployment of the backend can hold
installations across multiple hosts for the same user.

## What changes vs gitlab.com

* The OAuth app is registered on **your GitLab instance**, not gitlab.com.
* The API base URL becomes `https://<your-host>/api/v4`.
* The Supabase **provider config** in `supabase/config.toml` can only point
  to one host at a time. For multi-host deployments we use a Go-side OAuth
  code flow fallback — see below.

## Register the OAuth application

In your GitLab instance:

1. **Admin Area → Applications → New application** (or **User settings →
   Applications** for a per-user app).
2. Redirect URI: `https://<your-pipefort-host>/connect/callback`.
3. Scopes: `api`, `read_api`, `read_user`, `write_repository`.
4. Copy the Application ID and Secret.

## Configure the backend

The Go API needs both the OAuth credentials and a hint about the default
host:

```bash theme={null}
SUPABASE_AUTH_EXTERNAL_GITLAB_CLIENT_ID=<application id>
SUPABASE_AUTH_EXTERNAL_GITLAB_SECRET=<application secret>
GITLAB_OAUTH_REDIRECT_URI=https://<your-pipefort-host>/connect/callback
# Used as the default host for new installations and for `pipefort -g` URLs
# that don't carry an https://host/ prefix.
GITLAB_DEFAULT_HOST=gitlab.acme.com
```

`docker-compose.yml` already passes these through to the API container; the
Vercel functions read the same env at cold-start.

## Single-host vs multi-host

| Mode                              | When to use                                                   | How it works                                                                                                                                                                   |
| --------------------------------- | ------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
| Single-host via Supabase provider | Operator runs one Pipefort deployment per GitLab instance     | Add `url = "https://gitlab.acme.com"` to `[auth.external.gitlab]` in `supabase/config.toml`                                                                                    |
| Multi-host via Go-side OAuth      | One Pipefort deployment must talk to two or more GitLab hosts | Leave `url = ""` in Supabase. The SPA stashes the host the user chose in `sessionStorage`, the API issues OAuth code exchanges to whichever host the installation row carries. |

## User flow

The Connect page exposes a **"Use a self-hosted GitLab instance"** expander
that lets the user type the host (e.g. `gitlab.acme.com`) before clicking
**Continue with GitLab**. The chosen host travels through
`sessionStorage` to the callback and ends up on the `installations.host`
column.

## Limitations in v1

* Project-settings auditing (Protected Branches, Push rules, Secret
  Detection) is GitHub-only. The GitLab equivalents are on the roadmap.
* `include:` graph traversal is not performed; only literal
  `.gitlab-ci.yml` and `.gitlab-ci/**/*.yml` files are inspected.
* Multi-tenant self-hosted (one Pipefort deployment serving customers across
  *different* self-hosted GitLab instances with separate OAuth apps) requires
  the Go-side OAuth fallback path. Per-tenant OAuth app registration is on
  the roadmap.