Bi-Directional Sync

Connect your project to a GitHub, GitLab, or Bitbucket repository so content stays in step whether you edit in ReadMe or in your repo.

Bi-directional sync creates a two-way connection between your ReadMe project and a GitHub, GitLab, or Bitbucket repository. This optional workflow keeps content consistent across both platforms:

Write in your preferred environment whether that’s ReadMe or your local development setup.
Developers, engineers, and technical writers can collaborate using tools they prefer.
Changes sync automatically between ReadMe and Git creating a single source of truth.
All content types sync, including guides, API reference pages, custom pages, recipes, and changelogs.

Starter	Pro	Enterprise

Setting Up Bi-Directional Sync

ReadMe supports bi-directional sync with GitHub, GitLab, and Bitbucket.

For syncing with GitHub, you can connect to GitHub Cloud. If you are on the Enterprise plan, ReadMe supports bi-directional sync to GitHub Enterprise Server.

⚠️
The repository you’re syncing to must be empty—no commits or files (e.g., README.md)—before connecting to ReadMe. You can add or remove files after setup.

📘
Connecting to a repository owned by an organization (e.g., a GitHub organization or GitLab group) may require organization-level permissions such as the ability to install or configure third-party apps. If you encounter a permissions error during setup, coordinate with an organization owner or admin on your Git provider. See the provider-specific setup pages linked above for details.

Documentation Versioning

If your ReadMe project uses multiple Versions, only the Main Version is initially synced when you first enable Bi-Directional Sync. After successfully enabling Bi-Directional Sync, any changes to the other versions will sync to your Git repository.

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.

Unsynced

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

Synced

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.

Troubleshooting

Push rejected: the target branch is protected

If a synced branch has branch protection rules or rulesets, your Git provider can reject the commits ReadMe pushes to it. When that happens, Settings > Git Connection shows an error naming the affected branch:

What you'll notice

Changes saved in ReadMe don't appear in your repository.
Changes merged in Git can also stop appearing in ReadMe. This is most visible with API definitions: syncing an API definition requires ReadMe to write generated reference files back to the branch, so when that push is rejected the definition isn't updated, even though Markdown guides in the same commit may sync fine.
The Git Connection still shows as Connected. The error is on the branch, not the connection.

Why it happens

ReadMe Sync pushes commits directly to your synced branches, and it doesn't automatically bypass the rules you've set on the repository. Any rule that blocks direct pushes will reject them: requiring a pull request, requiring reviews or status checks, requiring signed commits or linear history, or restricting who can push.

How to fix it

Allow the ReadMe integration to push to every synced branch. For GitHub, add the ReadMe Sync app to the bypass list by following GitHub Branch Protection. Rulesets and legacy branch protection are configured in different places, so check which one your repository uses. For GitLab or Bitbucket, allow the account used by the ReadMe integration to push to the protected branch.
Check for rules defined at the organization level. Organization rulesets apply on top of repository rules and need their own bypass entry.
If your repository settings are managed by an automated tool (a repo-settings config, a policy bot, or infrastructure-as-code), make the change there. Otherwise the next run of that tool will revert it.
Trigger a sync by saving a small change to the affected branch in ReadMe, or by pushing a new commit to it. Commits ReadMe couldn't push are sent on the next successful sync.
Confirm the error has cleared on Settings > Git Connection. If a change merged in Git still isn't showing, re-save the affected page or API definition in ReadMe once the push succeeds.

FAQ

How does ReadMe integrate with GitHub and what permissions are required?

ReadMe uses a GitHub App with repo-level access: read-only for metadata(required) and read/write for syncing content. Webhooks handle syncs, change detection, and conflict resolution.

Why aren't my branches showing up in GitHub or GitLab?

New branches you create after enabling bi-directional sync automatically create a corresponding branch on Git tools, but existing branches will not create a corresponding branch on Git tools until you save a change to that branch in ReadMe.

What permissions are required when syncing with GitLab?

ReadMe requests access to:

read_api for listing projects
read_user and read_profile to display user information
read_repository to sync content in GitLab to ReadMe
write_repository to sync content in ReadMe to GitLab

Sync says a push was rejected because the branch is protected.

Your branch protection rules are blocking ReadMe's pushes. Add the ReadMe integration to the bypass list for that branch and trigger a new sync. See Troubleshooting above for the full steps.