Connect GitLab

Connect GitLab.com via OAuth at Settings → Sources, import projects, and enable merge-request checks with External Status Checks.

Purpose

Connect GitLab.com projects so CodeCleared can import and scan authorized code.

Who

GitLab project maintainers and CodeCleared organization owners or admins.

Prerequisites

You need a GitLab.com account that can authorize OAuth for the projects you import, plus access to the destination CodeCleared organization. Merge-request checks require a GitLab Premium or Ultimate plan (External Status Checks).

How it works

Open Settings → Sources and connect GitLab with OAuth.
Select the CodeCleared organization.
Import the projects shown.
On import, CodeCleared registers project webhooks automatically (push and merge-request events). If setup fails, the import still succeeds and returns setupWarning; the UI retries once via POST /repositories/:id/action with { "action": "setup-vcs" }. You can also retry that action from the repository page. Re-import cannot fix this (the repo already exists).
When GitLab Premium/Ultimate allows it, CodeCleared also registers the five External Status Checks used for MR checks (each with a unique notify URL).

When you import, CodeCleared sets the repository default branch from GitLab’s configured default branch. You can change that value later in repository configuration if needed.

Business rules

Only gitlab.com is supported (self-managed GitLab is not). Repository visibility follows the OAuth grant and selected organization. Private or external repositories can require a product PAT when OAuth access is insufficient. MR checks use External Status Checks and need GitLab Premium or Ultimate; without that plan, import and scans still work, but MR status checks are not created.

Scenarios & edge cases

Project missing: OAuth access is limited or the wrong organization is selected. Private/external repo: provide a product PAT only when the app asks for it. MR checks missing: confirm Premium/Ultimate and that External Status Checks were registered for the project. Import succeeded but no webhooks: use Retry VCS setup on the repository (or the automatic post-import retry). Reconnecting OAuth alone does not re-register hooks. On local/dev, GitLab.com rejects localhost webhook URLs — the platform must expose a public HTTPS API_PUBLIC_URL (tunnel) before setup can succeed. Non-main default branch: import still uses GitLab’s default (for example develop or master).

Limits

CodeCleared cannot import projects GitLab does not expose to the connected account. Self-managed and GitLab Dedicated instances are out of scope.

Common errors

Selecting an organization after importing.
Expecting MR checks without GitLab Premium/Ultimate (External Status Checks).
Expecting every import to default to main regardless of GitLab settings.
Assuming self-managed GitLab works the same as gitlab.com.
Local/dev API on localhost — GitLab returns Invalid url given until API_PUBLIC_URL is a public HTTPS URL.