Add GitLab CI scanner integration template

docs/gitlab-ci.md

@@ -0,0 +1,55 @@
+# GitLab CI Integration
+
+Use the ISNAD scanner in GitLab CI to check AI skills, prompts, and agent configs before they are merged or deployed.
+
+## Template
+
+Copy `examples/gitlab/.gitlab-ci.yml` into your GitLab project root, then adjust the scan targets for your repository:
+
+```yaml
+variables:
+  ISNAD_SCAN_TARGETS: "skills/**/*.js prompts/**/*.md configs/**/*.json"
+  ISNAD_SCAN_OUTPUT: "isnad-scan-results.json"
+  ISNAD_SCAN_FAIL_FAST: "false"
+```
+
+The job runs on merge requests and on the default branch. It stores the JSON scan result as a pipeline artifact for review.
+
+## Scan Targets
+
+Set `ISNAD_SCAN_TARGETS` to one or more shell globs. Keep them focused on files that contain executable agent behavior or instructions:
+
+- `skills/**/*.js`
+- `skills/**/*.ts`
+- `prompts/**/*.md`
+- `agents/**/*.json`
+- `configs/**/*.yaml`
+
+## JSON And Security Dashboard Output
+
+The template runs the scanner with `--json` and writes the output to `ISNAD_SCAN_OUTPUT`. GitLab keeps that file as an artifact and also receives it through `artifacts:reports:sast`.
+
+If your GitLab instance requires strict GitLab SAST schema output, keep the JSON artifact enabled and add a conversion step after the scanner command. The raw scanner output remains available for auditors and merge reviewers.
+
+## Fail-Fast Mode
+
+Set `ISNAD_SCAN_FAIL_FAST=true` when you want the scanner to stop on the first high-risk finding:
+
+```yaml
+variables:
+  ISNAD_SCAN_FAIL_FAST: "true"
+```
+
+## Example Pipeline
+
+```yaml
+include:
+  - local: examples/gitlab/.gitlab-ci.yml
+
+variables:
+  ISNAD_SCAN_TARGETS: "agent-skills/**/*.js system-prompts/**/*.md"
+  ISNAD_SCAN_OUTPUT: "gl-isnad-scan.json"
+```
+
+For a standalone project, copy the template instead of using `include: local`.
+

examples/gitlab/.gitlab-ci.yml

@@ -0,0 +1,34 @@
+stages:
+  - security
+
+variables:
+  ISNAD_SCAN_TARGETS: "skills/**/*.js prompts/**/*.md configs/**/*.json"
+  ISNAD_SCAN_OUTPUT: "isnad-scan-results.json"
+  ISNAD_SCAN_FAIL_FAST: "false"
+
+isnad_scan:
+  stage: security
+  image: node:20-alpine
+  before_script:
+    - npm install -g @isnad/scanner
+  script:
+    - |
+      set -eu
+
+      scan_args="batch ${ISNAD_SCAN_TARGETS} --json"
+      if [ "${ISNAD_SCAN_FAIL_FAST}" = "true" ]; then
+        scan_args="${scan_args} --fail-fast"
+      fi
+
+      isnad-scan ${scan_args} > "${ISNAD_SCAN_OUTPUT}"
+  artifacts:
+    when: always
+    expire_in: 14 days
+    paths:
+      - "${ISNAD_SCAN_OUTPUT}"
+    reports:
+      sast: "${ISNAD_SCAN_OUTPUT}"
+  rules:
+    - if: '$CI_PIPELINE_SOURCE == "merge_request_event"'
+    - if: '$CI_COMMIT_BRANCH == $CI_DEFAULT_BRANCH'
+

web/content/docs/gitlab-ci.md

@@ -0,0 +1,15 @@
+# GitLab CI Integration
+
+Run ISNAD scanner checks in GitLab merge request pipelines.
+
+Copy `examples/gitlab/.gitlab-ci.yml` into your GitLab repository root and configure:
+
+```yaml
+variables:
+  ISNAD_SCAN_TARGETS: "skills/**/*.js prompts/**/*.md configs/**/*.json"
+  ISNAD_SCAN_OUTPUT: "isnad-scan-results.json"
+  ISNAD_SCAN_FAIL_FAST: "false"
+```
+
+The job runs on merge requests and the default branch, writes scanner JSON to `ISNAD_SCAN_OUTPUT`, and keeps that file as an artifact for reviewer and auditor evidence.
+

