GitLab CI for DocsCI

Copy-paste .gitlab-ci.yml templates to run DocsCI on every merge request.

Prerequisites

1.Create a DocsCI account and project at snippetci.com/signup
2.Generate a token from Settings → Tokens
3.Add it as a CI/CD variable named DOCSCI_TOKEN (Settings → CI/CD → Variables, masked)
4.Optional: add GITLAB_TOKEN if you want MR comment posting

Basic workflow

Runs on merge requests and main branch pushes.

.gitlab-ci.ymlYAML

# .gitlab-ci.yml
stages:
  - test

docsci:
  stage: test
  image: alpine:latest
  before_script:
    - apk add --no-cache curl jq tar
  script:
    - tar czf docs.tar.gz docs/ *.md 2>/dev/null || tar czf docs.tar.gz docs/
    - |
      RESULT=$(curl -sf -X POST https://snippetci.com/api/runs/queue \
        -H "Authorization: Bearer $DOCSCI_TOKEN" \
        -F "docs_archive=@docs.tar.gz" \
        -F "branch=$CI_COMMIT_REF_NAME" \
        -F "commit_sha=$CI_COMMIT_SHA")
      echo "$RESULT" | jq .
      echo "$RESULT" | jq -e '.status == "passed"'
  rules:
    - if: '$CI_PIPELINE_SOURCE == "merge_request_event"'
    - if: '$CI_COMMIT_BRANCH == "main"'

Advanced: MR comments + OpenAPI

Posts a note on the merge request with the DocsCI result. Requires a GitLab personal access token with api scope.

.gitlab-ci.yml (advanced)YAML

# .gitlab-ci.yml (advanced with MR notes)
stages:
  - test

docsci:
  stage: test
  image: alpine:latest
  before_script:
    - apk add --no-cache curl jq tar
  script:
    - |
      tar czf docs.tar.gz docs/ 2>/dev/null || \
      find . -name "*.md" -o -name "*.mdx" | tar czf docs.tar.gz -T -
    - |
      RESULT=$(curl -sf -X POST https://snippetci.com/api/runs/queue \
        -H "Authorization: Bearer $DOCSCI_TOKEN" \
        -F "docs_archive=@docs.tar.gz" \
        -F "openapi_url=$OPENAPI_URL" \
        -F "branch=$CI_COMMIT_REF_NAME" \
        -F "commit_sha=$CI_COMMIT_SHA")
      echo "result=$RESULT" > docsci-result.env
      STATUS=$(echo "$RESULT" | jq -r '.status')
      FINDINGS=$(echo "$RESULT" | jq -r '.finding_count')
      RUN_ID=$(echo "$RESULT" | jq -r '.run_id')
      # Post MR note
      if [ -n "$CI_MERGE_REQUEST_IID" ]; then
        ICON=$([ "$STATUS" = "passed" ] && echo "✅" || echo "❌")
        NOTE="$ICON DocsCI: **$STATUS** — $FINDINGS finding(s). [View report](https://snippetci.com/runs/$RUN_ID)"
        curl -sf -X POST \
          "https://gitlab.com/api/v4/projects/$CI_PROJECT_ID/merge_requests/$CI_MERGE_REQUEST_IID/notes" \
          -H "PRIVATE-TOKEN: $GITLAB_TOKEN" \
          -d "body=$NOTE"
      fi
      echo "$RESULT" | jq -e '.status == "passed"'
  artifacts:
    reports:
      dotenv: docsci-result.env
    when: always
  rules:
    - if: '$CI_PIPELINE_SOURCE == "merge_request_event"'
    - if: '$CI_COMMIT_BRANCH == $CI_DEFAULT_BRANCH'

Scheduled nightly run

Add a pipeline schedule in GitLab (CI/CD → Schedules) to run nightly drift detection.

.gitlab-ci.yml (with schedule)YAML

# .gitlab-ci.yml (with scheduled nightly)
docsci-pr:
  stage: test
  image: alpine:latest
  before_script:
    - apk add --no-cache curl jq tar
  script:
    - tar czf docs.tar.gz docs/ *.md 2>/dev/null || tar czf docs.tar.gz docs/
    - |
      curl -sf -X POST https://snippetci.com/api/runs/queue \
        -H "Authorization: Bearer $DOCSCI_TOKEN" \
        -F "docs_archive=@docs.tar.gz" \
      | jq -e '.status == "passed"'
  rules:
    - if: '$CI_PIPELINE_SOURCE == "merge_request_event"'

docsci-nightly:
  stage: test
  image: alpine:latest
  before_script:
    - apk add --no-cache curl jq tar
  script:
    - find . \( -name "*.md" -o -name "*.mdx" \) | tar czf docs.tar.gz -T -
    - |
      RESULT=$(curl -sf -X POST https://snippetci.com/api/runs/queue \
        -H "Authorization: Bearer $DOCSCI_TOKEN" \
        -F "docs_archive=@docs.tar.gz" \
        -F "full_suite=true")
      echo "$RESULT" | jq .
      echo "$RESULT" | jq -e '.status == "passed"'
  rules:
    - if: '$CI_PIPELINE_SOURCE == "schedule"'

GitHub Actions →Migration guide →