GitHub Sync
Two-way sync between Theneo and GitHub, via a native GitHub App, push docs out to your repo, pull edits back automatically.
Before you start
Editor access in Theneo
Only editors on the project can connect or change a sync.
GitHub repo admin
Installing a GitHub App needs permission to grant repo access, or an org owner's help.
A repo & branch
Where your docs should live. The folder doesn't have to exist yet, sync will create it.
Set up the sync
1
Connect your GitHub account
Open the project you want to sync, go to its GitHub Sync settings, and click Connect GitHub. A GitHub window opens authorize the Theneo GitHub App. The popup closes itself once you're connected (if it doesn't, close it manually and return to Theneo).
2
Install the app on your repositories
Click Install / Configure repositories. On GitHub's install screen, choose All repositories or Only select repositories (and pick the repos you want), then confirm. You'll be returned to Theneo.
Grant access only to the repos you actually plan to sync. You can change this anytime from your GitHub org's Installed GitHub Apps settings.
3
Choose what to sync
In Theneo's GitHub Sync settings, pick your target and click Save:
- Repository - choose from the repos you granted access to.
- Branch - the branch docs live on. Defaults to
main. - Folder path - where docs live inside the repo. Defaults to
theneo_docs.
A project links to one repo, branch, and folder. If the repo or project is already linked elsewhere, Theneo warns you instead of creating a conflicting link.
Sync your docs — both directions
Use this to publish your Theneo docs into the repo. In GitHub Sync settings, click Sync to GitHub. Theneo writes your published documentation into the chosen folder as a single commit:
docs: Sync documentation from Theneo
What happens to your files:
- New and changed docs are written into the folder.
- Deleted docs (removed in Theneo) are removed from the folder, so it mirrors your project - it never just accumulates stale files.
- Everything outside your chosen folder is left untouched.
This happens automatically — there's nothing to click. Just push to the branch as usual.
- Someone pushes a change to the synced branch (directly or via a merged PR).
- If the change touches your docs folder, Theneo imports the updated files and re-publishes the project.
- Changes that don't touch the folder are ignored — normal code commits won't trigger a doc update.
How edits flow
You edit in Theneo
Click Sync to GitHub, and the repo folder is overwritten to match Theneo.
You edit in GitHub
Push to the synced branch/folder, and the Theneo project is overwritten to match the repo and re-published.
Because each direction overwrites the other, decide where a given edit originates and let sync carry it across — rather than editing both sides at once between syncs.
FAQ
Can I sync more than one branch or folder?
Can I sync more than one branch or folder?
Not per project - each project links to a single repo/branch/folder. Use separate projects for separate targets.
Which version of my docs gets pushed out?
Which version of my docs gets pushed out?
The published version of the project.
Will syncing touch other files in my repo?
Will syncing touch other files in my repo?
No. Only the configured folder is read or written.
What if I edit in both places before syncing?
What if I edit in both places before syncing?
Whichever direction runs next wins for that content - inbound overwrites the project; outbound overwrites the folder. Avoid parallel edits on the same content between syncs.
Who can set up or change the sync?
Who can set up or change the sync?
Anyone with editor access to the Theneo project. Access is re-checked when you connect.
How do I disconnect?
How do I disconnect?
Remove the Theneo GitHub App from the repository in your GitHub org's Installed GitHub Apps settings, and/or clear the sync configuration in the project.
Troubleshooting
"No access to project"
"No access to project"
You don't have editor rights on the project. Ask a project admin to grant them.
Repo not showing in the list
Repo not showing in the list
The GitHub App wasn't granted access to it. Re-run Install / Configure repositories and add it.
Pushed to GitHub but nothing imported
Pushed to GitHub but nothing imported
Confirm the change was on the synced branch and inside the configured folder, changes elsewhere are intentionally ignored.
Sync to GitHub fails
Sync to GitHub fails
Re-check that the project is still connected (the GitHub connection may need re-authorizing) and that the branch still exists.
On this page
- GitHub Sync