web/content/docs/integration.md

@@ -9,6 +9,12 @@ Integrate ISNAD trust verification into your agent platform or skill marketplace
 - **CI/CD pipelines:** Block untrusted dependencies
 - **Wallets:** Warn users about unverified agent actions
 
+## GitLab CI
+
+Use `examples/gitlab/.gitlab-ci.yml` to run `isnad-scan` in GitLab merge request pipelines. Configure `ISNAD_SCAN_TARGETS` for your skills, prompts, and agent configs, and keep the generated JSON artifact for reviewer and auditor evidence.
+
+See [GitLab CI Integration](./gitlab-ci) for the full template, configurable targets, JSON output, and fail-fast settings.
+
 ## Quick Integration
 
 ### Option 1: API (Simplest)

web/src/app/docs/gitlab-ci/page.tsx

@@ -0,0 +1,52 @@
+import { CodeBlock } from '@/components/CodeBlock';
+
+export default function GitLabCIPage() {
+  return (
+    <article>
+      <h1 className="text-3xl sm:text-4xl font-bold mb-6 tracking-tight">GitLab CI Integration</h1>
+      <p className="text-lg text-[var(--text-secondary)] mb-8">
+        Run ISNAD scanner checks in GitLab merge request pipelines and keep JSON evidence as a build artifact.
+      </p>
+
+      <h2 className="text-2xl font-bold mt-8 mb-4 pb-2 border-b border-[var(--border-dim)]">
+        Template
+      </h2>
+      <p className="text-[var(--text-secondary)] mb-4">
+        Copy <code>examples/gitlab/.gitlab-ci.yml</code> into your GitLab repository root and configure the target globs.
+      </p>
+      <CodeBlock
+        lines={[
+          'variables:',
+          '  ISNAD_SCAN_TARGETS: "skills/**/*.js prompts/**/*.md configs/**/*.json"',
+          '  ISNAD_SCAN_OUTPUT: "isnad-scan-results.json"',
+          '  ISNAD_SCAN_FAIL_FAST: "false"',
+        ]}
+      />
+
+      <h2 className="text-2xl font-bold mt-8 mb-4 pb-2 border-b border-[var(--border-dim)]">
+        Pipeline Behavior
+      </h2>
+      <ul className="list-disc list-inside space-y-2 text-[var(--text-secondary)] mb-6">
+        <li>Runs on merge requests and the default branch.</li>
+        <li>Installs <code>@isnad/scanner</code> in a Node 20 Alpine image.</li>
+        <li>Writes scanner JSON to <code>ISNAD_SCAN_OUTPUT</code>.</li>
+        <li>Publishes the JSON file as an artifact and GitLab SAST report input.</li>
+      </ul>
+
+      <h2 className="text-2xl font-bold mt-8 mb-4 pb-2 border-b border-[var(--border-dim)]">
+        Example Include
+      </h2>
+      <CodeBlock
+        lines={[
+          'include:',
+          '  - local: examples/gitlab/.gitlab-ci.yml',
+          '',
+          'variables:',
+          '  ISNAD_SCAN_TARGETS: "agent-skills/**/*.js system-prompts/**/*.md"',
+          '  ISNAD_SCAN_OUTPUT: "gl-isnad-scan.json"',
+        ]}
+      />
+    </article>
+  );
+}
+

web/src/app/docs/layout.tsx

@@ -27,6 +27,7 @@ const sections = [
       { href: '/docs/contracts', label: 'Smart Contracts' },
       { href: '/docs/api', label: 'API Reference' },
       { href: '/docs/integration', label: 'Integration Guide' },
+      { href: '/docs/gitlab-ci', label: 'GitLab CI' },
     ]
   },
 ];