Skip to content

Sync with GitHub

Sync your documentation with a GitHub repository. Push published content as Markdown files, pull changes made in GitHub back into Topicary, and optionally enable auto-sync to keep both sides in sync continuously.

Before you begin

This feature requires the Enterprise capability tier (the Business ). During the beta, every project is on the free Solo tier, so this feature is locked by default: go to Settings ▸ Billing and request Enterprise access to unlock it.

  • You need a GitHub repository where the documentation will be synced.

  • You need a GitHub personal access token with repo scope (or a fine-grained token scoped to the target repository).

  • You need at least one publication target configured in your map.

Configure GitHub sync

  1. Go to Settings in the sidebar.

  2. Open the Connections tab and find the Docs sync section.

  3. Enter the repository in owner/repo format: for example, acme/docs.

  4. Enter the branch name: for example, main or docs.

  5. Enter a path prefix: for example, docs/ to place files in a subdirectory.

  6. Add a GitHub personal access token with repo scope.

  7. Select the publication target whose content should be synced.

Store your GitHub personal access token securely. Use a fine-grained personal access token scoped to only the target repository when possible. The token is encrypted at rest using AES-256-GCM.

Test the connection

Click Test Connection to verify that Topicary can access the repository with the provided token.

Push to GitHub

  1. Open the Sync panel in the right sidebar of the topic editor, or go to Settings > Connections > Docs sync.

  2. Click Push.

  3. Topicary resolves the content through the publishing pipeline, converts topics to Markdown, and commits them to the repository.

The last sync status shows the timestamp, commit SHA, and number of files written.

What gets pushed

  • One Markdown file for each topic in the map

  • Files placed under the configured path prefix

  • Folder hierarchy matching the map structure

  • Content resolved through the full publishing pipeline (components expanded, conditions filtered, variables substituted)

Pull from GitHub

Pull changes made directly in the GitHub repository back into Topicary:

  1. Open the Sync panel or go to Settings > Connections > Docs sync.

  2. Click Pull.

  3. Topicary fetches the remote tree, compares content hashes, and imports changes.

New files become new topics (matched by title). Modified files update the corresponding topic's content. Deleted files are flagged but not automatically removed from Topicary.

Pull converts Markdown back to TipTap JSON for the editor. Complex Markdown features that do not have a TipTap equivalent may be simplified during conversion.

Auto-sync

Enable auto-sync to keep your repository and Topicary in sync automatically:

  1. Open the Sync panel.

  2. Toggle Auto-sync on.

When auto-sync is enabled:

  • Pushes happen automatically after each publish.

  • Pulls happen when GitHub sends a webhook notification (see below).

GitHub webhook for auto-pull

To receive automatic pull notifications, configure a GitHub webhook:

  1. In your GitHub repository, go to Settings > Webhooks.

  2. Add a webhook with the payload URL: https://topicary.com/api/v1/webhooks/github

  3. Set the content type to application/json.

  4. Add a secret (the same value configured in your Topicary Docs sync settings).

  5. Select the push event.

Topicary verifies the webhook signature using HMAC-SHA256 (timing-safe comparison) and triggers a pull when changes are detected on the configured branch.

The webhook handler includes sync loop prevention: pushes originating from Topicary do not trigger a pull, avoiding infinite loops.

Conflict resolution

If the same topic was modified in both Topicary and GitHub since the last sync, a pull triggers the conflict resolution dialog:

Option

Behavior

Keep yours

Discards the GitHub version and keeps the Topicary content

Use remote

Overwrites the Topicary content with the GitHub version

Auto-merge

Attempts a three-way merge of both versions

The dialog shows a side-by-side diff with color-coded changes (local versus remote) so you can compare before choosing.

Merging uses a three-way comparison (base, source, target) to combine changes. If both branches modify the same block, you will need to resolve the conflict manually using the side-by-side conflict resolution view. Always review the merge preview before confirming.

Sync history

The Sync panel shows a log of recent sync events:

  • Direction: push or pull

  • Timestamp: when the sync occurred

  • Files changed: number of files added, modified, or removed

  • Status: success or error (with details)

See also

Was this page helpful?