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

# Connect GitLab

> Authorize Pipefort to read your GitLab projects and open MRs via OAuth.

Pipefort uses a per-user GitLab OAuth token (managed via Supabase) to read your
project CI configuration and open Merge Requests for auto-fixable findings.
This page walks through the gitlab.com SaaS path; for self-hosted instances see
[Self-hosted GitLab](/webapp/self-hosted-gitlab).

## What gets scanned

| Path                                                    | Scanned                              |
| ------------------------------------------------------- | ------------------------------------ |
| `.gitlab-ci.yml` (repo root)                            | ✓                                    |
| `.gitlab-ci/**/*.yml` and `*.yaml`                      | ✓                                    |
| Files referenced by `include:` from other projects/URLs | ✗ (v1 limitation — track in roadmap) |

Project-side settings (Protected Branches, Push rules, Secret Detection) are
not yet audited from GitLab — only the YAML pipeline definitions. The GitHub
equivalent of these audits is shipped and will follow on the GitLab side in a
later release.

## One-time OAuth app registration (operator)

If you self-host the Pipefort backend, register a GitLab OAuth application
that all of your users will sign in through:

1. Go to **gitlab.com → User settings → Applications** (or your instance's
   Admin Area → Applications for a tenant-wide app).
2. Set the **Redirect URI** to your Supabase project's auth callback:
   * Local dev (Supabase CLI): `http://127.0.0.1:54421/auth/v1/callback`
   * Managed Supabase: `https://<project>.supabase.co/auth/v1/callback`
3. Tick the scopes Pipefort needs: `api`, `read_api`, `read_user`,
   `write_repository`.
4. Copy the resulting Application ID and Secret into your environment as
   `SUPABASE_AUTH_EXTERNAL_GITLAB_CLIENT_ID` and
   `SUPABASE_AUTH_EXTERNAL_GITLAB_SECRET`. The Go API also reads these to
   handle OAuth token refresh.

## User flow

1. From the Pipefort sign-in page, click **Sign in with GitLab**.
2. GitLab asks you to authorize Pipefort with the scopes above.
3. You land on `/connect/callback`. The SPA reads the access + refresh token
   off the Supabase session and POSTs them to `/api/gitlab/callback`, which
   persists them to a service-role-only `user_oauth_tokens` table.
4. You're redirected to the dashboard with your GitLab projects listed,
   tagged with a GitLab badge.

## Open fix MR

For findings whose rule appears in the auto-fix list (debug-trace,
allow-failure, missing-timeout in v1), the per-finding **Open fix MR** button
runs the same scanner.FixBytes rewrite locally on the API side, then opens
(or reuses) a Merge Request from the deterministic branch
`pipefort/fix/<rule-id>/<file-slug>`. Re-clicking the same finding
short-circuits to the existing MR instead of opening a duplicate.

## Removing access

Revoking access is two-sided:

* **GitLab side**: User settings → Applications → Authorized Applications →
  remove Pipefort. Existing tokens stop working immediately.
* **Pipefort side**: the token row in `user_oauth_tokens` is keyed on
  `(user_id, provider, host)` and is removed automatically when the user
  re-authorizes; an explicit delete endpoint is on the roadmap.