Sync with GitHub

How to Set Up Bi-Directional Sync with GitHub

Prerequisites

• You will need a GitHub account.
• When syncing to a repository in an organization, you will need permission to create an empty repository.

Set Up

1. Navigate to Settings > Git Connection page.
2. Select GitHub.
3. If you haven’t already, create an empty repository in GitHub—make sure to uncheck the option to create a README.
4. Sync with your provider and authenticate. Grant access to the repository you’d like to sync with and confirm your repository on the next screen.

Changing Repositories

1. Within ReadMe, disconnect the project via the trash icon.
2. Within GitHub, create your new repository (must be empty).
3. Navigate to Applications > Installed GitHub Apps.
4. Find ReadMe Sync and click Configure.
5. Under Repository access, select the new repository you’d like to sync to.
6. Return to ReadMe and connect to your new repository.

Editing Your Docs

Branches

• The initial commit from ReadMe is to establish branch synchronization with GitHub
• Branch names must exactly match the version names defined in ReadMe
• Any mismatched version and names will exist in GitHub and will not sync with ReadMe.

ReadMe: v2.0_new-branch
GitHub: v2-new-branch
		

ReadMe: v2.0_new-branch
GitHub: v2.0_new-branch
		

GitHub Enterprise Server

If you’re using a self-hosted GitHub Enterprise Server (GHES), you can set up syncing from your Group dashboard under Git Connection. Syncing requires a new, empty repository, and each child project can only sync to one repository.

If GHES isn’t available for your project, please contact your Customer Success Manager.

GitHub Branch Protection

If your GitHub repository uses branch protection rules, you’ll need to configure them to allow the ReadMe Sync app to push changes. Here's how to set it up based on your GitHub configuration:

For GitHub Rulesets (New Version)

1. Navigate to your repository’s branch protection settings.
2. Under the Bypass list section,+ Add bypass.
3. Search for ReadMe Sync (App • readmeio) and set the permission to Always allow.

For Legacy Branch Protection

1. Go to your repository’s branch protection rules.
2. Find the Allow specified actors to bypass required pull requests section.
3. Add readme-sync (ReadMe Sync) to the allowed actors list.

This configuration ensures that changes made in ReadMe’s editor can be synchronized to protected branches in your GitHub repository.

FAQ