Automatic cross-repo syncing between two GitHub repos

This feature is to automatically sync between repos, mainly in the private and public repo scenario.

Syncing from one repo to another will happen on the committed content on the branch. So if there are any pending Pull Requests into Repo A source branch, that content will not be merged into Repo B target branch. You will still have to manually accept any pull requests that are coming to your branches before the syncing can happen.

Note

Currently, we don't support provision of cross-repo syncing in OPS self-service portal. Please contact your Engagement PM AND Sandra Aldana if you want to use this feature.

Note

We don't support syncing data between two VSO repos, or from GitHub repo to VSO repo, or vice-versa.

Provision data syncing between two GitHub repos

Here is an explanation of the configuration. Note that for the example, we'd like to setup a cross-repo syncing relationship between repo A (branch live) and repo B (branch live).

Item Meaning Required? Example
repo A's URL The repo you are syncing from Yes https://github.com/MicrosoftDocsVirtualization-Documentation-Private
repo A's syncing branch The branch you are syncing from Yes live
repo A's working branch The branch used by OPS to resolve conflicts in PRs. No. If not provided, OPS will append -sync-work to syncing branch. live-sync-work
repo B's URL The repo you are syncing to Yes https://github.com/MicrosoftDocs/Virtualization-Documentation
repo B's syncing branch The branch you are syncing to Yes live
repo B's working branch The branch used by OPS to resolve conflicts in PRs. No. If not provided, OPS will append -sync-work to syncing branch as the name for working branch. live-sync-work
whether to require a PR opened when syncing from repo A to repo B
  • If Push, changes in repo A's syncing branch will be pushed into repo B's syncing branch automatically if there is no conflict.
  • If Pull Request, OPS will open a PR for users to confirm the merge.
  • In either case, if there is conflict, a PR will be opened for users to resolve and resume syncing.
Yes Push
whether to require a PR opened when syncing from repo B to repo A
  • If Push, changes in repo A's syncing branch will be pushed into repo B's syncing branch automatically if there is no conflict.
  • If Pull Request, OPS will open a PR for users to confirm the merge.
  • In either case, if there is conflict, a PR will be opened for users to resolve and resume syncing.
Yes Pull Request
user id The user should have Admin permission in both repos,so OPS will use the credential of the user to create webhooks on both repos. Yes hexiaokai

Note

It is recommended that users grant openpublishbuild account Write permission in both repos. This account will be used to open PRs during syncing.

Information needed

For each repo syncing, you need to provide a pair. In the case of private and public repo scenario, this is the information you need to provide:

Source Repo Source Branch Target Repo Target Branch Action Account for syncing
Source repo URL Private repo branch name Public repo URL Public repo branch name Push or Pull Account for syncing

Tip

If you would like to sync from repo A to B and from B to A, you need to provide two sets of configurations.

Recommendation

If you have a private repo to author your content and publish to docs, and a public repo to get external contributions, we recommend the following configuration. For simplicity, we are avoiding the working branches and let OPS use the default options.

  1. private repo, live branch -> public repo, live branch -> Push a. To automatically update the public repo with the content that gets published to docs
  2. public repo, live branch -> private repo, master branch -> PR a. To automatically bring the updates back from external community to your private repo, so it can be incorporated with the content and published live

It transforms in the following table:

Source Repo Source Branch Target Repo Target Branch Action Account for syncing
Private repo URL live Public repo URL live Push Account for syncing
Public repo URL live Private repo URL master Pull Account for syncing

Technical details behind the syncing

See techinical design document here.