GitHub Enterprise Sync

Connect ReadMe to a GitHub repository to keep your documentation and codebase in sync. This guide covers setup for GitHub Enterprise Cloud and GitHub Enterprise Server (GHES), along with network and repository requirements to get started.

Connect a Standard GitHub Repository

Follow the instructions to connect a repository hosted using GitHub. Use this option if your team doesn't use GitHub Enterprise Cloud or GitHub Enterprise Server.

Go to GitHub Sync for a setup guide.

Repository Requirements

Syncing to your GitHub Enterprise Server (GHES) or GitHub Enterprise Cloud requires a new, empty repository. Additionally, each project in a group can only sync to one repository.

ReadMe Permission Requirements

ReadMe uses a GitHub App with repo-level access. ReadMe requests access to:

Metadata - ReadMe requires read-only access to metadata to support core GitHub App functionality.
Content - ReadMe requires read and write access to sync content between ReadMe and GitHub.

Webhooks are used for syncing content, detecting changes, and resolving conflicts.

Access Git Connection Settings

To access GitHub Connection settings in your project or group dashboard go to Settings > Git Connection.

A new Git repository is required and must be completely empty. No commits or files (e.g., README.md) can be present before connecting to ReadMe. You can add or remove files after setup.

Connect GitHub Cloud

From the Git Connection page, under GitHub Connection click Connect. It will start the process to authenticate your GitHub and authorize ReadMe access.

Connect GitHub Enterprise Server (GHES)

To access GitHub Connection settings go to Group dashboard > Group Settings > Git Connection.

A new Git repository is required and must be completely empty. No commits or files (e.g., README.md) can be present before connecting to ReadMe. You can add or remove files after setup.

After selecting authorize on GitHub you are prompted to authenticate on GitHub.

📘
You will be prompted to fork the project to make edits if you are logged into GitHub as a non-repo owner on a public project.

Network Requirements

We recommend your GHES server be accessible from the internet.

If your GHES server is behind a VPN, you must allow traffic from ReadMe’s IP addresses:

100.78.225.12
34.211.200.85
35.160.120.126
44.233.151.27
54.69.248.207
74.220.48.0/24
74.220.56.0/24

Setup Requirements

To setup GHES, a user with permission to create GitHub Apps needs to provide their hostname and organization name. The GitHub App will be installed to their organization.

Once the app is created, you will see your app info and a reset button (if you need to recreate a new one). You will have to grant the app access to your organization and repositories.

Manage and Disconnect GitHub Enterprise Projects

Once a ReadMe project is connected a GitHub repository, you can click on the Connected button to manage the connection or disconnect the connection in the modal.

After setup, you will see all of your projects in the group. You can also filter by name, first sync, last sync, and status. You will need to select which repository should map to your ReadMe project. Additional repos can be added via GitHub.

Once a ReadMe project is connected a GitHub repository, you can click on the Connected button to manage the connection or disconnect the connection.