Skip to content

Sync with GitHub

Docs sync keeps a publication target and a GitHub repository in step: push your topics to the repo as Markdown, and pull edits made in GitHub back into Topicary. Both directions are actions you run; nothing syncs on a schedule.

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 to sync with.

  • You need a GitHub personal access token with repo scope, or a fine-grained token scoped to that repository.

  • You need at least one publication target. The Docs sync card is hidden until the project has one, because the sync always runs against a target's content.

Configure Docs sync

  1. Go to Settings in the sidebar.

  2. Open the Connections category and find the Docs sync card.

  3. Fill in the five fields:

Field

What to enter

Repository

The repository in owner/repo format, for example acme/docs

Branch

The branch to sync with, for example main

Path prefix

The directory inside the repo that holds the content files, for example docs/

Personal access token

A GitHub PAT with repo write access. Encrypted at rest

Publication target

Which published site's content to sync

  1. Click Save configuration.

  2. Click Test connection. Success reads Connected to <repo>; anything else shows the error GitHub returned.

Scope the token as tightly as you can: a fine-grained token limited to the one repository is enough. Topicary encrypts the token at rest with AES-256-GCM and never shows it again. To replace it, type a new one; leave the field blank to keep the current one.

Push to GitHub

Push writes every topic in the publication target to the repository as Markdown, in one commit.

  1. Open the topic editor's Sync panel and click Push all to GitHub, or go to Settings > Connections > Docs sync and click Sync now.

  2. Topicary resolves the content through the publishing pipeline, converts each topic to Markdown, and commits the files.

All files land in a single commit on the configured branch, with the message docs: sync from Topicary (<timestamp>). After a push, the settings card shows Last synced: with the time, the number of files written, and the short commit SHA linked to GitHub.

What gets pushed

  • One Markdown file for each topic in the publication target, whatever its status. Drafts are pushed too, with their status recorded in the file's YAML frontmatter

  • Files placed under the configured path prefix, in a folder hierarchy matching the map structure

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

Publishing a site does not push to GitHub. Push is always something you click, in the Sync panel or in the settings card.

A push also records what it wrote, so the next pull only has to look at files that changed in GitHub afterwards. That is why a pull immediately after a push usually reports nothing to do.

Pull from GitHub

  1. Open the topic editor's Sync panel.

  2. Click Pull from GitHub.

The settings card has no pull button: pull runs from the editor's Sync panel.

Topicary fetches the files under the path prefix on the configured branch and decides file by file what to do:

Situation

What happens

The file is unchanged since the last sync

Skipped

The file changed but matches the topic already

Nothing is written; both sides are marked as in step

The topic is locked by a read-only workflow stage

Skipped and reported, never overwritten

Both the file and the topic changed since the last sync

Raised as a conflict for you to resolve

The file changed and the topic did not

The remote version wins, silently

No topic matches the file title

A new topic is created, subject to your plan's topic limit

Remote changes overwrite local topics without asking

When a file changed in GitHub and the matching topic did not change in Topicary, the pull writes the GitHub version straight into the topic. There is no dialog and no warning: this is the normal fast-forward case, and it is what keeps repository edits from piling up as conflicts.

Every overwrite of this kind snapshots the previous content to the topic's version history first, so a surprise overwrite is recoverable. Version history is a Team-tier capability in the editor; if your plan does not include it, treat a pull as final.

Locked topics are skipped, not overwritten

A topic sitting in a read-only workflow stage is never written by a pull, and it is never offered in the conflict dialog either. The Sync panel lists them under Not pulled into locked topics with the reason for each, and the settings card reports the same thing as N topics were not updated (read-only workflow stage). Move the topic out of the read-only stage and pull again: the next pull offers the same files.

Deleted files

A pull only looks at files that exist in the repository. Deleting a file in GitHub does not delete, archive, or flag the matching topic in Topicary. Delete the topic yourself if you want the deletion to carry across.

Pull converts Markdown back to the editor's format. Markdown features that have no editor equivalent may be simplified during conversion.

Resolve conflicts

When both the topic and the file changed since the last sync, the pull opens the Sync conflicts dialog instead of writing anything. Each conflict shows a side-by-side diff, Your changes against Remote changes, and three resolutions:

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

Resolving a conflict settles it. Topicary records both sides as in step, so the same conflict does not come back on every later pull, and the resolved content is handed straight to the open editor rather than being overwritten by whatever was on screen.

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.

Automatic pulls from a webhook

Topicary has a webhook endpoint that pulls when GitHub reports a push on the configured branch, and it ignores pushes that came from Topicary itself so the two sides cannot loop. The endpoint requires a shared secret that cannot be set anywhere in the app today, so automatic pulls are not something you can turn on yourself. Contact support if you need them.

Sync history

The Sync panel's Recent activity section lists the last 10 sync events:

  • Pushed (N files) or Pulled (N files)

  • Conflicts detected, and Resolved (mine), Resolved (theirs), or Resolved (merge)

  • The time each event happened

The panel's Status section shows the current connection and the last sync time, moving through Ready, Pushing..., Pulling..., Synced, and Error.

See also

See also

Was this page helpful?