Créer un Agent de descriptions de PR pour GitHub Actions

Dans ce guide, vous créerez une GitHub Action qui utilise un Agent Mastra pour lire les diffs de pull requests, générer des résumés multilingues et les écrire directement dans la description de PR de l’interface GitHub. L’Action s’exécute à chaque création ou mise à jour d’une pull request et régénère la description lorsque le diff change.

Cette approche est semblable aux outils de PR alimentés par l’IA, comme CodeRabbit et Greptile, mais elle est conçue avec des Workflows GitHub Actions natifs et des Agents Mastra.

La configuration se compose de trois éléments :

• Un Agent Mastra qui génère la description
• Un Workflow GitHub Actions qui se déclenche pour les pull requests
• Un script Node.js qui relie le Workflow à l’Agent

L’Action terminée écrit une description avec des résumés en anglais, en espagnol et en japonais, chacun marqué d’un emoji de drapeau pour faciliter la lecture rapide. Par exemple :

🇬🇧 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開発をサポートするための設定ファイルを追加し、スクリプトを更新します。

Avant de commencer

• Un projet Mastra (consultez le démarrage rapide)
• Une clé API d’un fournisseur de modèles pris en charge. Si vous n’avez pas de préférence, utilisez OpenAI
• Node.js v22.13.0 ou version ultérieure

Configurer les secrets du dépôt

Le Workflow doit accéder à la clé API de votre fournisseur de modèles. Ajoutez-la comme secret de dépôt dans GitHub :

1. Accédez à votre dépôt sur GitHub

2. Accédez à Settings > Secrets and variables > Actions

3. Cliquez sur New repository secret

4. Ajoutez votre clé API sous le nom OPENAI_API_KEY, ou la clé appropriée pour votre fournisseur

   

Le Workflow référence ce secret avec ${{ secrets.OPENAI_API_KEY }} et le met à la disposition de l’Agent Mastra à l’exécution.

Créer l’Agent de description

L’Agent de description de PR transforme un diff Git en une description de pull request claire et utile aux personnes qui effectuent la revue.

Cet Agent reçoit le diff brut d’une pull request. Il génère les descriptions dans les langues configurées et formate la sortie avec des emojis de drapeaux afin que chaque section de langue soit rapidement lisible dans la PR.

src/mastra/agents/description-agent.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.6-sol',
})

Tester l’Agent localement

Avant de déployer le Workflow, vous pouvez tester l’Agent dans Studio afin de vérifier qu’il génère correctement les descriptions.

1. Obtenez le diff de n’importe quelle PR GitHub publique en ajoutant .diff à l’URL de la PR :

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

2. Ouvrez l’Agent de description de PR dans Studio et collez le contenu du diff avec ce prompt :

« Veuillez créer une description de PR pour les modifications suivantes. <paste the diff content here> »

L’Agent retourne une description formatée avec des sections en anglais, en espagnol et en japonais.

GitHub Actions

GitHub Actions exécute vos Workflows dans des environnements de courte durée sur l’infrastructure GitHub. Chaque exécution démarre avec une machine virtuelle propre et extrait votre code. Elle installe les dépendances avant d’exécuter les étapes du Workflow. L’environnement s’arrête lorsque l’exécution est terminée. Rien ne persiste entre les exécutions, sauf si vous l’enregistrez explicitement comme artefact ou dans un cache.

Créer le Workflow

Les Workflows GitHub Actions se trouvent dans le répertoire .github/workflows. Créez un répertoire .github à la racine de votre projet, puis un répertoire workflows à l’intérieur. Ajoutez pr-description.yml.

Ce Workflow s’exécute à chaque ouverture ou mise à jour d’une pull request. Il génère un diff pour la PR, appelle l’Agent Mastra pour décrire les changements et écrit directement la description dans la PR de l’interface GitHub.

.github/workflows/pr-description.yml

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

Explication du Workflow

• on: pull_request : s’exécute à l’ouverture ou à la mise à jour d’une pull request.
• permissions: pull-requests: write : autorise le Workflow à mettre à jour la description de PR.
• env : définit les chemins de fichiers partagés entre les étapes et lit les valeurs requises depuis les secrets du dépôt, y compris la clé API de modèle utilisée par l’Agent Mastra.
• actions/checkout@v4 + commandes Git : extrait l’historique complet du dépôt, récupère la branche de base de la PR et écrit le diff de la PR dans /tmp/pr_diff.txt.
• actions/setup-node@v4 : configure le runtime Node.js utilisé par le Workflow.
• npm ci : installe les dépendances Node.js du dépôt à partir du fichier de verrouillage.
• generate-description.ts : lit /tmp/pr_diff.txt, appelle l’Agent Mastra et écrit la description générée dans /tmp/pr_description.md.
• gh pr edit : met à jour la description de pull request avec le contenu de /tmp/pr_description.md.

remarque

Le Workflow exclut package-lock.json lors de la génération du diff. Les fichiers de verrouillage sont souvent volumineux et bruyants ; les inclure peut saturer la fenêtre de contexte de l’Agent et rendre la description obtenue plus difficile à analyser.

Créer le script du Workflow

Créez un répertoire scripts dans .github et ajoutez generate-description.ts.

Ce script lit le diff de PR depuis PR_DIFF_FILE, génère une description avec l’Agent Mastra, puis écrit le résultat dans PR_DESCRIPTION_FILE afin que le Workflow le publie dans la pull request.

.github/scripts/generate-description.ts

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)
    },
  },
)

Explication du script du Workflow

• mastra.getAgent("descriptionAgent") : récupère l’Agent Mastra qui génère la description de PR.
• agent.generate(...) : lit le diff de pull request depuis PR_DIFF_FILE et demande à l’Agent d’écrire une description de PR.
• Callback onError : écrit un message de secours dans PR_DESCRIPTION_FILE lorsque le diff est trop volumineux pour être traité.
• Callback onFinish : écrit la description de PR générée dans PR_DESCRIPTION_FILE.

Étapes suivantes

Vous disposez maintenant d’une GitHub Action qui génère des descriptions de PR multilingues avec un Agent Mastra. Une fois le Workflow et les fichiers associés fusionnés dans votre branche principale, l’Agent s’exécutera automatiquement à la prochaine création ou mise à jour d’une pull request. Vous pouvez suivre l’exécution dans l’onglet Actions de votre dépôt.

À partir de là, personnalisez les instructions de l’Agent ou modifiez les langues de sortie. Vous pouvez aussi étendre le Workflow afin de gérer d’autres événements.

Pour en savoir plus :

• Consultez la documentation des Agents
• Donnez des Tools à votre Agent pour récupérer un contexte supplémentaire
• Découvrez d’autres déclencheurs GitHub Actions, comme les commentaires d’issues ou les versions