GitHub
Use GitHub with Mastra in two ways:
- Agent tools let an agent work with repositories, issues, pull requests, releases, and workflow runs through Mastra Connect.
- Pull request signals let an agent follow pull requests (PRs) and react when they change.
ConnectDirect link to Connect
Before you start, complete the Connect setup to install @mastra/connect and configure your platform project. Connect keeps GitHub credentials on the Mastra platform, so your application never stores them.
Agent toolsDirect link to Agent tools
Give agents tools to search code and repositories, manage issues, pull requests, branches, files, and releases, and inspect and rerun workflow runs in GitHub.
Connect an account with the github provider ID. Run this command from the directory that contains your .env file:
mastra connect add github
Then pass tools() to the agent and select the provider:
import { Agent } from '@mastra/core/agent'
import { tools } from '@mastra/connect'
export const githubAgent = new Agent({
id: 'github-agent',
name: 'GitHub agent',
instructions:
'You help people search code and repositories, manage issues, pull requests, branches, files, and releases, and inspect and rerun workflow runs in GitHub.',
model: '__GATEWAY_OPENAI_MODEL_LUNA__',
tools: tools({ providers: ['github'] }),
})
The agent gets 49 GitHub tools, with keys such as github_add_issue_comment. See GitHub tools for the full list, and the tools() parameters to restrict tools or require approval before a call runs.
Pull request signalsDirect link to Pull request signals
The @mastra/github-signals provider polls subscribed PRs and sends notification signals to the agent thread when relevant activity occurs. It runs on your own infrastructure and uses the GitHub CLI for access instead of a Connect connection.
InstallationDirect link to Installation
Install GitHub Signals and the memory packages used in this example:
- npm
- pnpm
- Yarn
- Bun
npm install @mastra/github-signals @mastra/libsql @mastra/memory
pnpm add @mastra/github-signals @mastra/libsql @mastra/memory
yarn add @mastra/github-signals @mastra/libsql @mastra/memory
bun add @mastra/github-signals @mastra/libsql @mastra/memory
PrerequisitesDirect link to Prerequisites
GitHub Signals requires:
- A Mastra storage adapter with memory and notification support. The provider stores each subscription in the thread's metadata, so the thread must already exist.
- The
gitcrawlcommand onPATH, configured to access the repositories you want to monitor. The provider runsgitcrawl syncand reads its SQLite database. - The
sqlite3command onPATH. - The GitHub CLI installed and authenticated. The provider uses real
gh apiresponses to check repository permissions and GitHub App ownership before notifying the agent.
By default, comments from users with admin, maintain, or write access can trigger notifications. CodeRabbit and Devin bot comments are explicitly allowed.
Bot authorization checks ignoredBots first, using an exact case-insensitive login match. Other bots can trigger notifications when they're listed in authorizedBots, when the GitHub App is owned by a user whose repository permission is listed in authorizedPermissions, or when the app is owned by the organization that owns the repository. The default authorized permissions are admin, maintain, and write.
Failed, inaccessible, malformed, and unsupported app-owner lookups deny the bot comment. Successful app-owner lookups are cached for 24 hours. Failed lookups aren't cached.
Agent and subscriptionDirect link to Agent and subscription
Create one GithubSignals instance and register it on the agent. Register the agent and a storage adapter on the Mastra instance:
import { Agent } from '@mastra/core/agent'
import { Mastra } from '@mastra/core/mastra'
import { Memory } from '@mastra/memory'
import { GithubSignals } from '@mastra/github-signals'
import { LibSQLStore } from '@mastra/libsql'
export const githubSignals = new GithubSignals()
export const devAgent = new Agent({
id: 'dev-agent',
name: 'Development Agent',
instructions: 'Triage pull request activity and help resolve issues.',
model: 'openai/gpt-6.1-sol',
memory: new Memory(),
signals: [githubSignals],
})
export const mastra = new Mastra({
agents: { devAgent },
storage: new LibSQLStore({
id: 'mastra-storage',
url: 'file:./mastra.db',
}),
})
After the agent has created a memory thread, subscribe that thread to a PR. Choose review mode when the thread only needs code revisions, authorized latest PR comments, and observable review-thread-state updates:
await githubSignals.subscribeThreadToPR({
threadId: 'thread-123',
resourceId: 'user-123',
pr: {
owner: 'acme',
repo: 'web-app',
number: 42,
},
mode: 'review',
})
The provider syncs the PR immediately, stores the subscription, and starts polling every five minutes. Set pollIntervalMs in the GithubSignals constructor to change the interval. If the process restarts, call startPollingForThread() for each persisted thread subscription to resume polling.
A thread has one current GitHub Signals subscription. Subscribing it to another PR replaces the existing subscription.
Subscription modesDirect link to Subscription modes
GitHub Signals supports two subscription modes:
review: Follows new head revisions, authorized latest PR comments, and observable review-thread-state changes, including when all review threads become resolved.working: Follows all PR activity that can trigger a notification detected by the provider. Comment-bearing notifications remain subject to existing authorization gates. This is the default whenmodeis omitted and for stored subscriptions without a valid mode.
The following table shows the observable behavior of each mode:
| Pull request activity | working | review |
|---|---|---|
| First observation | Sends a baseline notification | Saves all cursors without notifying unless the PR is closed or merged; then notifies and removes the subscription |
| New commit or force-push | Notifies when the latest comment author is authorized | Notifies without requiring a comment author |
| New authorized latest PR comment | Notifies | Notifies |
| Observable review-thread-state change | Notifies while unresolved threads remain | Notifies, including when all review threads become resolved |
| Continuous integration checks start, fail, or recover | Notifies | Saves the new state without notifying |
| Merge conflicts appear or resolve | Notifies | Saves the new state without notifying |
| Other aggregate PR activity that can trigger a notification | Notifies when applicable authorization checks pass | Saves the new state without notifying |
| PR closes without merging | Notifies and keeps the subscription | Notifies and removes the subscription |
| PR reopens | Notifies | Doesn't notify because the earlier close removed the subscription |
| PR merges | Notifies and removes the subscription | Notifies and removes the subscription |
Review mode uses the latest generic PR comment exposed by gitcrawl, and the snapshot doesn't distinguish general PR conversation from inline review comments. Comment notifications require an authorized author because they include comment content. Review-state notifications contain only provider-generated state summaries and aren't author-gated.
The review-state cursor includes the unresolved thread count and the latest unresolved thread timestamp. It reports when the count reaches zero, but it can't report replies on threads that are already resolved.
During subscription, a PR already known to be closed or merged isn't stored and doesn't send an activity notification. Otherwise, review mode silently saves its first available non-terminal snapshot, including when the subscribe-time snapshot fails and a later poll supplies the first observation. If the first available poll snapshot or a later snapshot is closed or merged, the provider sends a terminal notification and removes the subscription. It doesn't follow a later reopen unless you subscribe again.
Subscription toolsDirect link to Subscription tools
The provider adds github_subscribe_pr and github_unsubscribe_pr tools to the agent. Pass mode when subscribing:
{
"owner": "acme",
"repo": "web-app",
"number": 42,
"mode": "review"
}
Omitting mode selects working. Don't subscribe for a one-off PR inspection.
MastraCode commandsDirect link to MastraCode commands
In MastraCode, use the spaced --mode flag with a PR number, owner/repo#number, or full GitHub PR URL:
/github subscribe 42 --mode review
/github acme/web-app#42 --mode working
/github unsubscribe 42
/github debug
MastraCode rejects --mode=review, missing or repeated mode values, unknown modes, and mode flags on unsubscribe. /github debug shows the stored mode and displays absent or invalid legacy values as working.