Sync AI Agent Rules Across Repositories with GitHub Actions

Your team improves an AGENTS.md instruction in one repository. A week later, another service still has the old rule. Cursor configuration has drifted too, and the shared Claude prompt was copied into only three of six projects.

This is an ordinary configuration-management problem hiding inside an AI tooling workflow. Copying files by hand does not scale, but pushing changes directly to protected default branches is not a good answer either.

In this tutorial, we will use team-ai-sync to keep AI agent instructions, prompts, and editor rules consistent across repositories. The workflow starts in dry-run mode, then distributes changes through normal pull requests so every update remains visible and reviewable.

What we are building

We will use one repository as the source of truth for shared AI guidance. A GitHub Actions workflow in that repository will:

1. Read a versioned synchronization manifest.
2. Compare the selected files with their destinations.
3. Preview changes without writing anything.
4. Create or update a pull request in each target repository after dry-run verification.

This approach is useful for files such as:

• AGENTS.md and CLAUDE.md
• GitHub Copilot instruction files
• Cursor and Windsurf rules
• reusable prompts
• team-specific documentation for coding agents

The tool synchronizes files, not hidden model context. It does not decide whether AI authored anything, and it should never be used to distribute secrets.

Prerequisites

You need:

• a GitHub repository that will hold the canonical files;
• one or more target repositories;
• permission to create branches and pull requests in those targets;
• a fine-grained personal access token or GitHub App token for cross-repository access.

The normal workflow GITHUB_TOKEN can read the source repository. Cross-repository writes require a separate token because the built-in token is scoped to the repository running the workflow.

For a fine-grained token, grant access only to the target repositories. The documented minimum is:

• Contents: read and write
• Pull requests: read and write
• Metadata: read
• Issues: read and write only when you want the workflow to apply labels

Store the token as a repository or organization Actions secret. In this example, the secret is named TEAM_SYNC_ADMIN_PAT.

Step 1: Create the canonical files

Suppose your source repository has this structure:

shared-ai-guidance/
├── AGENTS.md
├── prompts/
│   └── review.md
└── .github/
    └── sync-config.json
~~~

Keep these files in Git like any other engineering policy. Changes then have authors, reviews, commit history, and an obvious rollback path.

## Step 2: Define the synchronization manifest

Create `.github/sync-config.json`:

~~~json
{
  "version": 1,
  "defaults": {
    "branchName": "chore/sync-ai-guidance",
    "commitMessage": "chore: sync shared AI guidance",
    "prTitle": "chore: sync shared AI guidance",
    "deleteOrphans": false
  },
  "targets": [
    {
      "repo": "your-org/api-service",
      "files": [
        {
          "source": "AGENTS.md",
          "destination": "AGENTS.md"
        },
        {
          "source": "prompts/review.md",
          "destination": ".github/prompts/review.md"
        }
      ]
    },
    {
      "repo": "your-org/web-app",
      "files": [
        {
          "source": "AGENTS.md",
          "destination": "AGENTS.md"
        }
      ]
    }
  ]
}
~~~

Replace the placeholder repository names with repositories you control.

The explicit source and destination paths make the contract easy to audit. team-ai-sync also validates paths: absolute paths, traversal through `..`, and `.git` paths are rejected. `deleteOrphans` is disabled by default, which makes initial adoption safer because an incomplete manifest will not remove files from target repositories.

## Step 3: Add the GitHub Actions workflow

Create `.github/workflows/sync-ai-guidance.yml` in the source repository:

~~~yaml
name: Sync AI guidance

