Skip to main content

GitLab CI

vybdocs integrates with GitLab CI through .gitlab-ci.yml. The check runs on every merge request and produces Evidence Pack artifacts that GitLab stores for the configured retention period.

Basic pipeline​

.gitlab-ci.yml
stages:
  - check

vyb-check:
  stage: check
  image: node:24-alpine
  rules:
    - if: '$CI_PIPELINE_SOURCE == "merge_request_event"'
    - if: '$CI_COMMIT_BRANCH == $CI_DEFAULT_BRANCH'
  script:
    - npm ci
    - npx @vybdocs/vyb check --base origin/$CI_MERGE_REQUEST_TARGET_BRANCH_NAME --ci
  artifacts:
    when: on_success
    paths:
      - .vyb/evidence/
    expire_in: 1 year

With SAST report integration​

GitLab supports SAST reports in JSON format. vybdocs can output a compatible format:

vyb-check:
  stage: check
  image: node:24-alpine
  script:
    - npm ci
    - |
      npx @vybdocs/vyb check \
        --base origin/$CI_MERGE_REQUEST_TARGET_BRANCH_NAME \
        --output-format gitlab-sast \
        --output vyb-sast.json || true
  artifacts:
    reports:
      sast: vyb-sast.json
    paths:
      - .vyb/evidence/
    when: always
    expire_in: 1 year

With this configuration, violations appear in the GitLab Security Dashboard and as inline annotations on merge request diffs.

Evidence Pack as a compliance artifact​

For regulated environments, configure a dedicated job to archive Evidence Packs on every main branch merge:

archive-evidence:
  stage: archive
  image: node:24-alpine
  rules:
    - if: '$CI_COMMIT_BRANCH == $CI_DEFAULT_BRANCH'
  dependencies:
    - vyb-check
  script:
    - echo "Evidence Pack archived as GitLab artifact"
  artifacts:
    paths:
      - .vyb/evidence/
    expire_in: 7 years    # SOC 2 requires 1 year; keep 7 for safety

Cache for speed​

vyb-check:
  cache:
    key:
      files:
        - package-lock.json
    paths:
      - node_modules/
      - .npm/
  script:
    - npm ci --cache .npm --prefer-offline
    - npx @vybdocs/vyb check --ci

Merge request approval rule​

In GitLab Ultimate, add vyb-check as a required approval check:

  1. Go to Settings → Merge requests → Approval rules
  2. Add a rule: vybdocs Check — require 0 approvals (the CI job itself is the gate)
  3. Enable Pipelines must succeed

This prevents merge even if all human approvals are given, as long as vyb check is failing.

Next: Evidence Pack Overview