team-ai-sync
GitHub Docker Hub

Open-source repo file sync for AI teams

Sync AI guidance files across repositories

team-ai-sync copies files such as AGENTS.md, CLAUDE.md, prompts, editor settings, and repository rules from one source repo to many target repos. It does not merge directly. It opens pull requests or merge requests so each team can review the change.

You maintain one source repo. Put the files every project should share in one place.
CI runs team-ai-sync. The tool validates config, copies files, and creates a branch.
Targets get PRs or MRs. Repository owners review and merge the generated updates.
Get started View docs
GitHub Action GitLab Component Bitbucket Pipe MIT licensed 
targetRepositories:
  - your-org/api-service
  - your-org/web-app
files:
  - AGENTS.md
  - CLAUDE.md
directories:
  - .github/instructions
  - .github/prompts
Source repo shared AI assets
team-ai-sync validate, copy, branch
PR #18 api-service chore: sync team AI assets
MR #42 web-app reviewable changes
Problem it solves Stop manually copying AI instructions and prompt files across many repos.
Best fit Platform, DevEx, and engineering teams that manage many service repos.
Result Consistent agent guidance, prompts, and repo rules with reviewable changes.

How it works

One config file controls what gets copied and where it goes

The source repository owns sync-config.json and the shared files your team wants to standardize. A CI workflow runs team-ai-sync, clones each target, copies configured files, pushes a sync branch, and opens or updates one review request per changed repository.

  1. 01
    Maintain shared files

    Store agent instructions, prompts, editor defaults, and repo conventions in a source repo.

  2. 02
    Declare target repositories

    List target repos, files, directories, exclusions, branch names, labels, and reviewers.

  3. 03
    Run CI/CD automation

    Validate paths, simulate with dry runs, then create or update branches when changes exist.

  4. 04
    Review and merge locally

    Target maintainers keep control because generated changes land in PRs or MRs.

Supported platforms

Use the native package for each CI/CD ecosystem

Cross-platform sync is not the operating model. GitHub repositories use the GitHub Action, GitLab projects use the GitLab CI/CD Component, and Bitbucket repositories use the Bitbucket Pipe.

GitHub Actions

Use paladini/team-ai-sync@v1 from the source repository workflow. The token must be able to clone targets, push sync branches, and create pull requests.

Read GitHub setup 
- uses: paladini/team-ai-sync@v1
  with:
    github-token: ${{ secrets.TEAM_SYNC_ADMIN_PAT }}
    config-path: sync-config.json

What to sync

Sync the files developers look for before using AI in a repo

Keep coding-agent instructions, prompt templates, review guidance, editor defaults, and repository conventions aligned across API, web, infrastructure, and service repositories.

AGENTS.md CLAUDE.md .github/copilot-instructions.md .github/instructions/** .github/prompts/** .cursor/rules/** .vscode/extensions.json .editorconfig

Setup path

Start with a dry run, then scale with confidence

1

Pick a source repo

Create a dedicated guidance repo or use an existing platform repo owned by the team.

2

Add sync rules

Define target repositories, files, directories, exclusions, branch names, labels, and reviewers.

3

Store a token

Grant the smallest useful access for cloning targets, pushing branches, and opening review requests.

4

Run a dry run

Validate configuration and inspect planned changes before any branch or PR is created.

5

Open real PRs or MRs

Let target repository maintainers review, approve, and merge generated updates.

Public demo

See the full lifecycle in public repos

The demo shows dry-run validation, PR creation, PR updates, merge, and a final no-change run with changed=false.

Source repo API PR Web PR Demo walkthrough

Documentation

Everything needed for production rollout

Getting started Create the source repo, config, token, and first workflow. Configuration reference Understand every sync-config.json field and default. Authentication Choose tokens and permissions for target repositories. Operations guide Run dry runs, inspect outputs, and operate repository fleets. Security model Review path safety, branch safety, and rollout boundaries. Troubleshooting Diagnose token, permission, branch, label, and config issues.

Safe by default

Designed for reviewable repository operations

team-ai-sync does not merge generated PRs or MRs, bypass branch protection, manage secrets, or change repository settings. It validates paths, rejects traversal, and keeps target maintainers in the approval loop.

Path safety Rejects absolute paths, .., .git, and paths outside repo roots.
Dry-run mode Validate target changes without pushing branches or opening review requests.
Force-with-lease updates Updates existing sync branches without overwriting unexpected remote changes.

Questions developers ask

Plain answers before you install it

What does team-ai-sync do?

It syncs selected files and directories from one source repository to multiple target repositories. Instead of changing target default branches directly, it creates or updates PRs and MRs.

Why would a developer team use it?

Use it when many repos need the same AGENTS.md, CLAUDE.md, prompts, code review rules, editor settings, or AI-agent instructions, and you want updates to stay reviewable.

Does it work only on GitHub?

No. Use the GitHub Action for GitHub repositories, the GitLab CI/CD Component for GitLab projects, and the Bitbucket Pipe for Bitbucket repositories.