spectracebeta

Connect GitLab

Connect GitLab, map a repository to a Spectrace project, and verify merge requests against requirements.

This page shows you how to connect GitLab, link a repository to a Spectrace project, and confirm that merge-request verification is working.

What the GitLab integration does

Once a GitLab repository is mapped to a project, Spectrace installs a project webhook and watches its merge requests. A qualifying merge-request event queues the same requirement-to-code verification pipeline used for pull requests, stores the result in Spectrace, posts or updates a GitLab note, and publishes a commit status on the merge request's head commit.

The integration responds when a merge request opens, reopens, receives a new push, or has a material title, description, source-branch, or target-branch edit. Approval-only events do not start a run. Merging a resolved merge request moves its requirement to Done and runs the existing external status-sync flow.

Prerequisites

  • You are an owner or admin of the Spectrace workspace. Members can see the connection and existing mappings, but cannot connect GitLab, map repositories, or remove mappings.
  • The GitLab account authorizing Spectrace has Maintainer access to the repository. Spectrace needs that access to install the project webhook.
  • Your Spectrace deployment has GitLab OAuth and webhook settings configured. Self-managed GitLab is supported, but one Spectrace deployment currently targets one GitLab instance. Deployment settings are listed under Environment variables.
  • Production webhook registration needs a public HTTPS NEXT_PUBLIC_APP_URL. On localhost or plain HTTP, Spectrace keeps the mapping but reports that the webhook still needs public HTTPS.

Connect while creating a project

  1. Open the Repository step

    Create a project and continue to step 4, Repository. Choose the GitLab tab. If GitLab is already connected, Spectrace lists repositories where the connected account has Maintainer access.

  2. Connect GitLab if needed

    Click Connect GitLab and approve the api and read_user scopes. Spectrace returns to the new-project wizard with the GitLab tab selected; the project form remains available.

  3. Choose the repository

    Filter by namespace or name, then select one repository. Click Create project. Spectrace creates the project, stores the repository mapping, and installs the merge-request webhook.

If repository linking fails after creation — for example, because Maintainer access was removed — Spectrace opens the new project's Integrations settings and shows the failure there. The project itself is not discarded.

Open the project, click Settings, and choose Integrations → GitLab.

  • If the workspace is not connected, an owner or admin can click Connect GitLab. OAuth returns to the same project with the Integrations section open.
  • If GitLab is connected, choose an available repository and click Link GitLab Repository.
  • A linked repository shows its namespace, a link back to GitLab, and either webhook active or webhook needs public HTTPS.
  • Use the unlink control to remove the mapping. Spectrace also removes the GitLab webhook when the token and webhook are still available.

One GitLab repository can map to only one Spectrace project for the configured GitLab instance. The picker hides repositories already mapped to another project.

Manage mappings for the workspace

Owners and admins can also open Settings → Integrations → GitLab. The workspace-wide mapping table pairs a GitLab repository with a Spectrace project and lists every existing mapping. This is useful when several projects need to be mapped without opening each project separately.

Connecting GitLab is also offered during onboarding. That step creates the workspace connection; map the repository from project creation, Project settings, or the workspace-wide table.

Permissions and stored access

Spectrace requests the GitLab OAuth scopes api and read_user. The api scope is required to list Maintainer repositories, read merge-request diffs, install and remove project webhooks, post notes, and publish commit statuses. Access and refresh tokens are encrypted before storage.

Only Spectrace workspace owners and admins can change the organization-wide connection or repository mappings. The server repeats that authorization check for every connect, link, unlink, and disconnect action; hiding a button in the interface is not the security boundary.

What done looks like

The project integration card shows the GitLab namespace and webhook active. Opening a merge request whose branch, title, or description names a requirement produces a Spectrace note and a commit status, and the requirement's PR verification tab records the run.

If the card says webhook needs public HTTPS, the mapping exists but GitLab cannot notify this Spectrace deployment. Configure a public HTTPS app URL, then remap the repository to install the hook.

If no repositories appear, confirm that the connected GitLab user has Maintainer access and reconnect GitLab if its token has expired. A repository already mapped elsewhere is intentionally unavailable.

Current limitations

  • GitLab repository indexing and automatic requirement extraction are not supported yet. Those controls appear only for GitHub repositories.
  • GitLab issue-to-requirement synchronization is not implemented.
  • The VS Code extension does not create GitLab branches or merge requests.
  • Spectrace posts merge-request notes and commit statuses, but does not perform native GitLab approve or request-changes actions.
  • Group-level webhooks, an installation-style GitLab bot, and multiple GitLab instances per Spectrace deployment are not supported.