How to set Repo Docs up, how to connect a private repository, and what every message it gives you means.
Setting it up · Private repositories · How your files become pages · What it will not do · Limits · Messages and what they mean
After the app is installed, open Apps in the Confluence sidebar and choose Repo Docs. Everything is on that one page.
| Field | What to put in it |
|---|---|
| GitHub owner | The user or organisation the repository belongs to. In github.com/acme/handbook the owner is acme. |
| Repository | The repository name. In the example above, handbook. |
| Branch | Usually main. Older repositories often use master. |
| Folder | The folder holding your markdown, for example docs. Leave it empty to sync the whole repository. |
| Confluence space key | The space the pages go into. You can see it in the address bar when you open a space: in /wiki/spaces/ENG/ the key is ENG. |
Tick Sync automatically every hour if you want the pages to follow the repository on their own, then press Sync now. The first run tells you how many pages it created.
Keep the page open while it runs. A large repository is synced in batches, and the page asks for the next batch each time one finishes. Closing the tab stops it. Nothing is damaged if you do, and the next run picks up from where it stopped.
If a run is interrupted that way, the page will still say it is syncing the next time you open it. Press Clear it under that message to reset, then sync again.
A public repository needs nothing. A private one needs a GitHub token so the app can read it.
The token is checked against GitHub before it is stored, so a wrong or expired one is refused straight away rather than failing later. Once saved it is held in Forge secret storage: the app can use it, and the page can ask whether one exists, but it can never be read back out. Press Remove it to delete it.
Give the token the least it needs. One repository, Contents read-only, and an expiry date. The app never writes to your repository, so write access would serve no purpose.
The title comes from the first of these that exists:
title: line in the file's front matter, the settings block fenced by --- at the top of the file.# heading in the file.Front matter is not printed on the page. It is settings, so it is removed the same way your site generator removes it.
Confluence titles have to be unique inside a space. If two files ask for the same title, the first one
keeps it and the others are given the name of their folder as well, for example
Overview (api). The same file always gets the same title, so a second sync does not
rename anything.
Each folder becomes a page, and the files inside it become its children, so the shape of the repository survives. Folders nested several levels deep are handled.
An image referenced with a relative path, such as , is pointed at the
same file in your repository so it renders in Confluence. Images already using a full web address are
left alone.
A second run updates the same pages. It does not make duplicates. The app remembers which page belongs to which file, and every page it writes carries a short line at the bottom saying it was synced by Repo Docs.
The app holds no permission to delete anything, by design. You can see this for yourself on the installation screen: it asks to read spaces and pages, to write pages, and to use its own storage. There is no delete permission in the list, so it could not remove a page even if it tried.
The page stays. At the end of a sync the app lists any page whose file is no longer in the repository, so you can decide what to do with it. It never removes them itself.
If the space already holds a page with the same title, the app checks whether it wrote that page itself, by looking for its own line at the bottom. If the line is not there, the page belongs to someone else and it is left completely untouched. The file is reported as a conflict instead, and you can either rename that page or change the first heading in the file.
This is why a reinstall does not create duplicates: the app recognises its own pages and picks them back up.
| Limit | Detail |
|---|---|
| 800 files | One sync carries up to 800 markdown files. If your repository has more, put a folder in the Folder field and sync a part at a time. |
| One repository | Each Confluence site syncs one repository and folder at a time. Change the fields and sync again to move to another. |
| Hourly | The automatic sync runs once an hour. You can always press Sync now. |
| GitHub only | GitHub repositories today. GitLab and Bitbucket are not supported. |
| Message | What to do |
|---|---|
| Repository not found, or it is private | Check the owner, name and branch. If the repository is private, add a GitHub token. |
| Repository not found (with a token saved) | The token is valid but cannot see that repository. Check the owner, name and branch, and that the token lists this repository under its repository access. |
| GitHub refused the token | The token has expired or been revoked. Make a new one and save it again. |
| No .md files found | The folder or branch is wrong, or that folder holds no markdown. The message names both so you can see which one to correct. |
| No space with that key | Check the space key in the address bar of the space you want. It is the part after /spaces/. |
| This repository has too many files | More than 800 markdown files. Narrow it with the Folder field. |
| A page already exists and was not created by this app | Rename that page in Confluence, or change the first heading in the file. The existing page has not been touched. |
| A sync is already running | Another sync is in progress, most likely the hourly one. Wait for it to finish. If it never does, reload the page: the progress message comes back with a Clear it link under it. |
Write to support@maioapps.com. Telling us the exact message you saw, and the owner, repository, branch and folder you used, is usually enough to answer on the first reply.