---
title: Connect GitHub
description: "Connect your GitHub repository to Jamdesk for automatic deployments on push. Covers app installation, repository selection, and branch configuration."
---

> **For AI agents:** the complete documentation index is at [llms.txt](/docs/llms.txt). Append `.md` to any page URL for its markdown version.

Jamdesk integrates with GitHub to automatically deploy your documentation when you push changes.

<Note>
For background on how the GitHub App and personal account linking work together, see [Understanding GitHub Integration](/integrations/github).
</Note>

## 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 |

<Note>
Jamdesk only accesses repositories you explicitly grant access to. You can modify access anytime in your GitHub settings.
</Note>

## Connect a Repository

<Steps>
  <Step title="Select repository">
    When creating or editing a project, click **Connect Repository**.

    Choose from repositories where the GitHub App is installed.
  </Step>

  <Step title="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
  </Step>

  <Step title="Specify docs path">
    If your `docs.json` isn't in the repository root, specify the path:

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

    Leave blank if `docs.json` is in the root.
  </Step>
</Steps>

Once connected, your project dashboard shows the linked repository and branch:

<img src="/images/dashboard/github-connected.webp" alt="Dashboard showing GitHub repository connected with Linked status badge, repository name, and branch" style={{ display: 'block', margin: '0 auto', maxWidth: '500px' }} />

## Automatic Deployments

Once connected, every push to your configured branch triggers a build:

```bash
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:

1. Go to **Settings** → **Repository**
2. Click **Change Repository**
3. Select the new repository and branch

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

## Managing GitHub App Access

Control which repositories Jamdesk can access:

1. Go to [github.com/settings/installations](https://github.com/settings/installations)
2. Find **Jamdesk** in the list
3. Click **Configure**
4. Under "Repository access", select specific repositories or all

### Organization Repositories

For organization repositories, an organization admin must approve the GitHub App installation:

1. Request installation from your Jamdesk dashboard
2. An admin receives a notification in GitHub
3. Once approved, organization repos appear in the repository selector

## Linking Your Personal Account

For reliable build attribution, link your personal GitHub account in **User Settings**:

1. Click your avatar → **User Settings**
2. Find the **GitHub Account** section
3. Click **Link GitHub Account**

This is separate from the GitHub App and ensures your commits are properly attributed to you. [Learn more](/integrations/github#personal-github-account-user-level).

## 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

<Note>
  For more detailed troubleshooting, see [Understanding GitHub Integration](/integrations/github).
</Note>

## What's Next?

<Columns cols={2}>
  <Card title="Create a Project" icon="plus" href="/setup/creating-projects">
    Set up a new Jamdesk project
  </Card>
  <Card title="Directory Structure" icon="folder-tree" href="/setup/directory-structure">
    Organize your docs for scale
  </Card>
</Columns>