# GitHub integration on Mastra platform

The GitHub integration links a Mastra platform project to a GitHub repository. When you push changes to your repository Studio and Server will automatically be deployed.

> **Note:** The integration only works with repositories hosted on GitHub.com. Self-hosted GitHub Enterprise instances are not currently supported.

After a repository is linked, the platform:

- Builds and deploys Studio and Server on every push to the configured branches.
- Provisions managed databases and the Mastra gateway API key for projects created from a template.
- Surfaces commit, branch, and pull request context on each deploy.
- Reports build status back to GitHub as check runs and to the project dashboard with live status badges and inline logs.

## When to use the GitHub integration

Choose the GitHub integration when you want one of the following:

- Push-to-deploy from `main` or any other branch, including separate branches for Studio and Server.
- A managed onboarding flow that scaffolds a project from a Mastra template, including a fresh repository, managed database, and gateway API key.
- Pull-request and commit context inside the platform dashboard for triage.

The CLI flow (`mastra studio deploy` and `mastra server deploy`) is still available for ad-hoc deploys and CI providers other than GitHub. See [Studio](https://mastra.ai/docs/mastra-platform/studio) and [Server](https://mastra.ai/docs/mastra-platform/server) for the CLI-only path.

## Install the Mastra GitHub App

The integration is powered by the Mastra GitHub App. The App reads repository contents, listens for `push` events on the configured branches, and writes deploy status back as check runs.

1. In the [Mastra platform dashboard](https://projects.mastra.ai), open your organization settings. The page includes a **GitHub App** section.

2. Select **Install GitHub App** and choose the GitHub account or organization to install on.

   If you don't own the GitHub organization, GitHub creates a pending **installation request** that an admin must approve. The dashboard tracks pending requests alongside completed installations.

3. Select the repositories the App can access. You can scope to specific repositories or grant access to all repositories on the account.

   You can revoke or change repository access at any time from GitHub's App settings.

> **Note:** If GitHub later updates the App's required permissions, the dashboard surfaces an **outdated permissions** warning with an approval link. Repository operations return a `403` until an admin re-approves.

### Pending installation requests

When a non-admin requests the App on an organization, the request stays pending until an organization admin approves it on GitHub.com. The dashboard:

- Lists pending requests next to active installations.
- Lets the same user request access to multiple GitHub accounts at once.
- Reconciles pending state against GitHub when you open the page, removing requests an admin has declined or the requester has withdrawn.

To cancel a pending request, select **Cancel** next to it in the dashboard.

## Create a project from a template

Templates are the fastest way to get started. The platform creates a new repository from a Mastra template, links it to a fresh project, provisions any managed databases the template declares, and runs the first deploy.

1. In the dashboard, select **Create project** and choose **Start from a template**.

2. Pick a template and select the GitHub account that owns the new repository. Name the repository and choose whether it should be private.

3. Configure the template's managed database requirements. Templates can declare required databases (such as Turso or Neon) and you pick the provider and region per requirement.

4. Add any template-specific environment variables (for example, AI provider API keys). The platform seeds `MASTRA_GATEWAY_API_KEY` and `MASTRA_PLATFORM_ACCESS_TOKEN` automatically so that template code that talks to the Mastra gateway works on the first deploy.

5. Select **Create project**. The platform creates the repository, writes a `.mastra-project.json` config file into it, provisions the managed databases, and triggers the initial Studio and Server deploys.

The initial deploy waits for managed databases to finish provisioning before it starts, so the template's first build sees the database connection environment variables.

## Link an existing repository

Use this flow when you already have a Mastra project in a GitHub repository.

1. In the dashboard, select **Create project** and choose **Connect an existing repository**, or open an existing project and select **Link repository** from the project settings.

2. Pick an installation, then choose the repository. Repository search works across every repository the App has access to on that installation.

3. Choose the Studio and Server deploy branches. Both targets default to the repository's default branch, and they can share a branch or use different branches.

   You can disable Studio or Server for the project. The manual **Deploy from GitHub** drawer selects both targets by default when both are configured.

4. Select **Link repository**. The platform validates that the repository doesn't already have a `.mastra-project.json` file pointing at a different project. If it does, the dashboard warns you and offers an **Overwrite** option that replaces the file on link.

After linking, the next push to the configured branch triggers a deploy.

### `.mastra-project.json` conflicts

The platform writes a `.mastra-project.json` file into every linked repository to identify the project. When you link a repository that already has one of these files, the dashboard checks its contents before submitting:

- **Missing**: The platform creates the file on link.
- **Matching**: The file already points at the project you're linking, so no change is needed.
- **Conflicting**: The file points at a different project. You can cancel or explicitly overwrite the file.

See [Configuration](https://mastra.ai/docs/mastra-platform/configuration) for the file's schema.

## Push-to-deploy

After a repository is linked, every push to a configured branch triggers a deploy:

- A push to the **Studio branch** triggers a Studio deploy.
- A push to the **Server branch** triggers a Server deploy.
- If both targets share a branch, one push triggers both deploys in parallel.

Each deploy carries the commit SHA, branch, and (when available) the pull request number that introduced the commit. Builds run inside the platform and report status back to GitHub as check runs on the commit.

Only one build per deploy target runs at a time. If a new push arrives while a build is in progress, the platform cancels older queued builds for that same target and runs the latest. Studio and Server builds are tracked independently, so they can run in parallel when both targets are configured.

### Manual GitHub deploys

You can also trigger a deploy from the dashboard without pushing. Open the project, select **Deploy from GitHub**, pick the target (Studio, Server, or both) and a branch, and submit. The platform runs the deploy against the head commit of that branch and records the trigger as a **GitHub Workflow** deploy.

## Track deploys

After a project is created from a template or linked to a repository, the **Setup** page shows one row per deploy target. Each row:

- Displays a live status badge that polls the deploy until it finishes.
- Links to the deploy detail page via the deploy ID.
- Exposes a **Show logs** toggle that streams build and runtime logs inline. Server logs poll every three seconds while the deploy is active.

## Permissions and revocation

To stop deploys from a repository, do one of the following:

- **Unlink the repository** from the project in **Project settings → Repository**. The project keeps its history and you can re-link a different repository later.
- **Remove repository access** for the Mastra GitHub App on GitHub.com. Existing deploys keep running, but no new push triggers a deploy.
- **Uninstall the GitHub App** from the GitHub account. This removes access to every repository on that account.

If GitHub revokes or rotates the App's installation token, repository reads return a `github_app_permissions_outdated` error and the dashboard prompts an admin to re-approve permissions.

## Related

- [Mastra platform overview](https://mastra.ai/docs/mastra-platform/overview)
- [Studio on Mastra platform](https://mastra.ai/docs/mastra-platform/studio)
- [Server on Mastra platform](https://mastra.ai/docs/mastra-platform/server)
- [Configuration](https://mastra.ai/docs/mastra-platform/configuration)