Poliage

CI/CD Integration

Automate visual generation on every commit to ensure documentation never goes stale.

Quick Setup

Run the CI setup wizard to generate workflow files:

poliage ci

This generates configuration for:

  • GitHub Actions
  • GitLab CI
  • CircleCI

GitHub Actions

Manual Configuration

Create .github/workflows/poliage.yml:

name: Visual Docs
on: [push]
 
jobs:
  poliage:
    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: Install Poliage
        run: npm install -g @poliage/cli
 
      - name: Start application
        run: npm run dev &
 
      - name: Wait for app
        run: npx wait-on http://localhost:3000
 
      - name: Run scenarios
        run: poliage run --headless
        env:
          POLIAGE_API_KEY: ${{ secrets.POLIAGE_API_KEY }}
 
      - name: Publish assets
        run: poliage publish --force
        env:
          POLIAGE_API_KEY: ${{ secrets.POLIAGE_API_KEY }}

Required Secrets

Add to your repository secrets:

SecretDescription
POLIAGE_API_KEYAPI key from Project Settings
AWS_ACCESS_KEY_IDFor S3 storage (if using BYOS)
AWS_SECRET_ACCESS_KEYFor S3 storage (if using BYOS)

GitLab CI

Create .gitlab-ci.yml:

poliage:
  image: node:20
  script:
    - npm ci
    - npm install -g @poliage/cli
    - npm run dev &
    - npx wait-on http://localhost:3000
    - poliage run --headless
    - poliage publish --force
  variables:
    POLIAGE_API_KEY: $POLIAGE_API_KEY

Environment Variables

VariableDescription
POLIAGE_API_KEYAPI authentication token
CISet to true in most CI environments
POLIAGE_HEADLESSForce headless mode

Best Practices

Visual changes are reported, not blocked. By default, Poliage posts a PR comment summarizing visual changes rather than blocking the merge. This gives visibility without slowing down hotfixes.

  1. Cache dependencies: Speed up builds by caching node_modules
  2. Run on feature branches: Catch visual changes early
  3. Use GitHub Integration: Get notified of visual changes via PR comments
  4. Parallelize: Run multiple scenarios concurrently with --concurrency

Governance Modes

Poliage supports two governance modes in project settings:

ModeBehavior
notify (default)Posts a PR comment with visual changes summary. Non-blocking.
blockingPosts a commit status that requires approval. Use for strict governance.

Triggering on Specific Paths

Only run when relevant files change:

on:
  push:
    paths:
      - "src/**"
      - "docsync.config.json"