CI/CD Integration

This guide shows how to integrate AIGovHub into your CI/CD pipelines.

Overview

AIGovHub CLI is designed for automation:

Deterministic output: Same input produces same output (with --no-llm)
Exit codes: Non-zero on failure for pipeline integration
Machine-readable output: JSON format for processing
Fast execution: Deterministic scanning completes in seconds

GitHub Actions

Basic Scan

# .github/workflows/ai-compliance.yml
name: AI Compliance Check
 
on:
  push:
    branches: [main]
  pull_request:
    branches: [main]
 
jobs:
  ai-compliance:
    runs-on: ubuntu-latest
 
    steps:
      - name: Checkout code
        uses: actions/checkout@v4
 
      - name: Set up Python
        uses: actions/setup-python@v5
        with:
          python-version: '3.12'
 
      - name: Install AIGovHub
        run: pip install aigovhub-cli
 
      - name: Scan for AI Systems
        run: aigovhub scan . --no-llm
 
      - name: Validate Artifact
        run: aigovhub validate --strict
 
      - name: Upload Artifact
        uses: actions/upload-artifact@v4
        with:
          name: ai-compliance
          path: aigovhub.yaml

With LLM Enhancement

# .github/workflows/ai-compliance-llm.yml
name: AI Compliance (Enhanced)
 
on:
  workflow_dispatch:  # Manual trigger
  schedule:
    - cron: '0 0 * * 0'  # Weekly on Sunday
 
jobs:
  ai-compliance:
    runs-on: ubuntu-latest
 
    steps:
      - uses: actions/checkout@v4
 
      - uses: actions/setup-python@v5
        with:
          python-version: '3.12'
 
      - name: Install AIGovHub
        run: pip install aigovhub-cli
 
      - name: Scan with LLM Fallback
        env:
          ANTHROPIC_API_KEY: ${{ secrets.ANTHROPIC_API_KEY }}
        run: aigovhub scan . --llm-provider anthropic
 
      - name: Commit Updated Artifact
        uses: stefanzweifel/git-auto-commit-action@v5
        with:
          commit_message: 'chore: update AI compliance artifact'
          file_pattern: aigovhub.yaml

PR Comment with Results

# .github/workflows/ai-compliance-pr.yml
name: AI Compliance PR Check
 
on:
  pull_request:
    branches: [main]
 
jobs:
  ai-compliance:
    runs-on: ubuntu-latest
 
    steps:
      - uses: actions/checkout@v4
 
      - uses: actions/setup-python@v5
        with:
          python-version: '3.12'
 
      - name: Install AIGovHub
        run: pip install aigovhub-cli
 
      - name: Scan for AI Systems
        id: scan
        run: |
          aigovhub scan . --format json --output ai-scan.json --no-llm
          SYSTEMS=$(jq '.ai_systems | length' ai-scan.json)
          echo "ai_systems=$SYSTEMS" >> $GITHUB_OUTPUT
 
      - name: Comment on PR
        uses: actions/github-script@v7
        with:
          script: |
            const systems = ${{ steps.scan.outputs.ai_systems }};
            const body = `## AI Compliance Scan Results
 
            **AI Systems Detected:** ${systems}
 
            ${systems > 0 ?
              '⚠️ This repository contains AI systems. Please ensure compliance with EU AI Act requirements.' :
              '✅ No AI systems detected.'}
 
            See the full report in the workflow artifacts.`;
 
            github.rest.issues.createComment({
              issue_number: context.issue.number,
              owner: context.repo.owner,
              repo: context.repo.repo,
              body: body
            });

Matrix Testing

# .github/workflows/ai-compliance-matrix.yml
name: AI Compliance (Multiple Repos)
 
on:
  workflow_dispatch:
 
jobs:
  scan:
    runs-on: ubuntu-latest
    strategy:
      matrix:
        repo:
          - path: services/api
            name: api-service
          - path: services/ml
            name: ml-service
          - path: services/web
            name: web-service
 
    steps:
      - uses: actions/checkout@v4
 
      - uses: actions/setup-python@v5
        with:
          python-version: '3.12'
 
      - run: pip install aigovhub-cli
 
      - name: Scan ${{ matrix.repo.name }}
        run: |
          aigovhub scan ${{ matrix.repo.path }} \
            --output reports/${{ matrix.repo.name }}.yaml \
            --no-llm
 
      - uses: actions/upload-artifact@v4
        with:
          name: ${{ matrix.repo.name }}-compliance
          path: reports/${{ matrix.repo.name }}.yaml

GitLab CI

Basic Pipeline

# .gitlab-ci.yml
stages:
  - compliance
 
ai-compliance:
  stage: compliance
  image: python:3.12
  script:
    - pip install aigovhub-cli
    - aigovhub scan . --no-llm
    - aigovhub validate --strict
  artifacts:
    paths:
      - aigovhub.yaml
    expire_in: 1 week
  rules:
    - if: $CI_PIPELINE_SOURCE == "merge_request_event"
    - if: $CI_COMMIT_BRANCH == $CI_DEFAULT_BRANCH

With LLM (Protected Variables)

