GitLab Integration

GitLab provides the immutable anchor (commit_sha) and pipeline context that Quoderat binds to evidence. This page explains the mechanical mapping.

What this page can (and cannot) claim

✓
Claims (Mechanical)

• Immutable anchor: commit_sha is the default subject.id.
• Pipeline context: pipeline_id, job_id, mr_iid are recorded in subject.meta (non-authoritative).
• Runner context: runner_context.runner_type = "ci" when executed inside GitLab CI.
• Back-link option: The evidence_id can be surfaced in MR comments, job logs, or artifacts.

✗
No-claims (Non-normative)

• No automatic MR comments: back-linking is manual or via your own scripts.
• No pipeline enforcement: the envelope does not gate merge or deploy.
• No on-prem guarantees: GitLab self-hosted compatibility is not explicitly validated.
• No integrity lock on Git: envelope integrity is internal; Git history is external.

Mechanical mapping (recommended)

When recording a GitLab-triggered run, populate subject as follows:

subject.kind

"gitlab_commit" (default) or "gitlab_pipeline" (when pipeline-centric)

subject.id

commit_sha — the immutable anchor (40-char hex)

subject.source

"gitlab"

subject.meta

(non-authoritative navigation context)

• project_path — e.g., "group/repo"
• ref — branch or tag name
• pipeline_id — GitLab pipeline ID
• job_id — GitLab job ID
• mr_iid — Merge Request IID (if applicable)

Note: subject.meta is informational; it aids navigation but is not part of the integrity seal.

Example subject block

{
  "subject": {
    "kind": "gitlab_commit",
    "id": "a1b2c3d4e5f6a1b2c3d4e5f6a1b2c3d4e5f6a1b2",
    "source": "gitlab",
    "meta": {
      "project_path": "elk-it/my-service",
      "ref": "main",
      "pipeline_id": "123456",
      "job_id": "789012",
      "mr_iid": "42"
    }
  }
}

Where to surface evidence_id

The evidence_id is the UUID of the finalized envelope. You can back-link it into GitLab for discoverability. Options (non-normative):

MR comment

Post a comment with the envelope ID for human reviewers.

Trade-off: Visible to reviewers; requires API token with MR access.

Job log line

Echo the ID to stdout; it appears in the CI job log.

Trade-off: Always available; requires searching logs to find.

Pipeline artifact

Store the envelope JSON as a CI artifact (e.g., evidence.json).

Trade-off: Durable within GitLab retention policy; artifact size limits apply.

External commit status (optional)

Set a commit status with a link to the envelope viewer.

Trade-off: Visible on MR; requires status API access; URL must be reachable.

Back-linking snippet (illustrative)

Example: post evidence_id as an MR comment or echo to job log.

.gitlab-ci.yml snippet

quoderat_job:
  script:
    - |
      # Run your task and capture evidence_id from Quoderat
      EVIDENCE_ID=$(quoderat run ... --output-id)

      # Option A: Echo to job log
      echo "Evidence Envelope ID: $EVIDENCE_ID"

      # Option B: Post MR comment (requires GITLAB_TOKEN with api scope)
      if [ -n "$CI_MERGE_REQUEST_IID" ]; then
        curl --request POST \
          --header "PRIVATE-TOKEN: $GITLAB_TOKEN" \
          --form "body=Evidence: $EVIDENCE_ID" \
          "$CI_API_V4_URL/projects/$CI_PROJECT_ID/merge_requests/$CI_MERGE_REQUEST_IID/notes"
      fi
  artifacts:
    paths:
      - evidence.json

This is illustrative; adapt to your CI setup and token permissions.

Envelope fields relevant to GitLab

Field	Purpose
`subject.id`	Immutable anchor (commit_sha)
`subject.meta.*`	Non-authoritative navigation context
`runner_context.runner_type`	Reports "ci" when executed in GitLab CI
`artifacts[].location_hints`	Optional pointers to external logs/reports
`integrity.hash_chain`	Seals the envelope (internal integrity)

Next steps

CI/CD — pipeline-to-envelope mapping and recommended setup
Concepts — identity, traceability, canonicalization, integrity
API — programmatic envelope fetch and validation
First Job — complete walkthrough from intent to sealed envelope