Ecosyste.ms: Awesome

An open API service indexing awesome lists of open source software.

Awesome Lists | Featured Topics | Projects

https://github.com/repo-sync/repo-sync

🔄 Keep a pair of GitHub repos in sync
https://github.com/repo-sync/repo-sync

github github-actions

Last synced: about 1 month ago
JSON representation

🔄 Keep a pair of GitHub repos in sync

Awesome Lists containing this project

README 

        
# Repo Sync

[![All Contributors](https://img.shields.io/badge/all_contributors-2-orange.svg?style=flat-square)](#contributors)



> Keep a pair of GitHub repos in sync.



## How it Works



This project uses [GitHub Actions](https://github.com/features/actions) workflows to keep pairs of git repos in sync. It runs on a [schedule](#cron) (every 15 minutes by default). Shortly after changes are made to the default branch of **repo A**, the Actions workflow runs on **repo B** and generates a pull request including the recent changes from **repo A**. If more changes are made to **repo A** before the pull request is merged, those changes will be added to the existing pull request. The same is true in the opposite direction: changes made to **repo B** will eventually get picked up by the workflow in **repo A**. 



## Features



- One-way or two-way sync

- Sync between a private and public repo

- Sync between two private repos

- Sync between two public repos

- Sync from a third-party repo to a Github repo

- Uses Github Actions and a flexible scheduled job. No external service required!



## Requirements



- Your two repos must share a commit history. (If they do not already, you might need to [Combine Git repositories](https://gist.github.com/msrose/2feacb303035d11d2d05) before you begin.)

- Your repos must be using GitHub Actions v2. Sign up at [github.com/features/actions](https://github.com/features/actions)



## Installation



### Step 1. Set up Secrets



[GitHub Secrets] are variables stored on your GitHub repository that are made available in the GitHub Actions environment. There are two (2) required secrets on each repo. Go to **Settings > Security > Secrets and variables > Actions > New repository secret** on your repo page and add the following secrets:



#### `SOURCE_REPO`



The shorthand name or URL of the repo to sync.



- If the source repo is a **public** GitHub repo, use a shorthand name like `owner/repo`.

- If the source repo is a **private** GitHub repo, specify an HTTPS clone URL in the format `https://@github.com/owner/repo.git` that includes an access token with `repo` and `workflow` scopes. You can [generate a token](https://github.com/settings/tokens/new?description=repo-sync&scopes=repo,workflow) in your Github settings.

- If the source repo is not hosted on GitHub, specify an HTTPS URL that includes pull access credentials.



#### `INTERMEDIATE_BRANCH`



The name of the temporary branch to use when creating a pull request, for example, `repo-sync`. You can use whatever name you like, but do NOT use the name of a branch that already exists, as it will be overwritten.



### Step 2. Create Actions workflow files



Create a file `.github/workflows/repo-sync.yml` in **both repositories** and add the following content:



```yaml

name: Repo Sync



on:

  schedule: 

  - cron: "*/15 * * * *" # every 15 minutes. set to whatever interval you like



jobs:

  repo-sync:

    name: Repo Sync

    runs-on: ubuntu-latest

    steps:

    - uses: actions/checkout@v3

    - uses: repo-sync/github-sync@v2

      name: Sync repo to branch

      with:

        source_repo: ${{ secrets.SOURCE_REPO }}

        source_branch: main

        destination_branch: ${{ secrets.INTERMEDIATE_BRANCH }}

        github_token: ${{ secrets.GITHUB_TOKEN }}

    - uses: repo-sync/pull-request@v2

      name: Create pull request

      with:

        source_branch: ${{ secrets.INTERMEDIATE_BRANCH }}

        destination_branch: main

        github_token: ${{ secrets.GITHUB_TOKEN }}

```



To set up two-way sync, create these files in both repositories. To set up one-way sync, you only need to do this step in the target (destination) repository.



### Step 3. Watch the pull requests roll in!



There is no step 3! Once you commit to the repo, the workflows run on the schedule you specified in the workflow file. When repo-sync finds changes, it creates a pull request. If an unmerged repo-sync pull request already exists on the destination repo, repo-sync updates the existing PR.



## Advanced configuration



The workflow file is fully customizable allowing for advanced configurations.



#### cron



The default cron is every 15 minutes. This can be easily adjusted by changing the cron string.



#### Manual events



Instead of triggering workflows using the cron scheduler, you can set up [manual events](https://help.github.com/en/articles/events-that-trigger-workflows#manual-events) to trigger the workflow when the source repo changes.



#### Workflow steps



You can add or remove workflow steps to meet your needs. For example, you might remove the "Create pull request" to commit directly, or you could add a "Merge pull request" step.



#### One-Way Syncs



For one-way syncs, set up the workflow in the target repository only as described above.



#### Customize pull request



You can customize the PR/s title, body, label, reviewer, assingee, and milestone by setting environment variables as explained at [repo-sync/pull-request](https://github.com/repo-sync/pull-request#advanced-options).



#### Use SSH clone URL and deploy keys



You can use a SSH clone URL and specify an `SSH_PRIVATE_KEY` environment variable instead of using the https clone URL.



## Contributors ✨



Thanks goes to these wonderful people ([emoji key](https://allcontributors.org/docs/en/emoji-key)):



  

    Wei He
Wei He
🎨 💻 📖

    Zeke Sikelianos
Zeke Sikelianos
📖 🤔

  



This project follows the [all-contributors](https://github.com/all-contributors/all-contributors) specification. Contributions of any kind welcome!



[GitHub Secrets]: https://help.github.com/en/actions/configuring-and-managing-workflows/using-variables-and-secrets-in-a-workflow

[Actions workflow file]: https://help.github.com/en/articles/configuring-a-workflow