CI/CD Integration

Tier‑1: add shipgate next on pull requests for Next.js App Router repos (prefer the shipgate-next composite). Treat the job as a recommended advisory gate first; in your repo you may mark it as a required check once trusted. See Supported path (Tier-1). The ShipGate monorepo runs two required Tier‑1 jobs in ci.yml and a shipgate-pr-gate workflow on the same roots (blocking-aligned) — see docs/dogfooding-status.md.

Everything below that uses ISL specs, composite actions, or other hosts is best-effort unless your team has validated it — do not imply universal coverage in user-facing copy.

For what is guaranteed vs best-effort across commands and versions, read the reliability contract.

GitHub Actions

Recommended: Next.js PR gate (`shipgate next`)

Use the published CLI on pull_request (or the shipgate-next composite). Point NEXT_APP_ROOT at the folder that contains your Next.js package.json (often .). For enforcement-grade thresholds, prefer --strict (and --format quiet for logs). Add the job as a required status check in GitHub only when you want NO_SHIP to block merge.

name: ShipGate Next (PR gate)

on:
  pull_request:
    branches: [main]

jobs:
  shipgate-next:
    runs-on: ubuntu-latest
    env:
      NEXT_APP_ROOT: "."
    steps:
      - uses: actions/checkout@v4
      - uses: actions/setup-node@v4
        with:
          node-version: "20"
      - name: Install dependencies
        run: npm ci
        working-directory: ${{ env.NEXT_APP_ROOT }}
      - name: Install ShipGate CLI
        run: npm install -g @shipgate.dev/cli@3.0.0
      - name: Next.js merge gate
        working-directory: ${{ env.NEXT_APP_ROOT }}
        run: |
          mkdir -p .shipgate
          shipgate next . --strict --format quiet \
            --evidence-out .shipgate/shipgate-next-evidence.json \
            --summary-out .shipgate/shipgate-next-summary.md

A full example with PR comments and artifacts lives in the repo: examples/golden-path-next.

Composite gate action (advanced / legacy wiring)

The packaged action wraps broader gate flows. It is not the same as the Tier‑1 shipgate next path above — treat inputs and behavior as best-effort until you validate them for your repo.

name: ShipGate Verify

on:
  pull_request:
    branches: [main]
  push:
    branches: [main]

jobs:
  verify:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4

      - uses: actions/setup-node@v4
        with:
          node-version: "20"

      - name: Install dependencies
        run: npm ci

      - name: ShipGate Verify
        uses: guardiavault-oss/isl-gate-action@v1
        with:
          mode: auto          # auto | strict | specless
          threshold: 80       # Minimum trust score to SHIP
          spec-path: specs/   # Path to ISL spec files
          impl-path: src/     # Path to implementation

Action inputs

Input	Default	Description
`mode`	`auto`	`auto` — ISL where specs exist, specless elsewhere. `strict` — require specs for all code. `specless` — no specs, use heuristic checks.
`threshold`	`80`	Minimum trust score (0-100) to pass
`spec-path`	`specs/`	Path to ISL specification files
`impl-path`	`src/`	Path to implementation files
`fail-on`	`error`	Fail on `error`, `warning`, or `unspecced`

Action outputs

The action sets these outputs for use in subsequent steps:

Output	Description
`verdict`	`SHIP`, `WARN`, or `NO_SHIP`
`score`	Trust score (0-100)
`summary`	Human-readable verification summary

PR comments

PR-facing text should read like a merge check, not a research report. For Next.js, post the Markdown from --summary-out (or a short excerpt). For spec workflows, keep summaries short: verdict, score, blockers, link to artifacts.

Example (illustrative):

## ShipGate merge check

**Verdict: SHIP** | Score: 92/100

### Blockers
- (none)

### Notes
- See uploaded `shipgate-next-summary.md` / JSON evidence in CI artifacts.

Using the CLI directly (spec / advanced)

If you use .isl specifications, you can run verify / gate in CI. This path is advanced; it is not the Tier‑1 Next.js PR wedge.

name: ShipGate Gate

on:
  pull_request:
    branches: [main]

jobs:
  gate:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4

      - uses: actions/setup-node@v4
        with:
          node-version: "20"

      - run: npm ci

      - name: Install ShipGate CLI
        run: npm install -g @shipgate.dev/cli

      - name: Verify specs
        run: shipgate verify specs/ --impl src/ --ci --fail-on error

      - name: Run gate
        run: |
          shipgate gate specs/api.isl \
            --impl src/ \
            --threshold 85 \
            --ci \
            --output evidence/

GitLab CI

shipgate-verify:
  stage: test
  image: node:20
  script:
    - npm ci
    - npm install -g @shipgate.dev/cli
    - shipgate verify specs/ --impl src/ --ci --format json
  artifacts:
    reports:
      junit: evidence/results.xml
    paths:
      - evidence/
  rules:
    - if: $CI_MERGE_REQUEST_ID

Generic CI (any platform)

ShipGate works with any CI system that can run Node.js. Use the --ci flag for machine-readable output:

# Install
npm install -g @isl-lang/cli

# Verify with JSON output
shipgate verify specs/ --impl src/ --ci --format json

# Gate with exit code
shipgate gate specs/api.isl --impl src/ --threshold 80 --ci
# Exit code 0 = SHIP, Exit code 1 = NO_SHIP

Trust score thresholds

Configure the minimum trust score for different environments:

Environment	Recommended Threshold	Rationale
Development	60	Allow experimentation
Staging	80	Catch issues before prod
Production	95	High confidence required

# Different thresholds per branch
- name: Gate (staging)
  if: github.base_ref == 'staging'
  run: shipgate gate specs/ --impl src/ --threshold 80 --ci

- name: Gate (production)
  if: github.base_ref == 'main'
  run: shipgate gate specs/ --impl src/ --threshold 95 --ci

Specless mode in CI

Even without ISL specs, ShipGate can verify code using heuristic checks:

- name: Specless verification
  run: shipgate verify src/ --ci --fail-on error

Specless mode checks for:

Hardcoded credentials and secrets
Missing authentication on sensitive routes
PII in logs
Ghost imports (importing modules that don’t exist)
Hallucinated APIs

See Specless Mode for details.

Caching

Speed up CI runs by caching ShipGate’s analysis data:

- uses: actions/cache@v4
  with:
    path: |
      .isl-gate/
      node_modules/.cache/shipgate
    key: shipgate-${{ hashFiles('specs/**/*.isl') }}