How to publish private documentation from a GitHub repo
Turn the markdown in a private GitHub repository into a docs site only the right people can read, without a second permission list to maintain.
By Gusenga Thierry ·
The short answer
Point a documentation host at the repository's docs folder and let it check each reader before serving a page. GitHub Pages can only do this on GitHub Enterprise Cloud. DocuGate does it on any plan with private repositories: it reads the markdown on each push and lets GitHub decide who may read, or uses an allowlist of logins and emails.
What are the options?
Your documentation is already in the repository, next to the code it describes. You want it rendered as a site, and you want only some people to read it. There are three common approaches.
Read it on GitHub. GitHub renders markdown in the repository view. Anyone with repository access can read it, nobody else can, and there is nothing to set up. It is also a code browser, not a documentation site: no sidebar, no search across pages, and every reader needs repository access, which usually also means seeing the code.
GitHub Pages with private visibility. As of October 2026, GitHub's own documentation says: "To publish a GitHub Pages site privately, your organization must use GitHub Enterprise Cloud" (GitHub Docs). If you are already on Enterprise Cloud, this works. If you are not, it is a large upgrade for one feature. The GitHub Pages alternative page goes into this.
A docs host that reads the repository. A separate service reads the markdown, renders it, and checks each reader. This is what DocuGate does.
How does DocuGate read a private repository?
You install DocuGate's GitHub App on the account or organisation that owns the repository and grant it the repositories you want to publish. A space then reads one folder, on one branch:
| Field | Example |
|---|---|
| Repository | acme/platform |
| Branch | main |
| Docs folder | docs |
| URL slug | handbook |
The rules for turning files into pages are short:
- Only
.mdfiles become pages. - A folder becomes a sidebar group, nested folders nest.
- A file's title is its first
#heading. index.mdis the landing page; without one,README.mdstands in.
There is no sidebar config to write. If you want a fixed order, an optional
docugate.json at the repository root takes a sidebar list. See
connecting a repository.
Content is cached per commit. Push to the branch and the next reader gets the new version.
Who can read it?
Each space has one of three access modes, changeable at any time:
| Mode | Who can read | Good for |
|---|---|---|
| Public | Anyone with the link | Open-source docs |
| Repo access | Anyone GitHub lets open the repository | Internal runbooks |
| Allowlist | Named GitHub logins or email addresses | Clients, partners, a subset of a team |
Repo access is the one most teams want for internal docs. The server fetches each page using the reader's own GitHub token, so GitHub answers the question. There is no second permission list to keep in step with your organisation: when GitHub stops letting someone open the repository, DocuGate stops serving them its docs. GitHub returns a 404 for a private repository you cannot see, and DocuGate shows a locked screen with a button to ask the owner for access. The reasoning is in access control.
Allowlist is for readers who should see the docs but not the code. The list lives in the space's settings in DocuGate, not in the repository, and only you can see it. Someone on it by email address can sign in with Google and never needs a GitHub account.
What if the docs are spread across several repos?
A product split across a frontend, a backend and a mobile app has one set of docs to tell. On Pro, one space can read several repositories and merge their pages, each with its own branch and folder. Every page records which repository it came from. See merging repositories.
One thing to know before you mix visibility: if the main repository is public and you add a private one, everyone who can read the space can read the private repository's pages. The dialog says so before you confirm.
Can people fix a page without cloning?
Anyone who can push to the repository sees Edit on the pages they can push to. The change commits to the branch as them, so history and blame stay accurate. Someone on an allowlist who cannot push reads but does not edit.
Steps
- Sign up with GitHub and install the DocuGate app on the owner of the repository.
- Open Dashboard → New space and pick the repository.
- Set the branch and docs folder.
- Choose Repo access or Allowlist.
- Open the space at
/{your-handle}/{slug}and send the link.
Private repositories need Pro: $5 a month, $50 a year or $2 a week, with unlimited spaces. See pricing.
Try it
Connect a repository and publish its docs folder with Repo
access.
Questions people also ask
Do readers need a GitHub account?
For a Repo access space, yes, because GitHub is what vouches for them. For an Allowlist space, no: someone allowlisted by email can sign in with Google.
Does DocuGate copy my repository?
No. Content is cached per commit and re-read after a push to the configured branch. Nothing is stored permanently, so if you delete the repository the space empties.
Can different people see different parts of the same repo?
Yes. Create one space per folder, for example docs/developers as Public and docs/partners as Allowlist. Each space has its own access setting.
Which plan do I need for a private repository?
Pro, at $5 a month, $50 a year or $2 a week. The free Starter plan publishes public repositories.
Read next
- A GitHub Pages alternative for private sites: GitHub Pages only publishes privately on GitHub Enterprise Cloud. The alternatives for private docs, and what each asks of you.
- How do I share docs from a private repo without giving repo access?: Ways to let clients, partners or staff read the documentation in a private GitHub repository without adding them to the repository.
- Can someone read docs from a GitHub repo without a GitHub account?: Who can read documentation kept in a GitHub repository without a GitHub account, and how to give a non-developer access to private docs.
- Why the access check lives on the server, and GitHub is the gate: How DocuGate decides who may read a docs space, why that decision never runs in the browser, and why GitHub answers it for repository access.
Get started with DocuGate, free.