GitLab Integration Setup Guide

This guide walks you through connecting Lathe Studio to GitLab for CI/CD pipeline integration.

Prerequisites#

GitLab account (GitLab.com or self-hosted)
GitLab project with CI/CD pipelines
Project admin access in Lathe Studio

Overview#

The GitLab integration enables:

CI/CD Webhooks: Automatically create builds when GitLab pipelines complete
Pipeline Visibility: View pipeline status in Lathe Studio
Merge Request Integration: Display test results in MRs

Connecting GitLab#

Step 1: Create an API Key

Go to Settings > Organization > API Keys
Click Create API Key
Give it a name (e.g., "GitLab CI")
Select scopes:
- builds:read - View builds
- builds:create - Create new builds
Copy the generated key (shown only once)

Step 2: Configure GitLab Webhook

In GitLab, go to your project
Navigate to Settings > Webhooks
Configure:
- URL: https://lathestudio.dev/api/webhooks/gitlab
- Secret Token: Your API key (optional, for verification)
Trigger events: Select "Pipeline events"
SSL verification: Enable (recommended)
Click Add webhook

Step 3: Test the Integration

Trigger a pipeline in GitLab
Go to Releases page in Lathe Studio
You should see the build in the Build Queue section
Assign it to a release

Authentication Methods#

Method 1: API Key in Header (Recommended)

GitLab sends the secret token in the X-Gitlab-Token header. Add your API key there:

Secret Token: pt_live_xxxxxxxxxxxxxxxx

Method 2: Authorization Header

Configure a custom header:

Name: Authorization
Value: Bearer pt_live_xxxxxxxxxxxxxxxx

Method 3: Organization ID

Include your organization ID:

Name: X-Pt-Org-Id
Value: your-org-uuid

How It Works#

Pipeline Completes → GitLab sends webhook to /api/webhooks/gitlab
Authentication → Webhook verifies API key or org ID
Project Matching → System tries to match project URL to a Lathe Studio project
Queue or Create:
- If project + active release found → Build created directly
- If project found but no release → Queued for release assignment
- If no project match → Queued for project + release assignment
Assignment → User assigns queued builds via Releases page

Build Queue UI#

The Build Queue appears on the Releases page when there are pending builds:

Shows build name, source (GitLab), project, commit/branch
Assign to Release: Select an active release for the project
Select Project: Navigate to projects if project not auto-detected
Reject: Remove build from queue (no build created)

GitLab CI Example#

Add this to your .gitlab-ci.yml:

stages:
  - test
  - report

test:
  stage: test
  script:
    - npm test
  artifacts:
    reports:
      junit: test-results.xml

notify-lathe-studio:
  stage: report
  only:
    - main
    - develop
  script:
    - |
      curl -X POST https://lathestudio.dev/api/v1/results/ingest \
        -H "Authorization: Bearer $PT_API_KEY" \
        -H "Content-Type: application/json" \
        -d '{
          "build_name": "Pipeline $CI_PIPELINE_ID",
          "branch": "'"$CI_COMMIT_BRANCH"'",
          "commit_sha": "'"$CI_COMMIT_SHA"'",
          "test_results": [...]
        }'

Self-Hosted GitLab#

For GitLab self-hosted instances:

Ensure your instance is accessible from the internet
Use the same webhook URL: https://lathestudio.dev/api/webhooks/gitlab
Configure SSL certificates properly
Allowlist Lathe Studio IP addresses if using a firewall:
- Contact support for current IP ranges