How to Sync AI Rules in GitHub Actions

The Sync Architecture: Central Repo → Target Repos

The sync model: one central repository contains the canonical AI rules (github.com/org/ai-rules). Target repositories consume these rules via their CLAUDE.md, .cursorrules, or copilot-instructions.md files. When the central rules change: a GitHub Actions workflow opens PRs in all target repos with the updated rules. Teams review and merge the PRs. This model: ensures all repos get rule updates while preserving team autonomy (they can review before merging).

Central repo structure: rules/ directory containing base.md (organization rules), typescript.md (TypeScript-specific), go.md, python.md (language-specific), and a manifest.json listing all target repos. The manifest: maps each target repo to the rules it should receive (org/frontend-app → base.md + typescript.md, org/api-service → base.md + go.md). A build script concatenates the applicable rules into the final CLAUDE.md for each target.

Why not just copy the file manually? At 5 repos: manual copy works. At 50+ repos: a rule change requires opening 50 PRs by hand. Missing one repo: that repo falls behind. Forgetting to update: the rule change never propagates. GitHub Actions: automates the entire process. Change the central rules → workflow triggers → 50 PRs opened automatically → teams merge at their pace.

Step 1: Create the Sync Workflow (15 Minutes)

In the central rules repo: create .github/workflows/sync-rules.yml. Trigger: on push to main (rules changed) or on schedule (weekly check for drift). The workflow: reads the manifest, generates the composed rule file for each target repo, compares against the current rule file in the target repo, and opens a PR if there is a difference. The PR: includes the diff showing exactly what changed in the rules.

Workflow structure: checkout the central rules repo, read manifest.json for target repos, for each target repo: clone it (using a GitHub App token or PAT with repo scope), generate the composed rules file for that repo's stack, compare with the existing rules file, if different: create a branch, commit the updated rules, and open a PR with a descriptive title ('Update AI rules to v2.4.0') and body ('Changes: added error handling rule, updated TypeScript version reference').

Authentication: the workflow needs write access to target repos. Options: GitHub App (recommended — granular permissions, audit trail), Personal Access Token (simpler but less secure — tied to a person), or Organization token (available in GitHub Enterprise). AI rule: 'Use a GitHub App for production sync workflows. The app permissions: limited to creating branches and opening PRs. No admin access, no delete access.'

💡 The Manifest Maps Repos to Rule Sets

manifest.json: { 'org/frontend-app': ['base.md', 'typescript.md', 'react.md'], 'org/api-service': ['base.md', 'go.md'], 'org/ml-pipeline': ['base.md', 'python.md'] }. Each repo: gets exactly the rules that apply to its stack. The frontend app does not get Go rules. The ML pipeline does not get React rules. The manifest: is the single source of truth for which rules go where.

Step 2: PR Creation and Management

PR content: the PR title includes the rule version ('Update AI rules to v2.4.0'). The PR body includes: what changed (a human-readable changelog — 'Added: error handling rule for Result pattern. Updated: TypeScript version from 5.3 to 5.4. Removed: deprecated lodash import rule.'), why it changed (link to the central repo PR that made the change), and how to verify (a test prompt to run after merging to verify the AI follows the new rules).

PR behavior: if a PR already exists for this target repo (previous update not yet merged): update the existing PR instead of creating a new one. This prevents: PR pile-up (10 unmerged rule update PRs). The team sees one PR with the latest rules, not a chain of incremental updates. AI rule: 'One active rule-update PR per target repo at any time. Update the existing PR when new changes arrive. Close stale PRs only when the team explicitly declines the update.'

Adoption tracking: the workflow logs which repos have merged the latest rules and which have not. After the sync run: generate a report showing: repos with the latest rules (green), repos with a pending PR (yellow), and repos with no PR and outdated rules (red). Post this report to Slack or store it in the central repo. AI rule: 'The adoption report is the sync workflow's most valuable output after the PRs themselves. It gives leadership visibility into which teams have adopted and which need a nudge.'

⚠️ Never Force-Push Rules — Always Open PRs

A sync workflow that pushes directly to main in target repos: bypasses code review, may overwrite team customizations, and triggers CI without human verification. Always open PRs. The PR: shows the diff, allows team review, and can be declined if the update conflicts with team-specific rules. Force-pushing: destroys trust in the sync process. PRs: preserve team autonomy while ensuring visibility.

Step 3: Versioning and Rollback

Rule versioning: tag releases in the central repo (v2.4.0, v2.4.1). Each sync PR references the version. Target repos can pin a specific version (by not merging the PR until they are ready). The version tag in the generated CLAUDE.md header: tells the team and the platform which version they are on. AI rule: 'Semantic versioning for rules. Patch (v2.4.1): typo fix, wording improvement. Minor (v2.5.0): new rule added, existing rule updated. Major (v3.0.0): breaking change that requires team action.'

Rollback: if a rule change causes problems after merging: revert the PR in the target repo (git revert the merge commit). The target repo returns to the previous rules. The central repo: fix the problematic rule and release a new version. The next sync: delivers the fixed rules. AI rule: 'Rollback is git revert. Simple, fast, reliable. The team does not need to manually reconstruct the old rules — git history has them.'

Drift detection: the scheduled sync (weekly) detects drift: someone manually edited the CLAUDE.md in a target repo, diverging from the central rules. The weekly sync: compares the target's CLAUDE.md against what the central repo would generate. If they differ: opens a PR to realign (or flags the drift for investigation if the divergence was intentional). AI rule: 'Drift detection catches: accidental manual edits, rules that were modified during debugging and not reverted, and intentional customizations that should be formalized as team overrides.'

ℹ️ Drift Detection Catches Accidental Manual Edits

A developer debugs an AI issue by temporarily editing CLAUDE.md. They fix the issue but forget to revert the CLAUDE.md change. The rule file now differs from the central rules. Without drift detection: the divergence persists indefinitely. With weekly drift detection: the next sync run flags the difference. Either: revert the manual edit (it was temporary) or formalize the change as a team override in the central repo. Drift: caught and resolved within one week.

GitHub Actions Sync Summary

Complete GitHub Actions rule sync setup.

Architecture: central rules repo → GitHub Actions workflow → PRs to target repos
Central repo: rules/ directory + manifest.json mapping repos to their rule sets
Trigger: on push to main (rule changed) + weekly schedule (drift detection)
PRs: version in title, changelog in body, test prompt for verification. One active PR per repo
Auth: GitHub App (recommended) with branch + PR permissions only
Adoption report: green (current), yellow (PR pending), red (outdated). Posted to Slack
Versioning: semantic (patch/minor/major). Version header in generated CLAUDE.md
Rollback: git revert the merge commit. Central repo fixes the rule. Next sync delivers the fix