Guide: CI/CD Integration

Workloom's wl sync --check command turns AI configuration compliance into an automated gate. No more hoping everyone remembered to update their configs.

Basic Setup

GitHub Actions

name: AI Config Compliance
on: [pull_request, push]

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

      - name: Setup Node.js
        uses: actions/setup-node@v4
        with:
          node-version: 22

      - name: Install Workloom CLI
        run: npm install -g @workloom/cli

      - name: Check for drift
        run: wl sync --check
        env:
          WL_TOKEN: ${{ secrets.WORKLOOM_CI_TOKEN }}

GitLab CI

ai-config-check:
  image: node:22
  script:
    - npm install -g @workloom/cli
    - wl sync --check
  variables:
    WL_TOKEN: $CI_WORKLOOM_TOKEN

Other CI Systems

Any CI system that can run Node.js can use Workloom:

npm install -g @workloom/cli
export WL_TOKEN="your-ci-token"
wl sync --check

Understanding Exit Codes

Code	Meaning	CI Action
0	Clean — files match desired state	Pass
1	Drift detected	Fail — files diverged
2	Auth error	Fail — check token
3	Network error	Retry or fail
4	Conflict	Fail — manual resolution needed
5	Policy violation	Fail — trust gate blocked

Service Account Tokens

CI environments use service account tokens with scoped permissions:

# Create a CI-scoped token (via web UI or API)
# Permissions: read-only, sync-check only
# Cannot: publish, approve, modify workspace

Store as a CI secret:

• GitHub: Settings → Secrets → WORKLOOM_CI_TOKEN
• GitLab: Settings → CI/CD → Variables

Advanced Patterns

Locked Builds (Deterministic)

For maximum reproducibility, commit .loom/lock.json and use locked mode:

- name: Check with locked versions
  run: wl sync --check --locked

This verifies against exact locked versions — no resolution, no network calls to the registry (beyond token validation).

Drift Report as PR Comment

- name: Check drift
  id: drift
  run: |
    wl sync --check 2>&1 | tee drift-report.txt
    echo "exitcode=$?" >> $GITHUB_OUTPUT
  continue-on-error: true

- name: Comment on PR
  if: steps.drift.outputs.exitcode != '0'
  uses: actions/github-script@v7
  with:
    script: |
      const fs = require('fs');
      const report = fs.readFileSync('drift-report.txt', 'utf8');
      github.rest.issues.createComment({
        owner: context.repo.owner,
        repo: context.repo.repo,
        issue_number: context.issue.number,
        body: `## AI Config Drift Detected\n\n\`\`\`\n${report}\n\`\`\``
      });

Scheduled Drift Monitoring

Check for drift on a schedule (not just PRs):

name: Scheduled Drift Monitor
on:
  schedule:
    - cron: '0 9 * * 1-5' # Weekdays at 9am

jobs:
  drift-monitor:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4
      - run: npm install -g @workloom/cli
      - name: Check drift
        run: wl sync --check
        env:
          WL_TOKEN: ${{ secrets.WORKLOOM_CI_TOKEN }}
      - name: Alert on drift
        if: failure()
        run: |
          # Send Slack notification, create issue, etc.
          echo "Drift detected on $(date)"

Multi-Target Monorepo

For monorepos with multiple targets, wl sync --check checks all targets:

$ wl sync --check
Checking target: root (.)
  ✓ 3 files clean
Checking target: web (apps/web)
  ✗ 1 file drifted: apps/web/CLAUDE.md
Checking target: api (services/api)
  ✓ 2 files clean

Exit code: 1 (drift detected)

Best Practices

1. Make it a required check: Block merges when drift is detected.
2. Use read-only tokens: CI should never have publish permissions.
3. Commit the lock file: Enables --locked mode for deterministic checks.
4. Run on PRs AND main: Catch drift from both sides.
5. Alert on scheduled failures: Don't let drift accumulate silently.
6. Keep the CLI version pinned: npm install -g @workloom/cli@1.x for reproducibility.