GitHub Integration
Jamdesk uses two GitHub connections: a GitHub App for repository access and a personal account link for build attribution.
Jamdesk uses two separate GitHub connections with different jobs.
TL;DR: The GitHub App gives Jamdesk access to your repository. Linking your personal account attributes your commits to you.
Bitbucket Cloud projects work differently. One OAuth authorization covers repository access, the webhook, and build attribution. See Connect Bitbucket.
Overview
| Connection | Purpose | Scope | Required? |
|---|---|---|---|
| GitHub App | Repository access & webhooks | Per-project | Yes |
| Personal Account | User identity & attribution | Per-user | Recommended |
GitHub App (Project-level)
The Jamdesk GitHub App is installed on your GitHub account or organization. It gives Jamdesk access to the repositories you pick.
What it does
- Reads repository content: clones your docs to build them
- Receives webhooks: gets notified when you push changes
- Reports build status: shows deployment status on commits
Why you need it
Without the GitHub App installed, Jamdesk cannot:
- Access your repository to build documentation
- Automatically deploy when you push changes
- Show build status on GitHub commits
How it works
Project setup walks you through connecting GitHub. Pick one of two paths.
Create a starter docs repo (default for new projects)
Authorize Jamdesk to create a repository on your account or organization.
Pick your personal account or an organization. Jamdesk creates a new repository pre-filled with starter documentation.
Install the Jamdesk GitHub App (or grant it access to the new repo). The app builds and auto-deploys your docs.
Every push to your configured branch automatically triggers a deployment. Customize the starter docs whenever you're ready.
Connect an existing repo
Install the Jamdesk GitHub App and grant it access to your docs repository. Then choose the repo and branch in Jamdesk under Project Settings → Git Repository. The rest works the same way.
One app, multiple projects
One GitHub App installation can serve multiple Jamdesk projects:
- Install the app once on your account or organization
- Connect different repositories to different Jamdesk projects
- Each project has its own branch and path configuration
An organization admin installs the GitHub App once. Any team member can then create Jamdesk projects from repositories the app can access.
Personal GitHub Account (User-level)
Linking your personal GitHub account associates your GitHub identity with your Jamdesk profile. This is separate from the GitHub App.
What it does
- Identifies you: associates your GitHub username with your Jamdesk account
- Attributes builds: shows who triggered each deployment
- Team visibility: teammates see who made changes
Why you need it
Jamdesk has to match each push to a user. Without your account linked:
- Jamdesk falls back to matching by email address
- If your Git commit email differs from your Jamdesk email, attribution fails
- Build history may show "Unknown user" for your commits
Common issue: Git uses a personal email. Your Jamdesk account uses a work email. Link your GitHub account to fix attribution.
Check your Git email
git config user.email
git config --global user.email "you@company.com"Set it to your Jamdesk account email. A mismatch shows "Unknown user" in build history.
How to link your account
Click your avatar in the top right, then select User Settings.
Scroll to the GitHub Account card.
A popup opens to GitHub. Authorize Jamdesk to read your profile.
Your GitHub username appears in your Jamdesk profile.
How They Work Together
Think of them as two separate keys:
| Key | Opens | Owned by |
|---|---|---|
| GitHub App | Access to repositories | Project/Organization |
| Personal Link | Your identity | Individual user |
Team Example
A team of 3 developers works on company docs:
- Admin installs GitHub App on the organization
- Admin creates Jamdesk project connected to docs repo
- Each developer links their personal account
Now when any developer pushes:
- The GitHub App allows Jamdesk to read the repo and build
- The Personal link identifies who triggered the build
Solo Developer Example
Solo developers still need the two connections:
- GitHub App: connects your repo to Jamdesk
- Personal link: shows your name on your commits in build history
Disconnecting & Unlinking
Each action removes a different piece of access.
Disconnect GitHub (Project Settings)
What it does: Removes the repository connection from a single Jamdesk project.
Effects:
- Automatic deployments stop for that project
- The GitHub App stays installed on GitHub
- Other Jamdesk projects are unaffected
- Your personal account link is unaffected
When to use: You want to connect a different repository, or temporarily stop deployments.
How to reconnect: Go to Project Settings → Git Repository and select a repository.
Unlink GitHub (User Settings)
What it does: Removes your GitHub identity from your Jamdesk profile.
Effects:
- Your GitHub username no longer appears in your profile
- Build attribution falls back to email matching
- All repository connections remain intact
- The GitHub App stays installed
When to use: You want to link a different GitHub account, or remove the connection.
How to re-link: Go to User Settings → GitHub Account → Link GitHub Account.
Uninstall GitHub App (On GitHub)
What it does: Removes Jamdesk's access to your GitHub account.
Effects:
- All Jamdesk projects using this installation lose access
- Automatic deployments stop for all affected projects
- Webhooks are removed
- Personal account links are unaffected
Only uninstall the GitHub App if you want to remove Jamdesk access from every repository. This affects every Jamdesk project connected to your GitHub account.
How to uninstall:
- Go to GitHub Settings → Applications → Installed GitHub Apps
- Find "Jamdesk" and click Configure
- Scroll down and click Uninstall
Quick Reference
| Action | Location | Scope | Reversible? |
|---|---|---|---|
| Disconnect GitHub | Project Settings → Git Repository | Single project | Yes - reconnect anytime |
| Unlink GitHub | User Settings → GitHub Account | Your account | Yes - re-link anytime |
| Uninstall GitHub App | GitHub Settings | All projects | Yes - reinstall |
Troubleshooting
"Already have Jamdesk installed?"
If you've already installed the Jamdesk GitHub App, "Install GitHub App" opens GitHub's settings page instead of the installation page. Complete setup there:
Scroll down to the Repository access section on GitHub's settings page.
If the Save button is disabled (grayed out), switch from "All repositories" to "Only select repositories", then switch back.
Click the green Save button. Jamdesk detects the change and continues setup.
Popup blocked
If the GitHub popup doesn't open, your browser may have blocked it. Look for a popup blocker icon in your address bar, allow popups from Jamdesk, then click Try Again.
"My builds show 'Unknown user'"
Your personal GitHub account isn't linked. Go to User Settings → Link GitHub Account.
"Repository not showing up"
The GitHub App doesn't have access to that repository. Go to GitHub Settings, find Jamdesk, and add the repository.
"Builds aren't triggering"
- Check the repository is connected in Project Settings → Git Repository
- Verify you're pushing to the configured branch
- Check webhook delivery in GitHub repository settings
If those look right, the person who pushed may not be a member of the project. Jamdesk builds a push only from a project member. It matches the pusher by their linked GitHub account, or by their commit email matching the email they sign in to Jamdesk with.
With no match, the build shows as failed with the reason. The project owner gets an email, at most one a week per person. A push that changes nothing in your docs folder sends no email.
Invite the person in Project Settings → Members with their commit email. They need to sign in to Jamdesk with that email to accept. If they're already a member, they can link their GitHub account in User Settings instead.
"I can't access organization repositories"
An organization admin must approve the GitHub App installation. Ask your admin to install or approve Jamdesk in the organization settings.
"GitHub keeps sending me back to the Jamdesk app page"
Your company probably manages your GitHub account. GitHub doesn't let managed accounts install apps on themselves. See company-managed GitHub accounts for the fix.