CmdocsGitHub Integration
Connect your GitHub repo to cmdocs and ship docs on every push.
GitHub Integration
This is the happy path for shipping docs with cmdocs. Sign in with GitHub, link a repository, and every push to your tracked branch produces a new live deployment — no CI to configure, no servers to manage.
What you'll need
- A GitHub account
- A repository containing a
docs.jsonand at least one.mdxpage - 2 minutes
Don't have a docs repo yet? Run npx @cmdoss/cmdocs init my-docs locally, push it to a fresh GitHub repo, and come back here.
How it works at a glance
The cmdocs GitHub App registers a webhook on each connected repo. Every push triggers a build; the build worker clones the repo, runs the cmdocs pipeline, and publishes the static output to your environment's subdomain.
Walkthrough
Sign in to the dashboard
Open cmdocs.sh and click Continue with GitHub. The first time you sign in, GitHub will ask you to authorize cmdocs.
Install the cmdocs GitHub App
cmdocs uses a GitHub App (not a personal access token) so it can register webhooks securely on a per-repo basis. Pick the repos you want cmdocs to access — you can change this later.
You can grant access to all repos or only select repos. The latter is recommended for organizations.
Create a project
Back in the dashboard, click New Project. Give it a name — this becomes the slug for your default subdomain (<slug>.cmdocs.app).
Pick a repository
Choose the repo containing your docs from the list of repos cmdocs has access to.
If your docs.json is in a subdirectory (e.g. a monorepo at apps/docs), set the Docs path field to that folder.
First build runs automatically
As soon as the project is created, cmdocs registers a webhook on the repo and queues the first build. Watch the live build log on the deployment page.
A typical build looks like this:
[build] Cloning repository…
[build] Reading docs.json
[build] Transforming MDX (12 pages)
[build] Generating navigation
[build] Building static site (next build)
[build] Uploading artifacts
[build] ✓ Live at my-docs.cmdocs.shVisit your live site
When the deployment turns green, click the subdomain link at the top of the project page.
Push to deploy
From now on, every push to your tracked branch creates a new deployment. Open the Deployments tab to see history.
Branches and environments
By default, your project's production environment tracks main. You can add more environments — each with its own branch and subdomain — from Project → Environments → New.
| Environment | Branch | Subdomain | Use case |
|---|---|---|---|
production | main | <slug>.cmdocs.app | Public docs |
staging | develop | <slug>-staging.cmdocs.app | Internal review |
next | next | <slug>-next.cmdocs.app | Long-running feature branch |
You can override the auto-generated subdomain on the environment settings page.
Webhook security
cmdocs verifies every incoming webhook with HMAC-SHA256 using a per-installation secret. Webhooks that fail signature verification are rejected and never enqueue a build.
Prop
Type
Troubleshooting
What's next
How is this guide?