on:
  workflow_dispatch:
  push:
    branches:
      - main
    paths:
      - AGENTS.md
      - prompts/**
      - .github/sync-config.json

permissions:
  contents: read

jobs:
  sync:
    runs-on: ubuntu-latest
    steps:
      - name: Check out the source repository
        uses: actions/checkout@v4

      - name: Preview synchronization
        uses: paladini/team-ai-sync@v1
        with:
          github-token: ${{ secrets.TEAM_SYNC_ADMIN_PAT }}
          config-path: .github/sync-config.json
          dry-run: true
~~~

Pinning `paladini/team-ai-sync@v1` follows the stable major-version example from the project documentation. For stricter supply-chain control, you can pin an immutable commit SHA and update it deliberately.

The `paths` filter prevents unrelated source changes from starting the job. Keeping `workflow_dispatch` is helpful while introducing the workflow because you can test configuration changes manually.

## Step 4: Run the dry run first

Commit the files, open the Actions tab, and run **Sync AI guidance**.

With `dry-run: true`, team-ai-sync calculates the work but does not push branches or create pull requests. Inspect the job log and confirm:

- every intended target is listed;
- every source resolves to the expected destination;
- no unrelated file is included;
- authentication works for all targets.

This is the most important rollout step. It separates configuration validation from mutation.

The action also exposes outputs including `changed`, `synced-targets`, `failed-targets`, and `pr-urls`. They are useful if you later want a summary step or a notification, but the first run should stay simple.

## Step 5: Enable reviewable synchronization

After the dry run is correct, remove this line:

~~~yaml
dry-run: true
~~~

Run the workflow again. For each repository with changes, the action creates or updates its synchronization branch and pull request. It does not merge the PR, approve it, bypass branch protection, or modify repository settings.

Review the generated diff exactly as you would review any other cross-repository policy change. The project includes a [public end-to-end demo pull request](https://github.com/paladini/team-ai-sync-demo-api/pull/1), so you can inspect the resulting workflow before enabling it in your own organization.

## Verification checklist

Before expanding to more repositories, verify one target end to end:

1. The workflow completes successfully.
2. The pull request contains only the configured files.
3. The destination paths are correct.
4. Branch protection still requires the expected reviews and checks.
5. A second run updates the existing PR instead of creating noisy duplicates.
6. A run with no source changes produces no unnecessary target change.

For implementation details, use the project's current [getting-started guide](https://github.com/paladini/team-ai-sync/blob/main/docs/getting-started.md), [authentication guide](https://github.com/paladini/team-ai-sync/blob/main/docs/authentication.md), and [security model](https://github.com/paladini/team-ai-sync/blob/main/docs/security.md). The action is also listed on the [GitHub Marketplace](https://github.com/marketplace/actions/team-ai-sync).

## Security boundaries and limitations

Centralization increases consistency, but it also increases the importance of the source repository and its credentials.

- Protect changes to the canonical files with code owners and required review.
- Scope tokens to the smallest possible repository set and permissions.
- Prefer a GitHub App for long-lived organization-wide automation.
- Never place secrets, credentials, or private model context in synchronized files.
- Start with one target and dry-run mode before broad rollout.
- Keep destructive orphan deletion disabled until its behavior is explicitly required and tested.

team-ai-sync supports GitHub Actions, GitLab CI/CD components, and a Bitbucket Pipe, but a single synchronization package targets repositories on the same platform. This tutorial intentionally covers GitHub only.

## Frequently asked questions

### Does team-ai-sync write directly to the default branch?

No. It creates or updates a branch and pull request. Your existing review rules, checks, and branch protection remain the approval boundary.

### Can I synchronize different files to different repositories?

Yes. Each target declares its own file mappings, so a backend service can receive a different subset from a frontend project.

### What happens when a canonical file changes again?

The next workflow run compares the new source content with each destination and updates the synchronization pull request when needed.

### Is this limited to `AGENTS.md`?

No. It works with repository files in general. AI agent instructions, prompts, editor rules, and supporting documentation are common use cases.

## A practical next step

Start with one low-risk instruction file and one target repository. Run the workflow in dry-run mode, inspect the plan, and only then enable pull-request creation. Once that path is trustworthy, add repositories incrementally.

The goal is not merely to copy files faster. It is to make shared AI guidance behave like maintained engineering configuration: versioned, reviewable, reproducible, and difficult to forget.

> Disclosure: This article was researched, fact-checked, and drafted with AI assistance using the current primary project sources linked above.

How does your team currently prevent AI agent instructions from drifting across repositories?