Bi-Directional Sync

Bi-directional sync creates a two-way connection between your ReadMe project a Git repository. This optional workflow keeps content consistent across both platforms without manually updating your docs. Some benefits of bi-directional sync:

• Write Where You Want: Write in your preferred environment whether that’s ReadMe or your local development setup
• Collaboration: Developers, engineers, and technical writers can collaborate using tools they’re familiar with
• Automated Syncing: Changes sync automatically between ReadMe and Git creating a single source of truth and limiting manual changes

💁‍♂️

Note: GitHub Enterprise Server is available on Enterprise plans. Contact your Customer Success Manager if you’d like to enable it to your Group Project.

Prerequisites

To enable bi-directional sync, you’ll need the following:

• Your project is on the new editing experience, ReadMe Refactored
• You have a GitHub account and can create an empty, private repository

Enabling Bi-Directional Sync

💁‍♂️

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

If you have both prerequisites, you can enable by:

1. Navigate to Settings > Git Connection page.
2. Once there, you can Create a new repository in GitHub that is completely empty.
3. Sync with Github, select your empty repository, and authenticate.
4. Your repository should show up in ReadMe. Choose your repository to start syncing.

Once you select your repository, you’re all set to start writing your docs from ReadMe or a Git workflow!

Changing Repositories

If you need to connect your ReadMe project to a different GitHub repository, you must disconnect the original repository from GitHub's account settings.

1. Navigate to Applications > Installed GitHub Apps.
2. Find ReadMe Sync and click Configure
3. Under Repository access, select Only select repositories and uncheck the repository you’d like to disconnect.
4. Connect to a new repository by following the steps in Enabling Bi-Directional Sync.

Enabling 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. Note: Your GHES server must be accessible from the internet—syncing won't work if it's behind a VPN.

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

Editing Your Docs

Once your Git Connection is set up, all changes made in the ReadMe editor will automatically sync to your Git repository, and vice versa. When editing documentation in Git, you can use your preferred code editor or Git tools.

To ensure successful syncing from Git to ReadMe, follow these structure guidelines:

Markdown Files:

• Files must include required frontmatter: title and summary
• Content should be written in standard Markdown format
• File names must match the intended URL slug for proper routing

Navigation:

• Page order is defined using _order.yaml files
• Each category folder can have its’ own order.yaml
• Navigation structure in Git, mirrors your ReadMe project hierarchy

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
		

Handling Conflicts

When a conflict is detected while saving in ReadMe, the system will immediately prompt you to Overwrite Git changes or Cancel the save and continue editing. Changes saved in ReadMe, will always match what goes live.

When merging from GitHub, the user can resolve conflicts via the GitHub editor or the merge tool of their choice locally before pushing.

Working with 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