CI Integration

verikt enforces architecture rules in your CI pipeline and as a pre-commit hook.

Prerequisites

Your project must have an verikt.yaml file at the repository root. This file defines the architecture, capabilities, and rules that verikt check validates against.

If you don’t have one yet, run verikt new to scaffold a project, or create one manually following the verikt.yaml reference.

GitHub Actions

Add this workflow to .github/workflows/verikt.yml:

name: Architecture Check
on:
  pull_request:
    branches: [main]

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

      - name: Install verikt
        run: |
          curl -sSfL https://github.com/diktahq/verikt/releases/download/v0.2.1/verikt_0.2.1_linux_amd64.tar.gz | tar xz
          sudo mv verikt /usr/local/bin/

      - name: Check architecture
        run: verikt check

Caution

Always pin to a specific version (v0.2.1) instead of @latest. This prevents unexpected CI failures when a new version introduces stricter rules.

GitLab CI

Add this to your .gitlab-ci.yml:

verikt:
  stage: test
  image: golang:1.24
  cache:
    key: verikt
    paths:
      - /go/pkg/mod/
  before_script:
    - curl -sSfL https://github.com/diktahq/verikt/releases/download/v0.2.1/verikt_0.2.1_linux_amd64.tar.gz | tar xz
    - mv verikt /usr/local/bin/
  script:
    - verikt check
  rules:
    - if: $CI_MERGE_REQUEST_ID

Pre-commit Hook

Add a git pre-commit hook to catch violations before they are committed. Create .git/hooks/pre-commit:

#!/usr/bin/env bash
set -e

verikt check --staged

Then make it executable:

chmod +x .git/hooks/pre-commit

The --staged flag tells verikt to only check files that are staged for commit, making the hook fast enough for interactive use.

Pre-commit Framework

If you use the pre-commit framework, add this to your .pre-commit-config.yaml:

repos:
  - repo: local
    hooks:
      - id: verikt-check
        name: verikt check
        entry: verikt check --staged
        language: system
        pass_filenames: false
        always_run: true

Exit Codes

verikt check uses the following exit codes:

Exit Code	Meaning
0	No error-severity violations. Warnings may be present but do not cause failure.
1	An error-severity violation was found, or a proxy rule could not run.

Only error severity fails the build, in every category — dependency, structure, function, naming and anti-pattern findings alike. Warnings (missing optional capabilities, advisory anti-patterns) never affect the exit code, so use severity_overrides in verikt.yaml to decide what blocks you. That includes anti-patterns: a finding you have reviewed and accepted can be waived with a required reason, and stays visible in the WAIVED section rather than vanishing.

severity_overrides:
  god_package:
    - severity: ignore
      reason: "the shared domain vocabulary; nothing to trim"
      paths: ["internal/core/**"]

A proxy rule whose scope matches no files is reported as stale and fails the check. A rule that could not run has not passed, and treating it as a pass is how a silently-broken rule survives in CI for months. A rule that ran across its scope and found nothing has passed.

If you would rather gate in your own script, read result — the document carries a schema_version to check first:

verikt check --output json > verikt.json
jq -e '.result == "pass"' verikt.json

result is the verdict the exit code carries, across every category. Do not build a gate by selecting on severity across violations[] and anti_patterns[]: those hold built-in detector findings only, so a gate made from them passes when an error-severity proxy rule fires (those live in proxy_rules.violations[]), when a rule goes stale, and when a decision gate fails. All three fail verikt check.

Testing Across Go Versions

verikt resolves feature flags based on the detected Go version, which means scaffolded output varies by version. To verify templates render correctly across versions, use --set GoVersion in a matrix build:

# GitHub Actions example
jobs:
  scaffold-matrix:
    strategy:
      matrix:
        go-version: ["1.21", "1.23", "1.24", "1.25"]
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4
      - name: Install verikt
        run: |
          curl -sSfL https://github.com/diktahq/verikt/releases/download/v0.2.1/verikt_0.2.1_linux_amd64.tar.gz | tar xz
          sudo mv verikt /usr/local/bin/
      - name: Scaffold with target version
        run: |
          verikt new test-svc \
            --language go \
            --set GoVersion=${{ matrix.go-version }} \
            --arch hexagonal \
            --cap platform,bootstrap,http-api \
            --no-wizard
      - name: Verify generated code compiles
        uses: actions/setup-go@v5
        with:
          go-version: ${{ matrix.go-version }}
      - run: cd test-svc && go build ./...

This catches cases where a feature-gated template emits code that doesn’t compile on older Go versions.