Skip to main content

Syncing documents with GitHub

Connect a GitHub repository to a workspace or board and Cardscape mirrors its Markdown and MDX files as documents — two-way. Edit in either place and the changes flow to the other.

Connecting a repository​

Connecting a repository is admin only:

  1. Install the Cardscape GitHub App on the repository you want to sync (a GitHub popup walks you through granting access).
  2. Back in Cardscape, pick the installation and the repository.
  3. Choose the branch and, optionally, a root folder to limit which files sync.
  4. Choose the scope — the whole workspace, or a specific board.

The initial import brings the repository's Markdown and MDX files in as documents right away.

Editing and pushing​

A repo-backed document shows its file path and its push state in the editor:

  • Saving commits your change back to GitHub — the save action reads Save & push.
  • Not pushed yet means a local edit hasn't reached the repository yet.

Resolving conflicts​

If the file changed on GitHub while you were editing, you'll see a banner offering:

  • Load theirs — take the version from GitHub.
  • Overwrite repo — replace the file on GitHub with your version.

Other actions​

  • Add a local document to the repo — start a document in Cardscape, then add it to the connected repository so it becomes a real file.
  • Re-create a deleted file — if a file was deleted on GitHub, saving the document re-creates it.
  • Disconnect — detach the repository. Your documents are kept; they're just no longer linked to GitHub.
note

Syncing also happens on its own — whenever changes are pushed to GitHub, and on a regular schedule — so documents stay current without a manual sync.

  • Documents — how documents work once they're in Cardscape.