ethicalsecurity-agency / repo-sync-repo-sync

repo-sync / repo-sync

Repo Sync

Keep a pair of GitHub repos in sync.

How it Works

This project uses GitHub Actions workflows to keep pairs of git repos in sync. It runs on a schedule (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 before you begin.)
• Your repos must be using GitHub Actions v2. Sign up at 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://<access_token>@github.com/owner/repo.git that includes an access token with repo and workflow scopes. You can generate a token 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:

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 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.

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):

Wei He 🎨 💻 📖

Zeke Sikelianos 📖 🤔

This project follows the all-contributors specification. Contributions of any kind welcome!