Poliage

CI/CD Integration

Automate visual documentation captures as part of your deployment pipeline to ensure documentation stays in sync with product changes.

Why Automate?

Manual documentation updates lead to:

  • Screenshots that don't match current UI
  • Delays between product updates and documentation
  • Inconsistent capture quality and settings

With CI/CD integration, every deployment automatically updates your visual documentation.

GitHub Actions

Create .github/workflows/poliage.yml:

name: Update Documentation
 
on:
  push:
    branches: [main]
  workflow_dispatch:
 
jobs:
  capture:
    runs-on: ubuntu-latest
    
    steps:
      - uses: actions/checkout@v4
      
      - name: Setup Node.js
        uses: actions/setup-node@v4
        with:
          node-version: '20'
          cache: 'npm'
      
      - name: Install Poliage CLI
        run: npm install -g @poliage/cli
      
      - name: Authenticate
        run: poliage login --token ${{ secrets.POLIAGE_TOKEN }}
      
      - name: Run Captures
        run: poliage capture run
      
      - name: Sync to Poliage
        run: poliage sync -m "Auto-update from ${{ github.sha }}"

Add POLIAGE_TOKEN to your repository secrets at Settings → Secrets → Actions.

Capturing Against Staging

If you deploy to a staging environment first:

name: Update Documentation
 
on:
  deployment_status:
 
jobs:
  capture:
    if: github.event.deployment_status.state == 'success'
    runs-on: ubuntu-latest
    
    steps:
      - uses: actions/checkout@v4
      
      - name: Setup Node.js
        uses: actions/setup-node@v4
        with:
          node-version: '20'
      
      - name: Install dependencies
        run: npm install -g @poliage/cli
      
      - name: Authenticate
        run: poliage login --token ${{ secrets.POLIAGE_TOKEN }}
      
      - name: Run Captures
        env:
          BASE_URL: ${{ github.event.deployment_status.target_url }}
        run: poliage capture run
      
      - name: Sync
        run: poliage sync -m "Staging captures from deployment"

GitLab CI

Create .gitlab-ci.yml:

stages:
  - deploy
  - document
 
documentation:
  stage: document
  image: node:20
  script:
    - npm install -g @poliage/cli
    - poliage login --token $POLIAGE_TOKEN
    - poliage capture run
    - poliage sync -m "Auto-update from $CI_COMMIT_SHA"
  rules:
    - if: $CI_COMMIT_BRANCH == "main"

CircleCI

Create .circleci/config.yml:

version: 2.1
 
jobs:
  capture-docs:
    docker:
      - image: cimg/node:20.0
    steps:
      - checkout
      - run:
          name: Install Poliage
          command: npm install -g @poliage/cli
      - run:
          name: Authenticate
          command: poliage login --token $POLIAGE_TOKEN
      - run:
          name: Capture Screenshots
          command: poliage capture run
      - run:
          name: Sync to Platform
          command: poliage sync -m "CircleCI build $CIRCLE_BUILD_NUM"
 
workflows:
  version: 2
  build-and-document:
    jobs:
      - capture-docs:
          filters:
            branches:
              only: main

Vercel Integration

For Vercel deployments, use a GitHub Action triggered by deployment:

name: Poliage on Vercel Deploy
 
on:
  deployment_status:
 
jobs:
  capture:
    if: |
      github.event.deployment_status.state == 'success' &&
      github.event.deployment_status.environment == 'Production'
    runs-on: ubuntu-latest
    
    steps:
      - uses: actions/checkout@v4
      
      - uses: actions/setup-node@v4
        with:
          node-version: '20'
      
      - run: npm install -g @poliage/cli
      - run: poliage login --token ${{ secrets.POLIAGE_TOKEN }}
      - run: poliage capture run
        env:
          BASE_URL: ${{ github.event.deployment_status.target_url }}
      - run: poliage sync -m "Production deploy ${{ github.sha }}"

Best Practices

Use Environment Variables

Keep your config flexible:

{
  "captures": [
    {
      "name": "homepage",
      "url": "${BASE_URL}/"
    },
    {
      "name": "dashboard",
      "url": "${BASE_URL}/dashboard"
    }
  ]
}

Conditional Captures

Only capture changed areas using path filters:

- name: Check for UI changes
  uses: dorny/paths-filter@v2
  id: changes
  with:
    filters: |
      frontend:
        - 'src/components/**'
        - 'src/pages/**'
 
- name: Capture if UI changed
  if: steps.changes.outputs.frontend == 'true'
  run: poliage capture run && poliage sync

Parallel Captures

Speed up CI by increasing parallelism:

- name: Run Captures
  run: poliage capture run --parallel 10

Cache Dependencies

- name: Cache Poliage
  uses: actions/cache@v3
  with:
    path: ~/.npm
    key: ${{ runner.os }}-poliage-${{ hashFiles('**/package-lock.json') }}

Troubleshooting

Puppeteer Issues in CI

Most CI environments need additional dependencies for headless Chrome. Add these steps for Ubuntu:

- name: Install Chrome dependencies
  run: |
    sudo apt-get update
    sudo apt-get install -y \
      libnss3 libatk1.0-0 libatk-bridge2.0-0 \
      libcups2 libdrm2 libxkbcommon0 libxcomposite1 \
      libxdamage1 libxrandr2 libgbm1 libasound2

Common Issues

IssueSolution
Authentication failsVerify POLIAGE_TOKEN secret is set correctly
Captures timeoutIncrease timeout in config or add explicit waits
Missing fontsInstall font packages in CI environment
Screenshots differ from localEnsure same viewport and device scale factor