# Building a PR description agent for GitHub Actions

In this guide, you'll build a [GitHub Action](https://docs.github.com/en/actions) that uses a Mastra agent to read pull request diffs, generate multi-language summaries, and write them directly to the PR description in the GitHub UI. The action runs whenever a pull request is created or updated and regenerates the description as the diff changes.

This approach is similar to AI-powered PR tools like [CodeRabbit](https://coderabbit.ai/) and [Greptile](https://www.greptile.com/), but built using native GitHub Actions workflows and Mastra agents.

The setup consists of three parts:

- A Mastra agent that generates the description
- A GitHub Actions workflow that triggers on pull requests
- A Node.js script that connects the workflow to the agent

The finished action writes a description with summaries in English, Spanish, and Japanese, each marked with a flag emoji for quick scanning. For example:

```text
🇬🇧 English
This PR integrates Astro into the project, adding configuration files and updating scripts to support Astro development.

🇪🇸 Español
Este PR integra Astro en el proyecto, añadiendo archivos de configuración y actualizando scripts para soportar el desarrollo con Astro.

🇯🇵 日本語
このPRは、Astroをプロジェクトに統合し、Astro開発をサポートするための設定ファイルを追加し、スクリプトを更新します。
```

## Before you begin

- A Mastra project (see [Quickstart](https://mastra.ai/guides/getting-started/quickstart))
- An API key from a supported [model provider](https://mastra.ai/models). If you don't have a preference, use [OpenAI](https://mastra.ai/models/providers/openai)
- Node.js `v22.13.0` or later

### Set up repository secrets

The workflow needs access to your model provider API key. Add it as a repository secret in GitHub:

1. Go to your repository on GitHub

2. Navigate to **Settings** > **Secrets and variables** > **Actions**

3. Click **New repository secret**

4. Add your API key with the name `OPENAI_API_KEY` (or the appropriate key for your provider)

   ![Screenshot of repository secrets in GitHub UI](/assets/images/github-action-repository-secrets-4e97642b3aa65178a3459a5deebe6f79.jpg)

The workflow references this secret as `${{ secrets.OPENAI_API_KEY }}` and makes it available to the Mastra agent at runtime.

## Create the description agent

The PR description agent is responsible for turning a git diff into a clear, reviewer-friendly pull request description.

This agent receives the raw diff from a pull request. It generates descriptions in the configured languages and formats the output using emoji flags so each language section is quick to scan in the PR.

```ts
import { Agent } from '@mastra/core/agent'

export const descriptionAgent = new Agent({
  id: 'description-agent',
  name: 'PR Description Agent',
  instructions: `You are a helpful assistant that creates clear, concise PR descriptions.

When given a git diff of changed files, you will:
1. Analyze the changes to understand what was modified
2. Write a brief summary and list of changes
3. Output the same content in English, Spanish, and Japanese

Guidelines:
- Be concise but informative
- Focus on the "what" and "why" of changes
- Use technical terms appropriately
- Keep bullet points short and scannable
- Each language section should contain the same information, naturally translated

Output format:

### 🇬🇧 English

[1-2 sentence summary]

- [Change 1]
- [Change 2]
- [Change 3]

---

### 🇪🇸 Español

[Same summary in Spanish]

- [Same changes in Spanish]

---

### 🇯🇵 日本語

[Same summary in Japanese]

- [Same changes in Japanese]
`,
  model: 'openai/gpt-5.4',
})
```

### Test the agent locally

Before deploying the workflow, you can test the agent in [Studio](https://mastra.ai/docs/studio/overview) to verify it generates descriptions correctly.

1. Get a diff from any public GitHub PR by appending `.diff` to the PR URL:

   ```text
   https://github.com/owner/repo/pull/123.diff
   ```

2. Open the PR Description Agent in Studio and paste the diff content with this prompt:

"Please create a PR description for the following changes. `<paste the diff content here>`"

The agent will return a formatted description with sections in English, Spanish, and Japanese.

## GitHub actions

GitHub Actions run your workflows in short-lived environments on GitHub's infrastructure. Each run starts with a clean virtual machine, checks out your code, installs dependencies, runs your workflow steps, and then shuts down. Nothing persists between runs unless you explicitly save it as an artifact or cache.

### Create the workflow

GitHub Actions workflows live in the `.github/workflows` directory. Create a `.github` directory at the root of your project, then create a `workflows` directory inside it. Add a file named `pr-description.yml`.

This workflow runs whenever a pull request is opened or updated. It generates a diff for the PR, calls the Mastra agent to describe the changes, and writes the description directly into the PR in the GitHub UI.

```yaml
name: PR Description Generator

on:
  pull_request:
    types: [opened, synchronize]

permissions:
  contents: read
  pull-requests: write

env:
  GH_TOKEN: ${{ secrets.GITHUB_TOKEN }}
  OPENAI_API_KEY: ${{ secrets.OPENAI_API_KEY }}
  PR_DIFF_FILE: /tmp/pr_diff.txt
  PR_DESCRIPTION_FILE: /tmp/pr_description.md

jobs:
  generate-description:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4
        with:
          fetch-depth: 0

      - uses: actions/setup-node@v4
        with:
          node-version: '22'
          cache: 'npm'

      - run: npm ci

      - id: pr
        run: |
          BASE_REF=$(gh pr view ${{ github.event.pull_request.number }} --json baseRefName -q '.baseRefName')
          git fetch origin $BASE_REF
          git diff origin/$BASE_REF...HEAD -- . ':!package-lock.json' > $PR_DIFF_FILE

      - run: npx tsx .github/scripts/generate-description.ts

      - run: gh pr edit ${{ github.event.pull_request.number }} --body-file $PR_DESCRIPTION_FILE
```

#### The workflow explained

- **`on: pull_request`**: Runs when a pull request is opened or updated.
- **`permissions: pull-requests: write`**: Allows the workflow to update the PR description.
- **`env`**: Defines shared file paths used across steps and reads required values from repository secrets, including the model API key used by the Mastra agent.
- **`actions/checkout@v4` + git commands**: Checks out the full repository history, fetches the PR base branch, and writes the PR diff to `/tmp/pr_diff.txt`.
- **`actions/setup-node@v4`**: Sets up the Node.js runtime used by the workflow.
- **`npm ci`**: Installs the repository's Node.js dependencies from the lockfile.
- **`generate-description.ts`**: Reads `/tmp/pr_diff.txt`, calls the Mastra agent, and writes the generated description to `/tmp/pr_description.md`.
- **`gh pr edit`**: Updates the pull request description using the contents of `/tmp/pr_description.md`.

> **Note:** The workflow excludes `package-lock.json` when generating the diff. Lockfiles are often large and noisy, and including them can overwhelm the agent's context window and make the resulting description harder to reason about.

### Create the workflow script

Create a `scripts` directory inside `.github` and add a file named `generate-description.ts`.

This script reads the PR diff from `PR_DIFF_FILE`, generates a description using the Mastra agent, and writes the result to `PR_DESCRIPTION_FILE` for the workflow to publish to the pull request.

```typescript
import { readFileSync, writeFileSync } from 'fs'
import { mastra } from '../../src/mastra'

const agent = mastra.getAgent('descriptionAgent')

await agent.generate(
  `Please create a PR description for the following changes.

Git diff:
\`\`\`diff
${readFileSync(process.env.PR_DIFF_FILE!, 'utf-8')}
\`\`\``,
  {
    onError: () => {
      writeFileSync(
        process.env.PR_DESCRIPTION_FILE!,
        'This PR diff is too large to generate a description automatically.',
      )
    },
    onFinish: result => {
      writeFileSync(process.env.PR_DESCRIPTION_FILE!, result.text)
    },
  },
)
```

#### The workflow script explained

- **`mastra.getAgent("descriptionAgent")`**: Gets the Mastra agent that generates the PR description.
- **`agent.generate(...)`**: Reads the pull request diff from `PR_DIFF_FILE` and asks the agent to write a PR description.
- **`onError` callback**: Writes a fallback message to `PR_DESCRIPTION_FILE` when the diff is too large to process.
- **`onFinish` callback**: Writes the generated PR description to `PR_DESCRIPTION_FILE`.

## Next steps

You now have a GitHub Action that generates multi-language PR descriptions using a Mastra agent. Once the workflow and supporting files are merged into your main branch, the agent will run automatically the next time a pull request is created or updated. You can monitor the run in the **Actions** tab of your repository.

From here, you can customize the agent instructions, change the output languages, or extend the workflow to handle other events.

To learn more:

- Read the [agents](https://mastra.ai/docs/agents/overview) documentation
- Give your agent [tools](https://mastra.ai/docs/agents/using-tools) to fetch additional context
- Explore other [GitHub Actions triggers](https://docs.github.com/en/actions/using-workflows/events-that-trigger-workflows) like issue comments or releases