Skip to main content

Connect a repo

About three minutes from start to first sync. You'll need a GitHub account that owns the repo (or has admin access).

1. Open the GitHub tab

Project settings → GitHub. If this is the first time, you'll see a single Connect GitHub button.

2. Install the Docsio app

Click Connect GitHub. You're sent to GitHub to install the Docsio Docs Sync app.

You can grant access to:

  • All repositories in your account or org. Easiest, lets you switch repos later without re-installing.
  • Selected repositories. Pick one or a few. More restrictive — recommended if your account has many repos and you want to limit Docsio's access.

Confirm the install. GitHub redirects you back to Docsio.

3. Pick org, repo, branch

The configuration form appears with three dropdowns:

  • GitHub organization — your personal account or any org the app was installed on.
  • Repository — repos the app has access to inside the selected org.
  • Branch — usually main or master.

If you want to use a subdirectory inside the repo (e.g. your docs live under docs/ while the rest is application code), enable "Docs are in a subdirectory" and specify the path.

4. Pick the first-sync direction

This is the most important choice. Two options:

GitHub → Docsio. Use this when the repo already has markdown docs you want Docsio to render. Docsio reads the existing content and replaces the current state of your Docsio site with it.

Docsio → GitHub. Use this when the repo is empty (or you want to overwrite it). Docsio commits the current state of your Docsio site to the repo as a clean initial commit.

If your repo is brand new and empty, Docsio detects this and locks the picker to "Docsio → GitHub" — there's nothing to pull.

5. Save changes

Click Save changes. Initial sync runs:

  • GitHub → Docsio direction: pulls every allowlisted file from the repo into your Docsio project_files. Then triggers a build of your docs site against the new content.
  • Docsio → GitHub direction: commits your current docs to the configured branch as [docsio] initial sync from Docsio. Then triggers a build.

Either way, you'll see a status indicator and within ~30-60 seconds, the connection becomes Active.

6. Verify the sync

The settings page now shows:

  • Active green dot
  • The repo and branch you connected
  • Last commit author and message
  • "Force re-sync" and "Disconnect" buttons

Visit your repo on github.com — you should see either the seed commit (if Docsio → GitHub) or your existing files have been read in (if GitHub → Docsio).

Common gotchas

  • App not appearing in dropdown. If you installed the app on a different account than the one you're signed into Docsio with, switch accounts on github.com and re-install.
  • No repos showing in dropdown. The app was installed but didn't grant access to any repos. Re-install via Manage GitHub access link in the form.
  • Branch dropdown is empty. The repo is brand new with no commits yet. Pick "Docsio → GitHub" direction; we'll create the first commit and the branch for you.
  • Sync error: "Branch protection rules." Your branch has rules requiring PR reviews or specific status checks. Either grant the Docsio app permission to bypass rules, or change the rules so direct commits to the branch are allowed.

Next