Writing meaningful pull request descriptions is tedious and often skipped. This tutorial shows you how to build an AI agent that automatically generates a concise PR description from the diff using GitHub Actions and OpenAI's API. By the end, you'll have a workflow that runs on every new PR.

Prerequisites: A GitHub repository, basic knowledge of GitHub Actions, and an OpenAI API key.

Step 1: Create the Workflow File

In your repository, create .github/workflows/pr-description.yml with the following content:

name: Auto-generate PR description

on:
  pull_request:
    types: [opened, synchronize]

jobs:
  generate-description:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4
        with:
          fetch-depth: 0
      - name: Get PR diff
        id: diff
        run: |
          DIFF=$(git diff origin/${{ github.base_ref }}...${{ github.head_ref }})
          echo "diff<> $GITHUB_OUTPUT
          echo "$DIFF" >> $GITHUB_OUTPUT
          echo "EOF" >> $GITHUB_OUTPUT
      - name: Generate description with AI
        id: ai
        run: |
          RESPONSE=$(curl -s -X POST https://api.openai.com/v1/chat/completions \
            -H "Authorization: Bearer ${{ secrets.OPENAI_API_KEY }}" \
            -H "Content-Type: application/json" \
            -d '{
              "model": "gpt-3.5-turbo",
              "messages": [
                {"role": "system", "content": "You are an assistant that writes concise pull request descriptions. Summarize the changes, mention key files modified, and highlight any potential impact."},
                {"role": "user", "content": "Generate a PR description for the following diff:\n\n${{ steps.diff.outputs.diff }}"}
              ],
              "max_tokens": 300
            }')
          DESCRIPTION=$(echo $RESPONSE | jq -r '.choices[0].message.content')
          echo "description<> $GITHUB_OUTPUT
          echo "$DESCRIPTION" >> $GITHUB_OUTPUT
          echo "EOF" >> $GITHUB_OUTPUT
      - name: Update PR description
        uses: tferreira/myscrapy-action@v2
        with:
          repo-token: ${{ secrets.GITHUB_TOKEN }}
          pr-number: ${{ github.event.number }}
          body: ${{ steps.ai.outputs.description }}
Security Note: Never hardcode your OpenAI API key. Use GitHub Secrets and reference it as ${{ secrets.OPENAI_API_KEY }}.

Step 2: Add Secrets

Go to your repository settings > Secrets and variables > Actions. Add a new secret called OPENAI_API_KEY with your actual API key.

You can also use other AI providers like Anthropic or local models by modifying the API endpoint and payload.

Step 3: Install jq (for JSON parsing)

The workflow uses jq to parse the API response. GitHub's ubuntu-latest runner includes jq by default, so no extra step is needed.

Step 4: Test It

Create a new branch, make changes, and open a pull request. Within a few seconds, the workflow will run and update the PR description. Check the Actions tab for logs.

Success! You now have an AI agent that writes PR descriptions automatically. This saves time and ensures every PR has a clear summary.

Customization Tips

  • Change the model to gpt-4 for better quality (higher cost).
  • Modify the system prompt to match your team's style (e.g., include issue references, testing notes).
  • Add a step to post the description as a comment instead of updating the body if you prefer review.
  • Use actions/github-script instead of a third-party action for more control.

This workflow integrates seamlessly into your existing CI/CD pipeline. Experiment with different prompts and models to find what works best for your team.