> ## Documentation Index
> Fetch the complete documentation index at: https://docs.mixpeek.com/docs/llms.txt
> Use this file to discover all available pages before exploring further.

# GitHub Integration

> Connect a GitHub repo to your Canvas app for automatic deploys on push and preview URLs on pull requests.

## Overview

Connect a GitHub repository to a Canvas app and every push to your branch triggers an automatic build and deploy. Pull requests get [preview URLs](/canvas/apps/preview-deploys) for live review before merging.

***

## Connecting a repo

```bash theme={null}
curl -X POST https://api.mixpeek.com/v1/apps/$APP_ID/connect-repo \
  -H "Authorization: Bearer $API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "repo_url": "https://github.com/your-org/your-repo",
    "branch": "main"
  }'
```

This configures a GitHub webhook that listens for `push` and `pull_request` events on the specified branch.

***

## Automatic deploys on push

When you push to the connected branch:

1. GitHub sends a `push` webhook to Canvas
2. Canvas clones your repo and checks out the pushed commit
3. Runs `npm ci` to install dependencies
4. Runs `npm run build` to produce the build output
5. Zips the `dist/` directory and deploys it

Build output is streamed in real time — see [Build Logs](/canvas/apps/build-logs).

<Note>
  Canvas auto-detects your build output directory. It looks for `dist/`, `build/`, or `out/` in order.
</Note>

***

## What gets built

Canvas runs a standard Node.js build process:

```
git clone <repo_url> --branch <branch> --depth 1
cd <repo>
npm ci
npm run build
```

Your `package.json` must include a `build` script. The build output must contain an `index.html`.

***

## Git metadata in versions

Every deploy from GitHub automatically records git metadata in the version record:

| Field            | Description                              |
| ---------------- | ---------------------------------------- |
| `git_commit_sha` | The commit SHA that triggered the deploy |
| `git_author`     | Author of the commit                     |
| `git_branch`     | Branch name                              |

This metadata is visible in [Version History](/canvas/apps/versions) and in Studio.

***

## Webhook events

| Event                         | Canvas behavior                                          |
| ----------------------------- | -------------------------------------------------------- |
| `push` to connected branch    | Build and deploy to production                           |
| `pull_request` opened/updated | Build and deploy [preview](/canvas/apps/preview-deploys) |
| `pull_request` closed         | Clean up preview environment                             |

***

## Disconnecting

To stop automatic deploys, remove the webhook from your GitHub repository settings or update the app's configuration to remove the `repo_url`.

***

## Related

* [Deploy from Code](/canvas/apps/deploy)
* [Preview Deploys](/canvas/apps/preview-deploys)
* [Build Logs](/canvas/apps/build-logs)
* [Version History](/canvas/apps/versions)