GitHub Pages for client docs: when it's enough — and where it breaks

"Just put it on GitHub Pages" is the single most common answer to how do we share the docs in our repo? — and about half the time it's the right one. This is a guide to knowing which half you're in before a client bookmarks a URL that turns out to be public to the entire internet.

What GitHub Pages actually is

A free static-file host wired into your repo. Push to a branch, GitHub serves the files at something.github.io (or your custom domain). It doesn't care what generated the files — Jekyll, MkDocs, Docusaurus, plain HTML. As pure publishing plumbing, it's hard to beat: zero cost, zero servers, deploys on push.

The decision, in one list

Use GitHub Pages when all of these are true:

1. Every page can be read by anyone on the internet.
2. Nobody needs to comment — or your readers all have GitHub accounts and giscus is acceptable.
3. All readers may see the same content — no per-client separation.

Miss any one of them, and Pages stops being the tool. Here's why each breaks.

Break #1: private access requires Enterprise Cloud

This is the one that surprises teams. Access-controlled Pages sites exist only on GitHub Enterprise Cloud. On Free, Pro, and Team plans, a Pages site is public — even when the repo behind it is private. There's no password option, no visitor allow-list.

The workarounds people try:

• Client-side "login" gates — a JS prompt in front of content that's still served publicly. Not security; anyone can read the source or fetch the files directly.
• Obscure URLs — a link is a credential that gets forwarded, pasted into chats, and indexed.
• Moving to Netlify/Cloudflare + auth — legitimate, but now you're running an auth stack, and it's still one shared gate rather than per-client roles.

If "the client's docs shouldn't be on the open internet" is a requirement, Pages on a normal plan simply doesn't have the feature — at any price short of Enterprise.

Break #2: every visitor sees everything

Pages serves one site to everyone. "Client A sees project A, client B sees project B" means one repo + one Pages site per client, plus a build matrix that grows with every onboarding — and Break #1 still applies to each of those sites.

Break #3: no feedback channel

There's no commenting. giscus can bolt comments onto the pages, but it authenticates through GitHub — every commenting client needs an account, which is usually the exact thing you were avoiding. Feedback ends up back in email and Slack threads, detached from the doc.

What to do when Pages breaks

Keep the part of the stack that works — markdown in your repo, pushed with git — and swap the serving layer for one that has auth built in. That's what Miradorly is: it connects to the same repo, renders the same markdown, and serves it behind email/Google sign-in with per-project viewer/commenter roles, section comments with statuses, .docignore for internal files, and a role-aware MCP so AI agents query the docs within each user's permissions. Public pages are still possible — per page or per project, when you choose.

Your workflow doesn't change: write in your editor, push, done. The only difference is that the URL you send the client checks who's asking.

Bottom line

Public docs → GitHub Pages, free and correct. Client docs → the moment you need restricted or commentable, Pages needs Enterprise Cloud plus tooling it doesn't have; a portal with its own auth over the same repo gets you there for $29/mo without changing how you write.