A powerful GitHub Action workflow that automatically synchronizes repositories, allowing you to maintain mirrors or backups of your code with flexible branch mapping. You can direcly use this as a template and create your project without any other work or copy and pasting.

• Automatic Syncing: Synchronize repositories on every push or manually trigger syncs
• Smart Branch Mapping: Configurable branch mapping with intelligent defaults
• Status Tracking: Generates detailed sync status reports
• Flexible Configuration: Use environment variables or repository secrets
• Secure: Uses token-based authentication for secure operations

Create a file at .github/workflows/repo-sync-bot.yml in your source repository and copy the workflow provided in this repository.

You need a Personal Access Token (PAT) with appropriate permissions:

1. Go to your GitHub account → Settings → Developer settings → Personal access tokens → Fine-grained tokens (or Classic tokens)
2. Create a new token with the following permissions:
   • repo scope for private repositories
   • public_repo scope for public repositories
   • Add workflow scope if you want to sync workflow files
3. Copy the token

In your source repository:

1. Go to Settings → Secrets and variables → Actions
2. Add a new repository secret:
   • Name: SYNC_TOKEN
   • Value: Your personal access token

Choose one of these two configuration methods:

Create a .env file in the root of your source repository:

If you prefer not to commit a .env file, add this secret instead:

• Name: TARGET_REPO_URL
• Value: https://github.com/username/target-repo.git

The workflow follows these rules for determining which branch to use in the target repository:

1. If TARGET_BRANCH is specified in the .env file:

   • Use that branch regardless of which branch you're pushing to

2. If no TARGET_BRANCH is specified AND source branch is 'main':

   • Use 'RepoBot' branch in the target repository

3. If no TARGET_BRANCH is specified AND source branch is not 'main':

   • Use the same branch name as the source

After each sync, a sync-status.md file is created in the target repository with detailed information about:

• When the sync occurred
• Latest commit details
• Branch information
• Repository links

You can manually trigger a sync from the Actions tab in your repository:

1. Go to the Actions tab
2. Select "Sync Repositories" workflow
3. Click "Run workflow"
4. Optionally enable force push
5. Click "Run workflow" button

You can add multiple co-authors to commits made by the sync bot. This is useful for:

• Properly attributing contributions when syncing collaborative work
• Ensuring commit history reflects all contributors
• Maintaining accurate authorship in mirrored repositories

To add co-authors, include them in the .env file:

CO_AUTHORS="Example1 <[email protected]>, Example2 <[email protected]>"

• The sync token should have the minimal permissions needed
• Never commit your personal access token to the repository
• Consider using a dedicated bot account for syncing if you're syncing many repositories

1. Fork or Clone: Fork this repository or clone it to your local machine to get started

2. Customize the Workflow: Modify the workflow file if needed to match your specific requirements

3. Setup Authentication:

   • Create a Personal Access Token with appropriate permissions
   • Add the token as a repository secret named SYNC_TOKEN

4. Configure Target Repository:

   • Create a .env file with your target repository details
   • Example:

     TARGET_REPO_URL=https://github.com/Saviru/your-target-repo.git
     TARGET_BRANCH=target-branch
     CO_AUTHORS="Example1 <[email protected]>, Example2 <[email protected]>"
     

5. Test the Workflow:

   • Push a change to your repository
   • Go to the Actions tab to see the workflow run
   • Check the target repository to verify the sync

6. Monitor and Maintain:

   • Review the sync-status.md file in your target repository
   • Occasionally check that syncs are working as expected
   • Update your token if it expires

Issue: Workflow fails with authentication errors

• Solution: Verify your SYNC_TOKEN has the correct permissions.

Issue: Files aren't syncing correctly

• Solution: Check the workflow run logs for errors and verify your .env configuration.

Issue: Workflow files not syncing

• Solution: Your token needs the workflow scope to sync workflow files.

Issue: Co-authors not appearing in commits

• Solution: Ensure the CO_AUTHORS format is correct with name and email in angle brackets.

For more complex branch mapping requirements, modify the workflow file's branch logic section to implement custom mapping rules.

This project is licensed under the GNU General Public License v3.0 - see the LICENSE file for details.

Developed and maintained by @Saviru

Made with ❤️ for the GitHub community