diff --git a/docs/gitlab-ci.md b/docs/gitlab-ci.md new file mode 100644 index 00000000..affd036e --- /dev/null +++ b/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`. + diff --git a/examples/gitlab/.gitlab-ci.yml b/examples/gitlab/.gitlab-ci.yml new file mode 100644 index 00000000..cee94bad --- /dev/null +++ b/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' + diff --git a/web/content/docs/gitlab-ci.md b/web/content/docs/gitlab-ci.md new file mode 100644 index 00000000..b27bcb4e --- /dev/null +++ b/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. + diff --git a/web/content/docs/integration.md b/web/content/docs/integration.md index 261ce5f3..61aa017f 100644 --- a/web/content/docs/integration.md +++ b/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) diff --git a/web/src/app/docs/gitlab-ci/page.tsx b/web/src/app/docs/gitlab-ci/page.tsx new file mode 100644 index 00000000..4a909508 --- /dev/null +++ b/web/src/app/docs/gitlab-ci/page.tsx @@ -0,0 +1,52 @@ +import { CodeBlock } from '@/components/CodeBlock'; + +export default function GitLabCIPage() { + return ( +
+

GitLab CI Integration

+

+ Run ISNAD scanner checks in GitLab merge request pipelines and keep JSON evidence as a build artifact. +

+ +

+ Template +

+

+ Copy examples/gitlab/.gitlab-ci.yml into your GitLab repository root and configure the target globs. +

+ + +

+ Pipeline Behavior +

+ + +

+ Example Include +

+ +
+ ); +} + diff --git a/web/src/app/docs/layout.tsx b/web/src/app/docs/layout.tsx index 6b00ecfa..8413adcd 100644 --- a/web/src/app/docs/layout.tsx +++ b/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' }, ] }, ];