Connecting GitHub
Link your GitHub repository for automatic deployments
Jamdesk integrates with GitHub to automatically deploy your documentation when you push changes.
GitHub App Installation
When you first sign in to Jamdesk, you'll be prompted to install the Jamdesk GitHub App. This app enables:
- 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) | Clone and read your documentation files |
| Metadata (read) | List repositories and branches |
| Webhooks | Receive push notifications |
Jamdesk only accesses repositories you explicitly grant access to. You can modify access anytime in your GitHub settings.
Connect a Repository
When creating or editing a project, click Connect Repository.
Choose from repositories where the GitHub App is installed.
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
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.
Automatic Deployments
Once connected, every push to your configured branch triggers a build:
git add .
git commit -m "Update API documentation"
git push origin mainBuilds 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
For organization repositories, an organization admin must approve the GitHub App installation:
- Request installation from your Jamdesk dashboard
- An admin receives a notification in GitHub
- Once approved, organization repos appear in the repository selector
Troubleshooting
Repository not showing up
- Verify the GitHub App is installed on the repository
- For organization repos, confirm an admin has approved access
- Try refreshing the repository list in the dashboard
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
- Ensure the repository is accessible to the Jamdesk App