Why Check Rules in CI/CD
Developers may forget to run rulesync pull after a ruleset update. Without a CI check: the code is built and deployed with outdated rules. The AI: may have generated code using old conventions that are no longer current. With a CI check (rulesync pull --check): the pipeline fails if the local rule files are outdated. The developer: runs rulesync pull, commits the updated files, and pushes again. The deployment: only proceeds with current rules.
The rulesync pull --check command: compares the local CLAUDE.md (and other output files) against the current version in the RuleSync dashboard. If they match: exit code 0 (success, pipeline continues). If they differ: exit code 1 (failure, pipeline stops with a message: 'AI rules are outdated. Run rulesync pull to update.'). The check: is read-only — it does not modify any files. It only verifies freshness.
Where to add the check: as an early step in the CI pipeline, before lint, tests, or build. If the rules are outdated: there is no point running the rest of the pipeline on code that may have been generated with old conventions. Fail fast: the rule check takes 2-3 seconds. Failing at this stage: saves the time of running lint (30 seconds), tests (2 minutes), and build (2 minutes) on code that will need to be updated anyway.
Step 1: GitHub Actions Integration
Add the RuleSync check to your GitHub Actions workflow. In .github/workflows/ci.yml, add a step before your lint/test/build steps: - name: Check AI rules freshness, run: npx rulesync pull --check, env: RULESYNC_API_KEY: ${{ secrets.RULESYNC_API_KEY }}. The npx rulesync: downloads the CLI on the fly (no global install needed in CI). The --check flag: verifies without modifying files. The API key: from GitHub Secrets.
For projects with RuleSync as a devDependency (recommended for CI): pnpm exec rulesync pull --check (or npx rulesync pull --check). The devDependency: locks the CLI version (no surprise behavior changes from a new CLI version). The check: runs against the locked version, ensuring consistent behavior. AI rule: 'DevDependency for CI: locks the CLI version. npx for quick setup: downloads the latest version. DevDependency is more predictable for production pipelines.'
Workflow example: the rule check runs as the first job step. If it fails: the workflow stops. No lint, no tests, no build, no deploy. The developer sees: 'AI rules are outdated' in the GitHub Actions log. They: run rulesync pull locally, commit the updated files, push. The workflow: runs again and the check passes. Total developer effort: 2 minutes. AI rule: 'The rule check is the first step. Fail fast. Do not waste CI minutes on outdated code.'
The rule check takes 2-3 seconds. If it fails: the developer knows immediately (no waiting for lint, tests, and build to complete first). If it passes: the rest of the pipeline runs on verified-current code. Placing the check after the build: wastes 4+ minutes of CI time on every run where rules are outdated. First step: maximum time savings when the check fails, zero overhead when it passes.
Step 2: GitLab CI Integration
In .gitlab-ci.yml, add a stage for the rule check. stages: [check-rules, lint, test, build, deploy]. The check-rules job: image: node:20-alpine, script: ['npx rulesync pull --check'], variables: RULESYNC_API_KEY: $RULESYNC_API_KEY. The variable: set as a CI/CD variable in GitLab (masked and protected). The stage: runs before lint, test, and build.
GitLab-specific optimization: use the allow_failure: false setting (default) to ensure the pipeline stops on outdated rules. For non-blocking checks (advisory mode during the rollout period): set allow_failure: true. The job: logs the outdated status but the pipeline continues. After the team is accustomed to keeping rules current: switch to allow_failure: false (blocking). AI rule: 'Start with advisory (allow_failure: true) during the first month. Switch to blocking after the team is reliably keeping rules current.'
Caching: the RuleSync CLI downloads and caches the current ruleset data. In GitLab CI: cache the npm cache directory to speed up repeated npx rulesync calls. cache: paths: [.npm/]. The first run: downloads the CLI and checks rules (5 seconds). Subsequent runs with cache: checks rules (2 seconds). AI rule: 'Caching the npm cache: saves 3 seconds per CI run. Across 50 pipelines per day: 2.5 minutes saved daily. Small but free optimization.'
Day 1: enable the rule check in blocking mode. 15 CI pipelines fail across the organization because teams have not run rulesync pull recently. 15 teams: frustrated. Confidence in the CI check: damaged. Better: start with advisory mode (GitLab allow_failure: true, GitHub Actions continue-on-error: true). The check: logs warnings but does not block. Teams: learn to keep rules current without pipeline disruption. After 2-4 weeks: switch to blocking. By then: most teams are already current.
Step 3: Advanced CI Patterns
Auto-update in CI: instead of just checking, the CI pipeline can automatically update rules and commit. Pattern: rulesync pull (generates updated files) → git add CLAUDE.md .cursorrules → git commit -m 'chore: update AI rules to latest' → git push. This auto-update: keeps rules current without developer intervention. Use with caution: the auto-commit changes files in the repository without human review. Recommended: only for the base branch, with a notification to the team when an auto-update occurs.
Conditional checks: only run the rule check when relevant files have changed. If the PR only modifies documentation (README.md, docs/): skip the rule check (the rules are not relevant to docs-only changes). Pattern: use path filters in GitHub Actions (paths: ['src/**', 'CLAUDE.md']) or rules in GitLab CI (rules: [changes: ['src/**', 'CLAUDE.md']]). The filter: reduces unnecessary CI runs. AI rule: 'Conditional checks: reduce CI noise for non-code PRs. But for code PRs: always check rules. The code PR is where outdated rules have the most impact.'
Multi-project checks: for monorepos with multiple projects, run rulesync pull --check for each project in the CI pipeline. Each project: may have different rulesets assigned. The check: verifies each project's rules independently. Pattern: a matrix job in GitHub Actions (strategy: matrix: project: [frontend, api, worker]) or parallel jobs in GitLab CI. AI rule: 'Monorepo: check each project independently. One project may have current rules while another is outdated. Per-project checks: catch the specific outdated project.'
Auto-update in CI: the pipeline pulls new rules and commits them automatically. The benefit: rules are always current, no developer intervention. The risk: a bad ruleset update is automatically committed to the repository before anyone reviews it. The recommendation: auto-update for non-critical branches (development, staging). Manual update (developer runs rulesync pull, reviews, commits) for the main branch. This balances automation with human oversight.
RuleSync CI/CD Summary
Complete RuleSync CI/CD integration guide.
- Command: rulesync pull --check. Read-only. Exit 0 if current, exit 1 if outdated. 2-3 seconds
- Position: first step in CI pipeline. Before lint, test, build. Fail fast on outdated rules
- GitHub Actions: npx rulesync pull --check with RULESYNC_API_KEY from secrets
- GitLab CI: check-rules stage with masked CI variable. Start advisory, then switch to blocking
- DevDependency: locks CLI version for predictable CI behavior. Preferred over npx for production
- Auto-update: CI pulls and commits updated rules. Use with caution — auto-modifies the repo
- Conditional: skip for docs-only PRs. Always check for code PRs
- Monorepo: per-project checks via matrix jobs. Each project verified independently