CI and automation

This page is the single map of every automated pipeline in the shieldkit repository. Human contributors and Cursor agents should start here when asking “what runs when?” or “why did this workflow fail?”.

Related deep-dives:

Dependency policy — Vercel AI SDK (ai) version strategy, Dependabot, drift handling
Running tests — local commands, test layout, env vars
Verification matrix — what each test layer proves

Overview

mermaid

flowchart TB
  subgraph merge_gate["Merge gate (every push / PR)"]
    CI["CI — lint, test, build, docs, audit, pack"]
    DOCS["Docs — VitePress deploy check"]
    CODEQL["CodeQL — security analysis"]
    LABEL["Labeler — PR labels"]
    AICOMPAT_PR["AI SDK Compatibility — when src/deps change"]
  end

  subgraph weekly["Weekly (Monday UTC)"]
    DEP["Dependabot 06:00 — opens PRs"]
    AICOMPAT["AI SDK Compatibility 08:00 — drift + matrix"]
  end

  subgraph nightly["Nightly"]
    RED["Red Team 04:00 — Ollama adversarial"]
  end

  DEP --> AICOMPAT
  AICOMPAT -->|drift + latest passes| ISSUE_D["Issue: ai-sdk-drift"]
  AICOMPAT -->|latest fails| ISSUE_F["Issue: ai-sdk-compat-failure"]

Workflow reference

Workflow	File	Trigger	Blocks merge?	Purpose
CI	`ci.yml`	Push / PR to `main`	Yes	Full quality gate + build + docs + `npm pack --dry-run`
AI SDK Compatibility	`ai-sdk-compat.yml`	Weekly Mon 08:00 UTC, PR (deps/src/tests), manual	Yes on PR when triggered	Lockfile vs `ai@latest`; typecheck + test + build matrix
Docs	`docs.yml`	Push / PR (docs paths)	Yes when triggered	VitePress build / GitHub Pages
CodeQL	`codeql.yml`	Push / PR / schedule	Advisory	Static security analysis
Red Team	`redteam.yml`	Daily 04:00 UTC, manual	No (`continue-on-error`)	Live Ollama injection prompts
Labeler	`labeler.yml`	PR opened / sync	No	Auto-labels (`ci`, `tests`, `documentation`, …)
Publish	`publish.yml`	Push tag `v*`, manual	N/A (release)	npm OIDC publish + GitHub Release from `CHANGELOG`

