> ## 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](https://docs.mixpeek.com/docs/canvas/apps/preview-deploys.md) 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](https://docs.mixpeek.com/docs/canvas/apps/build-logs.md).

> [!NOTE]
>
> Canvas auto-detects your build output directory. It looks for `dist/`, `build/`, or `out/` in order.

***

## 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](https://docs.mixpeek.com/docs/canvas/apps/versions.md) 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](https://docs.mixpeek.com/docs/canvas/apps/preview-deploys.md) |
| `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](https://docs.mixpeek.com/docs/canvas/apps/deploy.md)
* [Preview Deploys](https://docs.mixpeek.com/docs/canvas/apps/preview-deploys.md)
* [Build Logs](https://docs.mixpeek.com/docs/canvas/apps/build-logs.md)
* [Version History](https://docs.mixpeek.com/docs/canvas/apps/versions.md)


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.