All Docs
GitLab Integration Setup Guide

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 events and build status in Lathe Studio

Connecting GitLab#

Step 1: Create a GitLab Connection in Lathe Studio

  1. In Lathe Studio, open your project and go to Project Settings → Integrations
  2. Find GitLab and click Connect
  3. Lathe Studio generates a webhook URL containing a unique token — copy it

Step 2: Configure the GitLab Webhook

  1. In GitLab, go to your project
  2. Navigate to Settings > Webhooks
  3. Configure:
    • URL: the webhook URL from Lathe Studio (includes ?token=...)
    • Secret Token: your connection's webhook secret (optional — enables request verification)
  4. Trigger events: Select "Pipeline events"
  5. SSL verification: Enable (recommended)
  6. Click Add webhook

Step 3: Test the Integration

  1. Trigger a pipeline in GitLab
  2. Open the GitLab connection panel in Lathe Studio to see recent events
  3. If the pipeline matches a pipeline config with auto-create enabled, a build appears on the Releases page

Authentication#

GitLab webhooks are authenticated by the unique token in the webhook URL (?token=...), which identifies your project's connection. If you set a Secret Token on the GitLab webhook, it must match your connection's webhook secret — GitLab sends it in the X-Gitlab-Token header and Lathe Studio rejects requests with a mismatched token.

How It Works#

  1. Pipeline Completes → GitLab sends the Pipeline Hook to your webhook URL (/api/webhooks/gitlab?token=...)
  2. Authentication → The token identifies your project's connection; if a secret is configured, the X-Gitlab-Token header must match
  3. Pipeline Matching → The pipeline is matched against the pipeline configs on the connection
  4. Build Creation → When the matching pipeline has auto-create enabled (the default), a build is created in your project when the pipeline finishes
  5. Review → Every event is recorded in the connection's recent events list, so you can confirm delivery and troubleshoot

Build Queue UI#

The Build Queue on the Releases page holds builds that arrived without a project or release assignment (for example, from the Bitbucket webhook). From the queue you can:

  • Assign to Release: Select an active release for the project
  • Select Project: Navigate to projects if the project was not auto-detected
  • Reject: Remove the build from the queue (no build created)

GitLab CI Example#

To report test results back to Lathe Studio, create an API key (Settings > Organization > API Keys) with the results:submit scope, add it to your CI/CD variables as PT_API_KEY (masked), then add this to your .gitlab-ci.yml:

The example below posts JSON directly. To send a generated file, use lathe report <file> --project <code> with JUnit XML, TestNG XML (testng-results.xml), NUnit 3 XML, xUnit.net v2 XML, or Cucumber JSON. The CLI detects the format from its contents; --format selects one explicitly. Cypress, Playwright, Postman (Newman), pytest, and Appium-based suites already produce JUnit XML. The ingest API accepts JSON payloads, not raw report files.

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://lathe.studio/api/v1/results/ingest \
        -H "Authorization: Bearer $PT_API_KEY" \
        -H "Content-Type: application/json" \
        -d '{
          "build": {
            "identifier": "Pipeline $CI_PIPELINE_ID",
            "branch": "'"$CI_COMMIT_BRANCH"'",
            "commit_sha": "'"$CI_COMMIT_SHA"'"
          },
          "source": { "pipeline": "gitlab_ci" },
          "results": [
            { "test_identifier": "TC-MOB-0042", "name": "Login works", "status": "passed", "duration_ms": 1200 }
          ]
        }'

If your API key is org-scoped (not tied to one project), also include "project_key": "YOUR-PROJECT-CODE" at the top level of the payload.

Self-Hosted GitLab#

For GitLab self-hosted instances:

  1. Ensure your instance is accessible from the internet
  2. Use the same webhook URL: https://lathe.studio/api/webhooks/gitlab
  3. Configure SSL certificates properly
  4. Allowlist Lathe Studio IP addresses if using a firewall:
    • Contact support for current IP ranges

Troubleshooting#

Builds not appearing

  1. Check webhook delivery in GitLab (Settings > Webhooks > Recent Deliveries)
  2. Verify the webhook URL includes the ?token= query parameter
  3. Ensure "Pipeline events" is selected in webhook settings
  4. Check the connection's recent events in Lathe Studio — if the event arrived but no build was created, the pipeline may not match any configured pipeline config

Rate limiting

Results-ingest API keys are limited to 60 requests per minute by default. Contact support to increase limits.

Self-hosted SSL issues

If using self-signed certificates:

  1. Use valid SSL certificates (Let's Encrypt recommended)
  2. Or disable SSL verification in webhook settings (not recommended for production)

Security#

  • The webhook URL token identifies your project's connection — treat it as a secret
  • Webhook secrets are stored encrypted and verified on each request via the X-Gitlab-Token header
  • Results-ingest API keys are hashed using SHA-256 before storage; only the first 12 characters are kept for identification
  • Keys can be revoked at any time
  • All webhook communications use HTTPS

Unlinking GitLab#

To disconnect:

  1. Go to your GitLab project
  2. Navigate to Settings > Webhooks
  3. Find the Lathe Studio webhook
  4. Click Delete

Note: Previously created builds remain in Lathe Studio. New builds will not be created until reconnected.

Advanced Configuration#

Pipeline Auto-Create

Each pipeline configured on the connection matches events by name and can toggle automatic build creation. When auto-create is off, events are still recorded in the connection's recent events list without creating builds.

For additional help, contact support.

← All DocsSettings →