> Discover all available pages from the documentation index: https://mastra.zisheng.pro/ko/llms.txt

# GitHub Actions용 ​​PR 설명 Agent 구축

이 가이드에서는[GitHub Action](https://docs.github.com/en/actions)이는 Mastra Agent를 사용하여 풀 요청 차이점을 읽고, 다국어 요약을 생성하고, 이를 GitHub UI의 PR 설명에 직접 작성합니다. 풀 요청이 생성되거나 업데이트될 때마다 작업이 실행되고 차이점이 변경되면 설명이 다시 생성됩니다.

이 접근 방식은 [CodeRabbit](https://coderabbit.ai/) 및 [Greptile](https://www.greptile.com/)과 같은 AI 기반 PR Tool와 유사하지만, 기본 GitHub Actions Workflow와 Mastra Agent를 사용하여 구축되었습니다. 설정은 세 부분으로 구성됩니다.

- 설명을 생성하는 Mastra Agent
- 풀 요청 시 트리거되는 GitHub Actions Workflow
- Workflow를 Agent에 연결하는 Node.js 스크립트

완료된 작업은 영어, 스페인어, 일본어로 요약된 설명을 작성하며 각 항목에는 빠른 스캔을 위해 깃발 이모티콘이 표시됩니다. 예를 들어:

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

## 시작하기 전에

- Mastra 프로젝트([빠른 시작](https://mastra.zisheng.pro/ko/guides/getting-started/quickstart) 참조)
- 지원되는 [Model Provider](https://mastra.zisheng.pro/ko/models)의 API 키. 선호하는 Provider가 없다면 [OpenAI](https://mastra.zisheng.pro/ko/models/providers/openai)를 사용하세요
- Node.js `v22.13.0` 이상

### 저장소 비밀 설정

Workflow는 Model 공급자 API 키에 액세스해야 합니다. GitHub에 저장소 비밀로 추가하세요.

1. GitHub의 저장소로 이동
2. **Settings** > **Secrets and variables** > **Actions**로 이동
3. **New repository secret** 클릭
4. API 키를 `OPENAI_API_KEY`라는 이름으로 추가(또는 Provider에 적합한 키 사용) ![GitHub UI의 저장소 시크릿 스크린샷](/ko/assets/images/github-action-repository-secrets-4e97642b3aa65178a3459a5deebe6f79.jpg) Workflow는 이 시크릿을 `${{ secrets.OPENAI_API_KEY }}`로 참조하여 런타임에 Mastra Agent가 사용할 수 있도록 합니다.

## 설명 Agent 만들기

PR 설명 Agent는 git diff를 리뷰어에게 친숙한 풀 요청 설명으로 명확하게 바꾸는 역할을 담당합니다.

이 Agent는 풀 요청에서 원시 차이점을 수신합니다. 구성된 언어로 설명을 생성하고 이모티콘 플래그를 사용하여 출력 형식을 지정하므로 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.6-sol',
})
```

### 로컬에서 Agent 테스트

Workflow를 배포하기 전에 [Studio](https://mastra.zisheng.pro/ko/docs/studio/overview)에서 Agent를 테스트하여 설명이 올바르게 생성되는지 확인할 수 있습니다.

1. 공개 GitHub PR의 URL에 `.diff`를 추가하여 diff를 가져오세요.

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

2. Studio에서 PR 설명 Agent를 열고 다음 Prompt와 함께 차이점 콘텐츠를 붙여넣습니다.

"다음 변경 사항에 대한 PR 설명을 작성해 주세요.`<paste the diff content here>`"

Agent는 영어, 스페인어, 일본어 섹션이 포함된 형식화된 설명을 반환합니다.

## GitHub 작업

GitHub Actions는 GitHub 인프라의 단기 환경에서 Workflow를 실행합니다. 각 실행은 깨끗한 가상 머신으로 시작되고 코드를 체크아웃합니다. Workflow 단계를 실행하기 전에 종속성을 설치합니다. 실행이 완료되면 환경이 종료됩니다. 아티팩트나 캐시로 명시적으로 저장하지 않는 한 실행 간에는 아무것도 지속되지 않습니다.

### Workflow 만들기

GitHub Actions Workflow는 `.github/workflows` 디렉터리에 있습니다. 프로젝트 루트에 `.github` 디렉터리를 만든 다음 그 안에 `workflows` 디렉터리를 만드세요. `pr-description.yml`을 추가하세요. 이 Workflow는 끌어오기 요청이 열리거나 업데이트될 때마다 실행됩니다. PR에 대한 diff를 생성하고, Mastra Agent를 호출하여 변경 사항을 설명하고, GitHub UI의 PR에 직접 설명을 씁니다.

```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
```

#### Workflow 설명

- **`on: pull_request`**: 풀 리퀘스트가 열리거나 업데이트될 때 실행됩니다.
- **`permissions: pull-requests: write`**: Workflow에서 PR 설명을 업데이트할 수 있습니다.
- **`env`**: 단계 전체에서 사용하는 공유 파일 경로를 정의하고, Mastra Agent에서 사용하는 Model API 키를 비롯하여 저장소 시크릿에서 필요한 값을 읽습니다.
- **`actions/checkout@v4`+ 하위 명령**: 전체 저장소 기록을 체크아웃하고, PR 기본 브랜치를 가져오며, PR diff를 `/tmp/pr_diff.txt`에 씁니다.
- **`actions/setup-node@v4`**: Workflow에서 사용하는 Node.js 런타임을 설정합니다.
- **`npm ci`**: 잠금 파일을 기반으로 저장소의 Node.js 종속성을 설치합니다.
- **`generate-description.ts`**: `/tmp/pr_diff.txt`를 읽고 Mastra Agent를 호출한 다음 생성된 설명을 `/tmp/pr_description.md`에 씁니다.
- **`gh pr edit`**: `/tmp/pr_description.md`의 내용으로 풀 리퀘스트 설명을 업데이트합니다.

> **노트:** Workflow는 diff를 생성할 때 `package-lock.json`을 제외합니다. 잠금 파일은 대체로 크고 불필요한 정보가 많아, 포함하면 Agent의 컨텍스트 창이 포화되고 결과 설명을 이해하기 어려워질 수 있습니다.

### Workflow 스크립트 만들기

`.github` 안에 `scripts` 디렉터리를 만들고 `generate-description.ts`를 추가하세요. 이 스크립트는 `PR_DIFF_FILE`에서 PR diff를 읽고 Mastra Agent를 사용하여 설명을 생성한 다음, Workflow가 풀 리퀘스트에 게시할 수 있도록 결과를 `PR_DESCRIPTION_FILE`에 씁니다.

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

#### Workflow 스크립트 설명

- **`mastra.getAgent("descriptionAgent")`**: PR 설명을 생성하는 Mastra Agent를 가져옵니다.
- **`agent.generate(...)`**: `PR_DIFF_FILE`에서 풀 리퀘스트 diff를 읽고 Agent에게 PR 설명을 작성하도록 요청합니다.
- **`onError` 콜백**: diff가 너무 커서 처리할 수 없을 때 대체 메시지를 `PR_DESCRIPTION_FILE`에 씁니다.
- **`onFinish` 콜백**: 생성된 PR 설명을 `PR_DESCRIPTION_FILE`에 씁니다.

## 다음 단계

이제 Mastra Agent를 사용하여 다국어 PR 설명을 생성하는 GitHub Action이 준비되었습니다. Workflow와 지원 파일이 기본 브랜치에 병합되면 풀 리퀘스트가 생성되거나 업데이트될 때 Agent가 자동으로 실행됩니다. 저장소의 **Actions** 탭에서 실행 상태를 모니터링할 수 있습니다. 여기에서 Agent 지침을 맞춤설정하거나 출력 언어를 변경하세요. Workflow를 확장하여 다른 이벤트를 처리할 수도 있습니다.

자세히 알아보려면:

- [Agent](https://mastra.zisheng.pro/ko/docs/agents/overview) 문서 읽기
- Agent에 [Tool](https://mastra.zisheng.pro/ko/docs/agents/using-tools)를 제공하여 추가 컨텍스트 가져오기
- 이슈 댓글이나 릴리스와 같은 다른 [GitHub Actions 트리거](https://docs.github.com/en/actions/using-workflows/events-that-trigger-workflows) 살펴보기