GitLab CI Integration

The MergeWhy GitLab CI template lets you report pipeline runs and attestations from GitLab CI pipelines in minutes. Works with both GitLab.com and self-hosted GitLab instances. Evidence is automatically linked to your merge requests.

60-Second Setup

1. Add API key as CI/CD variable

Go to GitLab → Project/Group → Settings → CI/CD → Variables → Add variable:

Key:       MERGEWHY_API_KEY
Value:     <your MergeWhy API key>
Protected: ✓
Masked:    ✓

Get your API key at: MergeWhy → Settings → Developer → API Keys → Create Key

2. Include the template

include:
  - remote: 'https://raw.githubusercontent.com/mergewhy/gitlab-ci-template/main/mergewhy.gitlab-ci.yml'

stages:
  - test
  - security
  - report      # always last

variables:
  MERGEWHY_API_URL: https://app.mergewhy.com

unit-tests:
  stage: test
  image: node:20-alpine
  script:
    - npm ci && npm test

report-unit-tests:
  extends: .mergewhy-report-attestation   # from included template
  stage: report
  needs: [unit-tests]
  variables:
    MERGEWHY_ATTEST_NAME: "unit-tests"
    MERGEWHY_ATTEST_TYPE: "test_results"
    MERGEWHY_ATTEST_STATUS: "$CI_JOB_STATUS"

mergewhy-pipeline:
  extends: .mergewhy-report-run           # from included template
  stage: report
  needs:
    - job: unit-tests
      optional: true

Available Templates

.mergewhy-report-run

Extend to report the completed pipeline. Automatically reads CI_PIPELINE_ID, CI_COMMIT_SHA, CI_MERGE_REQUEST_IID, and other GitLab CI variables.

.mergewhy-report-attestation

Extend to report a test or security attestation. Configure with environment variables:MERGEWHY_ATTEST_NAME, MERGEWHY_ATTEST_TYPE, MERGEWHY_ATTEST_STATUS, and optional numeric fields.