← Back to Blog

How to Add Nark to Your GitHub Actions CI

By Nark Team

Why Run Nark in CI?

Running npx nark locally is great for individual developers, but the real value comes from making it part of your CI pipeline. Every pull request gets checked for unhandled package behaviors — no one can merge code that silently ignores axios timeouts, Prisma connection failures, or Stripe rate limits.

Prerequisites

  • A TypeScript project with a tsconfig.json
  • A GitHub repository with Actions enabled

Step 1: Add the Workflow File

Create .github/workflows/nark.yml in your repository:

name: Nark — Profile Check

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

jobs:
  nark-scan:
    name: Scan for unhandled behaviors
    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: Run Nark
        run: npx nark --tsconfig tsconfig.json

That's it. Nark will scan your project and fail the check if it finds unhandled Profile violations.

Step 2: Customize the Scan

Scan a Specific tsconfig

If your project uses a different tsconfig for source files (common in monorepos):

      - name: Run Nark
        run: npx nark --tsconfig tsconfig.app.json

Set a Severity Threshold

Only fail on errors, allowing warnings to pass:

      - name: Run Nark
        run: npx nark --tsconfig tsconfig.json --min-severity error

JSON Output for Downstream Processing

      - name: Run Nark
        run: npx nark --tsconfig tsconfig.json --format json > nark-report.json

      - name: Upload Report
        uses: actions/upload-artifact@v4
        with:
          name: nark-report
          path: nark-report.json

Step 3: Connect to Nark Cloud (Optional)

If you're using Nark Cloud to track violations over time, add your API key as a repository secret:

  1. Go to Settings → Secrets and variables → Actions in your GitHub repo
  2. Add a secret named NARK_API_KEY with your API key from the Nark Cloud dashboard
  3. Update the workflow:
      - name: Run Nark
        run: npx nark --tsconfig tsconfig.json --api-key $NARK_API_KEY
        env:
          NARK_API_KEY: ${{ secrets.NARK_API_KEY }}

Scan results will stream to your Nark Cloud dashboard for trend tracking and team visibility.

What Nark Checks

On every CI run, Nark cross-references your code against Profiles for packages like:

  • axios — unhandled network errors, timeouts, request cancellations
  • @prisma/client — unhandled query failures, connection errors, constraint violations
  • stripe — unhandled API errors, rate limits, idempotency issues
  • pg / redis / ioredis — unhandled connection failures, command errors
  • nodemailer — unhandled SMTP errors, authentication failures

The full list of supported packages is growing — see our supported packages page.

Monorepo Setup

For monorepos with multiple packages, run Nark against each:

    strategy:
      matrix:
        package: [apps/api, apps/web, packages/shared]

    steps:
      - uses: actions/checkout@v4

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

      - name: Install dependencies
        run: npm ci

      - name: Run Nark on ${{ matrix.package }}
        run: npx nark --tsconfig ${{ matrix.package }}/tsconfig.json

Next Steps