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.1.0/verikt_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.1.0) 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.1.0/verikt_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	All checks passed. Warnings may be present but do not cause failure.
1	One or more architecture violations were found.

Warnings (such as missing optional capabilities) are printed to stderr but do not cause a non-zero exit code. Only actual violations fail the 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.1.0/verikt_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.