Dependabot (dependabot.yml) is not a workflow but opens PRs weekly (Monday 06:00 UTC). The ai-sdk group bundles ai and @ai-sdk/*; those PRs should pass CI and AI SDK Compatibility.

CI (merge gate)

File: .github/workflows/ci.yml
Node: 22
Concurrency: one run per ref; PRs cancel in-progress runs.

Step	Command	What it proves
Install	`npm ci`	Reproducible lockfile
Quality gate	`npm run ci`	Lint (0 warnings), Prettier, `tsc`, Vitest (163 tests), full-tree `npm audit`
Library	`npm run build`	`dist/` compiles via tsup
Documentation	`npm run docs:build`	VitePress links and MD valid
Package tarball	`npm pack --dry-run`	npm publish surface = `dist` + README + LICENSE

npm run ci includes tests/adversarial/ but not tests/redteam/ (see Running tests).

AI SDK Compatibility

File: .github/workflows/ai-sdk-compat.yml
Why: shieldkit is tightly coupled to Vercel AI SDK v6 (LanguageModelV3 middleware). New ai releases can break types or middleware contracts before consumers upgrade.

Jobs

Job	What it does
Version drift report	Runs `scripts/check-ai-sdk-version.mjs`; writes a summary table (lockfile, npm latest, peer range, drift yes/no)
Compatibility matrix	Two parallel legs: pinned lockfile (`npm ci`) and latest on npm (`npm install ai@latest`); each runs `typecheck`, `test:run`, `build`
Weekly notify	Scheduled only: opens a GitHub issue when drift is detected (latest passes) or when the matrix fails (latest breaks)

Outcomes (scheduled run)

Situation	Workflow result	Maintainer action
Lockfile = latest, all green	Pass	None
Lockfile < latest, matrix green	Pass + optional `ai-sdk-drift` issue	Merge Dependabot PR or `npm install ai@latest --save-dev`
`ai@latest` matrix red	Fail + `ai-sdk-compat-failure` issue	Fix forward compatibility in `src/` / tests; read AI SDK releases
Pinned matrix red	Fail	Fix regression on current pin (same as broken `main`)

PR triggers

Runs when a PR touches:

package.json, package-lock.json
src/**, tests/**
scripts/check-ai-sdk-version.mjs, workflow or Dependabot config

Local equivalents

bash

npm run check:ai-sdk                    # drift report (human-readable)
npm run check:ai-sdk -- --strict        # exit 1 if lockfile < latest
npm run check:ai-sdk -- --json          # machine-readable
npm run verify:ai-sdk-latest            # full typecheck + test + build on latest

After verify:ai-sdk-latest, run npm ci to restore the lockfile pin.

Full policy: Dependency policy.

Red Team (advisory)

File: .github/workflows/redteam.yml
Schedule: daily 04:00 UTC
Merge impact: none (continue-on-error: true, REDTEAM_STRICT=0)

Installs Ollama on the runner, pulls llama3.2, runs npm run test:redteam. Uploads test-results/ artifacts when present.

Locally, default REDTEAM_STRICT=1 hard-fails on unblockable injection prompts. See Security assurance report.

Docs deployment

File: .github/workflows/docs.yml
Builds VitePress with VITEPRESS_BASE set for GitHub Pages project sites. Details: DEPLOYMENT.md.

CodeQL

File: .github/workflows/codeql.yml
JavaScript/TypeScript analysis on src/. Results appear in the GitHub Security tab.

Publish (npm)

File: .github/workflows/publish.yml
Trigger: push tag v* (or manual workflow_dispatch)
Auth: npm trusted publishing (OIDC) — requires one-time setup on npmjs.com

Runs the same quality gate as CI, builds dist/, verifies npm pack --dry-run, then npm publish. On tag push, also extracts the matching CHANGELOG section and creates a GitHub Release automatically.

Full setup (trusted publisher form fields, release checklist): npm publishing.

Dependabot groups

Group	Packages	Schedule
`ai-sdk`	`ai`, `@ai-sdk/*`	Weekly Mon 06:00 UTC
`testing`	vitest	Weekly
`typescript-and-build`	typescript, tsup, esbuild	Weekly
`linting-and-formatting`	eslint, prettier	Weekly
`docs`	vitepress	Weekly
`security-updates`	any (security advisories)	As needed

Labels (automation)

Label	Source	Meaning
`dependencies`	Dependabot / drift issues	Dependency change
`ai-sdk-drift`	AI SDK Compatibility (scheduled)	Latest passes; lockfile can be bumped
`ai-sdk-compat-failure`	AI SDK Compatibility (scheduled)	Latest `ai` breaks the test matrix
`automated`	Drift / compat issues	Bot-opened reminder

PR labels from labeler.yml: ci, dependencies, documentation, code, tests, examples, security.

Maintainer checklist

Every PR

[ ] CI green
[ ] AI SDK Compatibility green (if workflow ran on the PR)

After merging an ai bump

[ ] npm run ci locally
[ ] Scan AI SDK changelog
[ ] Update CHANGELOG.md if peer or middleware behavior changed

Weekly (optional)

Review Actions → AI SDK Compatibility summary
Triage open ai-sdk-drift / ai-sdk-compat-failure issues
Merge grouped Dependabot PRs when green

CI and automation ​

Overview ​

Workflow reference ​

CI (merge gate) ​

AI SDK Compatibility ​

Jobs ​

Outcomes (scheduled run) ​

PR triggers ​

Local equivalents ​

Red Team (advisory) ​

Docs deployment ​

CodeQL ​

Publish (npm) ​

Dependabot groups ​

Labels (automation) ​

Maintainer checklist ​

Related ​