Skip to content
docs

GitLab Integration

Authorize Vygl on GitLab.com or your self-hosted GitLab instance to discover projects, register webhooks, and post merge-request comments. The integration uses standard OAuth 2.0 with automatic token refresh.

Install

Section titled “Install”

  1. Open Settings → Connections in Vygl.

  2. Click Connect GitLab. You’re redirected to GitLab’s authorization page.

  3. Authorize. Approve the requested api scope.

  4. Pick projects. GitLab redirects back to Vygl. Select the projects you want scanned.

Webhooks register automatically. Pushes and merge requests trigger scans.

Scopes

Section titled “Scopes”
ScopeWhy
apiFull API access — needed for project metadata, source fetch, MR comments, and webhook CRUD. GitLab doesn’t offer a finer-grained scope that covers this combination.

GitLab tokens have expiries; Vygl refreshes them transparently in the background.

What happens on a push or MR

Section titled “What happens on a push or MR”
  1. GitLab fires a webhook with the push/MR event. Vygl verifies the shared-secret token sent in the X-Gitlab-Token header against the per-repo secret.
  2. Vygl clones the project at the new commit.
  3. Scan engines run server-side.
  4. Findings appear in the dashboard, deduplicated against history.
  5. For merge requests, Vygl posts a fresh summary comment (one per scan) and updates pipeline status.

Branch filtering

Section titled “Branch filtering”

Each project’s scan_config.branches list filters which branch pushes trigger a scan. Patterns are glob (fnmatch) — e.g. main, release/*, * (default). MR scans always run. Today the filter is API-only — no UI yet.

Self-hosted GitLab

Section titled “Self-hosted GitLab”

Self-hosted GitLab Community and Enterprise editions are supported. The base URL is set globally per Vygl deployment via the GITLAB_URL env var — multi-tenant SaaS users are pinned to gitlab.com. For self-hosted, override GITLAB_URL at deploy time and authorize the OAuth app on your instance.

Removing access

Section titled “Removing access”

Teardown has two independent halves — do both for a clean removal:

  • In Vygl — disable a single project, or disconnect the whole provider, from Settings → Connections. See Managing connected repositories.
  • On GitLab — revoke the authorization (User Settings → Applications). Webhook events stop immediately.

Existing scans and findings are retained in Vygl regardless.