Connect GitHub

Jamdesk deploys your documentation automatically when you push to GitHub.

For background on how the GitHub App and personal account linking work together, see Understanding GitHub Integration.

Docs in Bitbucket Cloud instead? See Connect Bitbucket. Each project connects to one provider. No GitHub account? See Docs Without GitHub.

GitHub App Installation

Jamdesk prompts you to install the Jamdesk GitHub App the first time you sign in. The app grants:

Repository access: read your docs content
Webhooks: trigger builds on push
Commit status: show build status on commits

Permissions

The Jamdesk GitHub App requests these permissions:

Permission	Purpose
Repository contents (read and write)	Clone and read your documentation files. Writes happen only when you save in the dashboard editor, accept Fix with AI suggestions, or turn on translation
Metadata (read)	List repositories and branches
Webhooks	Receive push notifications

Jamdesk only accesses repositories you explicitly grant access to. Change access anytime in your GitHub settings.

Connect a Repository

Select repository

Click Connect Repository while creating or editing a project.

Choose from repositories where the GitHub App is installed.

Choose branch

Select the branch to deploy:

main or master: most common for production docs
docs: if you keep docs in a separate branch
Any branch: for preview deployments

Specify docs path

If your docs.json isn't in the repository root, specify the path:

docs/           # Docs in a subdirectory
packages/docs/  # Monorepo with docs package

Leave blank if docs.json is in the root.

The project dashboard then shows the linked repository and branch:

Dashboard showing GitHub repository connected with Linked status badge, repository name, and branch

Automatic Deployments

Every push to your configured branch triggers a build:

git add .
git commit -m "Update API documentation"
git push origin main

Builds typically complete in 30-90 seconds. View status in the dashboard or on the GitHub commit.

Changing Repositories

To connect a different repository:

Go to Settings → Repository
Click Change Repository
Select the new repository and branch

Changing repositories may affect your live documentation. The new repository must contain valid Jamdesk configuration.

Managing GitHub App Access

Control which repositories Jamdesk can access:

Go to github.com/settings/installations
Find Jamdesk in the list
Click Configure
Under "Repository access", select specific repositories or all

Organization Repositories

An organization admin must approve the GitHub App installation for organization repositories:

Request installation from your Jamdesk dashboard
An admin receives a notification in GitHub
Organization repos appear in the repository selector after approval

Linking Your Personal Account

Link your personal GitHub account in User Settings for reliable build attribution:

Click your avatar → User Settings
Find the GitHub Account section
Click Link GitHub Account

This link is separate from the GitHub App. It attributes your commits to you. Learn more.

Troubleshooting

Repository not showing up

Verify the GitHub App is installed on the repository
For organization repos, confirm an admin has approved access
Refresh the repository list in the dashboard

GitHub keeps sending you back to the Jamdesk app page

Your company probably manages your GitHub account. GitHub doesn't let these accounts install apps on their own account. See company-managed GitHub accounts to fix it.

Use a GitHub account another Jamdesk account uses

The repository list shows a message that starts with:

Another Jamdesk account already uses this GitHub account.

It means another Jamdesk account's project already uses the Jamdesk GitHub App on that GitHub account. Usually a teammate set up Jamdesk first, or you're signed in to a second Jamdesk account.

To use the account's repositories:

Click Verify on GitHub.
Sign in to GitHub as a user who can push to the repository.
Pick the repository from the list.

Verify on GitHub links the GitHub user you sign in as to your Jamdesk account, the same as User Settings does. If your browser is already signed in to GitHub as someone else, sign out of GitHub first.

The list shows only repositories your GitHub user can push to. The check lasts one hour, so pick the repository soon after you verify. If Jamdesk says GitHub didn't show any installs you can use, check that you signed in as the right GitHub user. Or ask an owner of the GitHub account to give you access to the repository.

To work in the same project instead, ask its owner to invite you.

Builds not triggering

Check the webhook is active in repository settings
Verify you're pushing to the configured branch
Look for webhook delivery errors in GitHub

Permission denied errors

Re-authorize the GitHub App in your GitHub settings
Confirm the Jamdesk App can access the repository

For more detailed troubleshooting, see Understanding GitHub Integration.

What's Next?

Create a Project

Set up a new Jamdesk project

Directory Structure

Organize your docs for scale