How to integrate Critiq in your GitHub workflow

Integrating Critiq in your GitHub workflow means the same rule-backed scan runs where you already work: on your laptop before push, on every pull request in Actions, and optionally as a required check in branch protection. No Critiq Cloud account is required for the open source path; scanning runs on your runner with @critiq/cli and @critiq/rules.

This guide walks through a practical rollout: install the CLI, add a workflow file, connect branch protection, and tune monorepo paths. Product overview and install commands live at https://critiq.dev/products/oss; the Action-focused setup is at https://critiq.dev/integrations/github-actions.

Layer 1: local checks in the inner loop

Start where feedback is cheapest. Add @critiq/cli and @critiq/rules as dev dependencies and run critiq check from the repository root. Authors fix findings before CI spends minutes on a queue.

npm install -D @critiq/cli @critiq/rules
npx @critiq/cli check .
critiq check --format json .

Optional: add a package.json script and a pre-push hook if your team wants a soft gate. Keep secrets scanning separate with critiq audit secrets when credential-shaped literals must block commits.

Layer 2: pull_request workflow with critiq-action

Create .github/workflows/critiq.yml triggered on pull_request. The composite action installs the CLI, runs a diff-scoped check, posts inline review comments, and can fail the job on severity.

name: Critiq

on:
  pull_request:

permissions:
  contents: read
  pull-requests: write

jobs:
  critiq:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v6
        with:
          fetch-depth: 0

      - uses: critiq-dev/critiq-action@v1
        with:
          comment-mode: inline
          fail-on-severity: high

fetch-depth: 0 is required so base and head SHAs resolve for diff mode. pull-requests: write is required for inline comments. Pin cli-version and rules-version when you want CI to match a known catalog release.

Layer 3: branch protection and required checks

After the workflow runs green on a test PR, add the Critiq job name under branch protection required status checks. Match the job key in your workflow (critiq in the example above). If fail-on-severity is off, a green job means the scan completed, not zero findings; use fail-on-severity: high when merges should block on security findings.

• Settings → Branches → Add rule → Require status checks
• Search for the Critiq job name from Actions
• Require pull request reviews separately; Critiq does not replace human review

Monorepo and path scoping

Set working-directory to the package root and target to the subtree you analyze. That keeps PR comments on the app the author changed instead of unrelated packages.

      - uses: critiq-dev/critiq-action@v1
        with:
          working-directory: apps/web
          target: apps/web
          fail-on-severity: high

Add .critiq/config.yaml at the repo or package root for presets, ignorePaths, and rule toggles. The Action loads config from working-directory automatically.

Reusable workflow for many repositories

Platform teams can centralize checkout, permissions, and default inputs in critiq-dev/critiq-action reusable workflow. Caller repos stay thin.

jobs:
  critiq:
    uses: critiq-dev/critiq-action/.github/workflows/reusable-critiq.yml@v1
    secrets: inherit

Verify local and CI output match

Before debugging "works locally, fails in CI," compare CLI and rules versions and the same base/head pair.

critiq check --base origin/main --head HEAD --format json .

Rule IDs and severities in JSON should match inline comments on the PR. If they diverge, pin versions in the workflow and in package.json devDependencies.

Next steps

• Automate PR checks, /blog/automate-pr-review-checks-github-actions
• Inline comments and dedupe, /blog/inline-pr-comments-dedupe-severity
• OSS product page, https://critiq.dev/products/oss
• GitHub Actions integration, https://critiq.dev/integrations/github-actions
• Action README, https://github.com/critiq-dev/critiq-action

Integrate Critiq in your GitHub workflow in three layers: local habit, pull_request automation, then branch protection once the catalog earns trust. Each layer uses the same inspectable rules so review feedback stays reproducible end to end.