# .gitlab-ci.yml
ai-compliance-enhanced:
  stage: compliance
  image: python:3.12
  variables:
    AIGOVHUB_LLM_PROVIDER: anthropic
  script:
    - pip install aigovhub-cli
    - aigovhub scan . --llm
  artifacts:
    paths:
      - aigovhub.yaml
  rules:
    - if: $CI_COMMIT_BRANCH == $CI_DEFAULT_BRANCH
  # ANTHROPIC_API_KEY set as CI/CD variable (masked)

Scheduled Weekly Scan

# .gitlab-ci.yml
ai-compliance-weekly:
  stage: compliance
  image: python:3.12
  script:
    - pip install aigovhub-cli
    - aigovhub scan . --no-llm
    - |
      if git diff --quiet aigovhub.yaml; then
        echo "No changes in AI systems"
      else
        echo "AI systems changed - review required"
        exit 1
      fi
  rules:
    - if: $CI_PIPELINE_SOURCE == "schedule"

Azure DevOps

Basic Pipeline

# azure-pipelines.yml
trigger:
  - main
 
pool:
  vmImage: 'ubuntu-latest'
 
steps:
  - task: UsePythonVersion@0
    inputs:
      versionSpec: '3.12'
 
  - script: pip install aigovhub-cli
    displayName: 'Install AIGovHub'
 
  - script: aigovhub scan . --no-llm
    displayName: 'Scan for AI Systems'
 
  - script: aigovhub validate --strict
    displayName: 'Validate Artifact'
 
  - task: PublishBuildArtifacts@1
    inputs:
      pathToPublish: 'aigovhub.yaml'
      artifactName: 'ai-compliance'

Jenkins

Jenkinsfile

// Jenkinsfile
pipeline {
    agent {
        docker {
            image 'python:3.12'
        }
    }
 
    stages {
        stage('Install') {
            steps {
                sh 'pip install aigovhub-cli'
            }
        }
 
        stage('Scan') {
            steps {
                sh 'aigovhub scan . --no-llm'
            }
        }
 
        stage('Validate') {
            steps {
                sh 'aigovhub validate --strict'
            }
        }
    }
 
    post {
        always {
            archiveArtifacts artifacts: 'aigovhub.yaml', fingerprint: true
        }
    }
}

CircleCI

# .circleci/config.yml
version: 2.1
 
jobs:
  ai-compliance:
    docker:
      - image: cimg/python:3.12
    steps:
      - checkout
      - run:
          name: Install AIGovHub
          command: pip install aigovhub-cli
      - run:
          name: Scan for AI Systems
          command: aigovhub scan . --no-llm
      - run:
          name: Validate Artifact
          command: aigovhub validate --strict
      - store_artifacts:
          path: aigovhub.yaml
          destination: ai-compliance
 
workflows:
  version: 2
  compliance:
    jobs:
      - ai-compliance

Docker Integration

Dockerfile

# Dockerfile.aigovhub
FROM python:3.12-slim
 
RUN pip install --no-cache-dir aigovhub-cli
 
WORKDIR /workspace
 
ENTRYPOINT ["aigovhub"]
CMD ["--help"]

Using in Pipelines

# GitHub Actions example
jobs:
  scan:
    runs-on: ubuntu-latest
    container:
      image: ghcr.io/aigovhub/aigovhub-cli:latest
    steps:
      - uses: actions/checkout@v4
      - run: aigovhub scan . --no-llm

Local Docker Usage

# Build
docker build -t aigovhub -f Dockerfile.aigovhub .
 
# Scan current directory
docker run -v $(pwd):/workspace aigovhub scan . --no-llm
 
# With API key for LLM
docker run -v $(pwd):/workspace \
  -e ANTHROPIC_API_KEY=$ANTHROPIC_API_KEY \
  aigovhub scan . --llm

Pre-commit Hook

Add to .pre-commit-config.yaml:

repos:
  - repo: local
    hooks:
      - id: aigovhub-scan
        name: AI Compliance Scan
        entry: aigovhub scan . --no-llm --dry-run
        language: system
        pass_filenames: false
        types: [python]

Best Practices

1. Use `--no-llm` in CI

LLM calls add latency and cost. Use deterministic scanning for CI:

aigovhub scan . --no-llm

2. Cache Dependencies

# GitHub Actions
- uses: actions/cache@v4
  with:
    path: ~/.cache/pip
    key: ${{ runner.os }}-pip-aigovhub

3. Fail on Validation Errors

Use --strict to fail if the artifact has warnings:

aigovhub validate --strict

4. Version Control the Artifact

Commit aigovhub.yaml to your repository:

git add aigovhub.yaml
git commit -m "Update AI compliance artifact"

5. Periodic Deep Scans

Run LLM-enhanced scans weekly or monthly:

# GitHub Actions schedule
on:
  schedule:
    - cron: '0 0 * * 0'  # Weekly on Sunday

6. Alert on Changes

Detect when AI systems change:

git diff --exit-code aigovhub.yaml || echo "AI systems changed!"

Exit Codes

Code	Meaning	Action
0	Success	Continue pipeline
1	Error or validation failure	Fail pipeline

Troubleshooting

"Command not found: aigovhub"

Ensure pip installed to PATH:

pip install aigovhub-cli
export PATH="$HOME/.local/bin:$PATH"

Slow Scans

Use --no-llm for speed
Exclude large directories (already excludes .git, node_modules)

Rate Limiting (LLM)

If using LLM in CI:

Use secrets management for API keys
Consider caching results
Schedule during low-usage times