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.
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 integrationDirect link to When to use the GitHub integration
Choose the GitHub integration when you want one of the following:
- Push-to-deploy from
mainor 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 and Server for the CLI-only path.
Install the Mastra GitHub AppDirect link to 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.
In the Mastra platform dashboard, open your organization settings. The page includes a GitHub App section.
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.
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.
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 requestsDirect link to 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 templateDirect link to 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.
In the dashboard, select Create project and choose Start from a template.
Pick a template and select the GitHub account that owns the new repository. Name the repository and choose whether it should be private.
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.
Add any template-specific environment variables (for example, AI provider API keys). The platform seeds
MASTRA_GATEWAY_API_KEYandMASTRA_PLATFORM_ACCESS_TOKENautomatically so that template code that talks to the Mastra gateway works on the first deploy.Select Create project. The platform creates the repository, writes a
.mastra-project.jsonconfig 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 repositoryDirect link to Link an existing repository
Use this flow when you already have a Mastra project in a GitHub repository.
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.
Pick an installation, then choose the repository. Repository search works across every repository the App has access to on that installation.
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.
Select Link repository. The platform validates that the repository doesn't already have a
.mastra-project.jsonfile 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 conflictsDirect link to mastra-projectjson-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 for the file's schema.
Push-to-deployDirect link to 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 deploysDirect link to 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 deploysDirect link to 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 revocationDirect link to 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.