Sync Shared AI Guidance Across Repositories with team-ai-sync

Teams often agree on a shared AGENTS.md, CLAUDE.md, prompt directory, or editor configuration, then discover that every repository has a slightly different copy. Manual copying is easy to start and hard to trust. A stale instruction can change how an AI coding agent edits a codebase, while a direct write to a default branch removes the review point that should catch the mistake.

This tutorial shows how to use team-ai-sync to keep shared AI guidance in one source repository and distribute it through reviewable pull requests. The example uses the stable v1 Action, a JSON configuration file, and a dry run before any branch or pull request is created.

TL;DR

Create a sync-config.json file that names target repositories and repository-relative paths. Call paladini/team-ai-sync@v1 from GitHub Actions with a token that can update the targets. Start with dry-run: true, inspect the result, then allow the Action to create or update pull requests. The tool does not merge those requests for you.

Prerequisites

You need:

• A source GitHub repository containing the shared files.
• One or more target repositories that the token can read and write.
• A fine-grained personal access token or GitHub App token with Contents: Read and write and Pull requests: Read and write on the targets. Issues: Read and write is also needed when the configuration applies labels.
• A GitHub Actions workflow that can read the source repository.

The stable v1 Action runs on Node 24. The repository's v1 tag documents GitHub Actions, GitLab CI/CD, and Bitbucket packages, but this walkthrough focuses on GitHub.

1. Create the source configuration

Put the files that should be shared in the source repository. For example, this can be an AGENTS.md file plus instructions under .github/instructions.

Create sync-config.json beside those files:

{
  "targetRepositories": [
    "your-org/api-service",
    "your-org/web-app"
  ],
  "syncMode": "overwrite",
  "deleteOrphans": false,
  "files": ["AGENTS.md", "CLAUDE.md", ".editorconfig"],
  "directories": [".github/instructions", ".github/prompts"],
  "exclude": [],
  "prOptions": {
    "title": "chore: sync team AI assets",
    "body": "Synced from {{sourceRepo}} at {{sourceCommit}}.",
    "commitMessage": "chore(ai-assets): sync team assets",
    "branch": "chore/team-ai-sync",
    "labels": ["automation", "chore"],
    "userReviewers": [],
    "teamReviewers": []
  }
}

The configuration requires at least one file or directory. overwrite replaces an existing configured path. Use skip when the first sync should install starter files without replacing local edits. Directories are copied recursively, and exclude accepts repository-relative paths or glob patterns.

Keep target names and paths intentional. The project validates paths before processing targets and rejects absolute paths, .. traversal, .git segments, and paths that resolve outside a repository root.

2. Add the workflow

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

name: Sync AI Assets

on:
  push:
    branches: [main]
  workflow_dispatch:

jobs:
  sync:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4
      - uses: paladini/team-ai-sync@v1
        with:
          github-token: ${{ secrets.TEAM_SYNC_ADMIN_PAT }}
          config-path: sync-config.json

Create the TEAM_SYNC_ADMIN_PAT repository secret in the source repository. The source workflow's GITHUB_TOKEN only needs to read the source checkout. The separate github-token input is the credential used to clone target repositories, push sync branches, and create or update pull requests.

The Action also accepts source-root and dry-run. The default configuration path is sync-config.json, so config-path is optional when you use that name.

3. Run a dry run first

Before opening pull requests, add the dry-run input:

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

The dry run validates the configuration, clones targets into temporary worktrees, copies the configured paths, and reports whether changes exist. It does not push branches or create pull requests. This makes it the right first check for a new target list and for changes to deleteOrphans.

When the dry run is clean, remove dry-run: true or set it to false. A real run resolves each target's default branch, creates or resets the configured sync branch, copies files, commits only when changes exist, pushes the branch, and creates or updates one pull request per changed target.

Expected result

For each target with changes, the result should be a normal pull request from the configured sync branch. The generated request is where a target repository owner can review the exact file changes, discuss them, and decide when to merge.

The Action exposes JSON outputs for pr-urls, synced-targets, failed-targets, and changed. A later run with no differences should report changed=false for the no-change case. The project's public demo documents this lifecycle with a dry run, pull request creation, an update to existing requests, a merge, and a final no-change run.

Why this review boundary matters

The useful design choice is not only central storage. team-ai-sync keeps synchronization separate from approval. It creates or updates branches and pull requests, but it does not merge requests, bypass branch protection, approve requests, manage secrets, or change target repository settings.

That boundary supports a practical operating model: keep shared guidance in one source repository, let automation prepare changes, and let each target repository review the change in its own context. A repository can still reject an instruction that is inappropriate for its language, deployment model, or security requirements.

Security boundaries and failure modes

Treat the token as a write credential. Store it as a repository or project secret, grant access only to the targets that need synchronization, and never put it in sync-config.json or a committed workflow file.

Do not distribute private keys, credentials, or machine-specific settings. The project is designed for reviewable guidance, prompts, editor settings, and repository conventions. It cannot make a shared instruction safe merely because the file arrived through a pull request.

Be especially careful with deleteOrphans. It defaults to false. When enabled, deletion is limited to files inside configured synced directories, but it can still remove target files that are no longer present in the source. Run a dry run first and review the proposed changes.

A missing configured file or directory fails validation before pull requests are created. A target can fail independently while other targets continue, so inspect failed-targets rather than treating a successful workflow as proof that every repository changed. Cross-platform synchronization is not the supported operating model: use the GitHub Action for GitHub targets, the GitLab component for GitLab projects, and the Bitbucket pipe for Bitbucket repositories.

Reproducible verification

The v1 checkout of the repository was verified locally with the documented development commands:

npm ci
npm run lint
npm test
npm run build

The checks completed successfully: TypeScript linting passed, 6 test files with 18 tests passed, and the bundled Action build completed. npm ci also reported 9 dependency audit findings, including 7 high-severity findings, so that result is a dependency warning rather than a security guarantee.

To verify your own rollout, keep the first target set small. Compare the dry-run output with the source files, inspect the generated pull request, and confirm that the target branch contains only the configured paths. Then merge manually and run the workflow again to verify the no-change behavior.

FAQ

Does it merge pull requests automatically?

No. It creates or updates pull requests and leaves review, approval, and merge to target repository maintainers.

Can I sync only files that are missing?

Yes. Set syncMode to skip. The default overwrite mode replaces existing configured paths.

Can I remove stale files?

Set deleteOrphans to true only for configured synced directories. Review a dry run first.

Which files can I sync?

The documented examples include AGENTS.md, CLAUDE.md, Copilot instructions, prompt directories, Cursor rules, .editorconfig, and other repository-relative files or directories.

Does the Action need a secret?

Yes, when it must access target repositories. Use the github-token input with a suitably scoped PAT or GitHub App token stored as a secret.

Takeaway

Centralizing AI guidance is useful only when updates remain reviewable. team-ai-sync turns a shared-file problem into a normal branch and pull request workflow: validate paths, dry-run the target set, inspect the generated changes, and keep the final merge decision with each repository.

Have you found a better review policy for synchronizing AGENTS.md or prompt files across a repository fleet? Share the rule that has prevented the most drift in your team.

AI assistance disclosure

AI assistance was used to organize and edit this tutorial. The repository documentation, stable v1 examples, license, security model, and local verification results were checked against primary sources before publication.

Sources

• team-ai-sync README at the stable v1 tag
• team-ai-sync getting started guide
• team-ai-sync configuration reference
• team-ai-sync security model
• team-ai-sync MIT license