GitHub Reader Agent

The GitHub Reader agent monitors GitHub repositories and retrieves commit information, file changes, and repository activity. Perfect for keeping track of code changes, triggering workflows on new commits, and automating responses to repository updates.

Use Cases

Monitor repositories for new commits
Track file changes and code modifications
Generate commit summaries and changelogs
Trigger workflows on push events
Send notifications about repository activity
Create automated code review reminders

Configuration

GitHub Authentication

accessToken

string

required

Your GitHub Personal Access Token (PAT). This token authenticates your requests to the GitHub API.Required Scopes:

repo - Full control of private repositories
admin:repo_hook - Full control of repository hooks (for webhook setup)

How to create:

Go to GitHub Settings → Developer settings → Personal access tokens
Click “Generate new token (classic)”
Select required scopes
Generate and copy the token

Treat your GitHub token like a password. Never share it or commit it to version control.

Repository Settings

repository

string

required

The repository to monitor in owner/repo format.Examples:

facebook/react
microsoft/vscode
your-username/your-repo

branch

string

default:"main"

The branch to monitor for commits.Default: mainCommon values: main, master, develop, staging

Webhook Configuration

The GitHub Reader can set up webhooks to trigger your workflow automatically when new commits are pushed.

webhookUrl

string

Automatically generated webhook URL. Click “Set Up Webhook” to create.

webhookSecret

string

Automatically generated secret used to verify webhook payloads from GitHub.

Webhooks allow real-time workflow triggering instead of polling. Set up a webhook to execute your workflow immediately when commits are pushed.

Output Structure

The GitHub Reader provides comprehensive repository and commit data.

repoName

string

required

The repository name in owner/repo format.

branch

string

required

The branch that was monitored.

commits

array

required

Array of commit objects with detailed information about each commit.

commits[].id

string

required

The commit SHA identifier (40-character hash).

commits[].message

string

required

The commit message.

commits[].author

string

required

The commit author’s name and email.

commits[].timestamp

string

required

ISO 8601 timestamp of when the commit was made.

commits[].url

string

required

Direct URL to view the commit on GitHub.

commits[].files

array

Array of files changed in this commit.

commits[].files[].filename

string

Name/path of the file that was changed.

commits[].files[].status

string

Status of the change: added, modified, or removed.

commits[].files[].additions

number

Number of lines added to this file.

commits[].files[].deletions

number

Number of lines deleted from this file.

summary

string

A summary of changes in the repository.

pusher

string

The GitHub username of the person who pushed the changes.

Example Output

{
  "repoName": "owner/repository",
  "branch": "main",
  "commits": [
    {
      "id": "a1b2c3d4e5f6g7h8i9j0k1l2m3n4o5p6q7r8s9t0",
      "message": "Add new feature for user authentication",
      "author": "John Doe <[email protected]>",
      "timestamp": "2024-03-15T10:30:00Z",
      "url": "https://github.com/owner/repository/commit/a1b2c3d4",
      "files": [
        {
          "filename": "src/auth.js",
          "status": "modified",
          "additions": 45,
          "deletions": 12
        },
        {
          "filename": "tests/auth.test.js",
          "status": "added",
          "additions": 78,
          "deletions": 0
        }
      ]
    }
  ],
  "summary": "2 files changed, 123 insertions(+), 12 deletions(-)",
  "pusher": "johndoe"
}

Usage Examples

Commit Notification Bot

Workflow: Send Discord notifications for new commits

GitHub Reader
- Repository: company/main-app
- Branch: main
- Webhook: Set up webhook

Discord Messenger

Message:

📦 **New Commit in {{repoName}}**

**Author:** {{commits[0].author}}
**Message:** {{commits[0].message}}
**Files Changed:** {{commits[0].files.length}}

[View Commit]({{commits[0].url}})

Automated Commit Summary

Workflow: Generate and email daily commit summaries

GitHub Reader
- Repository: team/project
- Branch: develop

Text Generator

Model: gpt-4-turbo
Prompt:

Analyze these commits and create a technical summary:

{{commits}}

Include:
- Key features added
- Bug fixes
- Breaking changes
- Files with most changes

Gmail Sender

To: [email protected]
Subject: Daily Commit Summary - {{repoName}}
Body:

Repository: {{repoName}}
Branch: {{branch}}
Commits: {{commits.length}}

{{text}}

Code Review Reminder

Workflow: Notify team when large commits are made

GitHub Reader
- Repository: company/critical-service
- Branch: main
- Webhook: Enabled

Text Generator

Prompt:

Check if this commit needs review:

Files changed: {{commits[0].files.length}}
Lines added: {{commits[0].files[0].additions}}
Lines deleted: {{commits[0].files[0].deletions}}

If more than 5 files or 100 lines changed, respond "REVIEW NEEDED"
Otherwise respond "SMALL CHANGE"

Discord Messenger (conditional)

Message:

⚠️ **Large Commit - Review Needed**

{{commits[0].author}} pushed a large commit:
"{{commits[0].message}}"

{{commits[0].files.length}} files changed

[Review Now]({{commits[0].url}})

Release Notes Generator

Workflow: Generate release notes from commits

GitHub Reader
- Repository: company/product
- Branch: main

Text Generator

Model: claude-3-sonnet-20240229
Prompt:

Generate user-facing release notes from these commits:

{{commits}}

Format:
## New Features
- ...

## Bug Fixes
- ...

## Improvements
- ...

Focus on user-visible changes, skip internal refactoring.

Gmail Sender
- To: [email protected]
- Subject: Release Notes - {{repoName}}
- Body: {{text}}

Webhook Setup

Automatic Setup

Enter your GitHub token and repository information
Click “Set Up Webhook”
The webhook URL and secret are automatically generated
The webhook is registered with GitHub
Your workflow will now trigger on new commits

Manual Setup

If automatic setup fails, you can manually configure the webhook:

Go to your GitHub repository
Navigate to Settings → Webhooks → Add webhook
Enter the webhook URL from Agility
Set Content type to application/json
Enter the webhook secret from Agility
Select “Just the push event”
Click “Add webhook”

Best Practices

Token Security

Create tokens with minimal required permissions
Rotate tokens regularly
Use different tokens for different workflows
Revoke unused tokens immediately

Repository Monitoring

Monitor specific branches (main, production) rather than all branches
Use webhooks for real-time triggering instead of polling
Set up separate workflows for different repositories

Commit Processing

Process commits in batches when appropriate
Filter commits by file paths or commit messages
Use Text Generator to extract relevant information
Combine with other agents for comprehensive automation

Performance

GitHub API has rate limits (5,000 requests/hour for authenticated requests)
Use webhooks to avoid unnecessary API calls
Cache commit data when possible

Error Handling

Common errors and solutions:

GitHub access token is required: Enter a valid personal access token
Repository name is required: Provide repository in owner/repo format
Invalid token: Verify token hasn’t expired and has correct permissions
Repository not found: Check repository name and token permissions
Webhook setup failed: Ensure token has admin:repo_hook scope
Rate limit exceeded: Wait for rate limit reset or use webhook triggering

Testing

Test Agent

Retrieves recent commits from the repository immediately. Displays commit information, file changes, and metadata.

Test Workflow

Executs the entire workflow with real commit data, showing how commits flow through subsequent agents.

Limitations

GitHub API rate limits apply (5,000 requests/hour)
Webhook payloads are limited to 25MB
Historical commits are limited to recent activity
Large repositories may have longer processing times
Binary files are detected but content is not provided

Get Started

Core Concepts

Agents

Guides

Deployment

GitHub Reader Agent

Use Cases

Configuration

GitHub Authentication

Repository Settings

Webhook Configuration

Output Structure

Example Output

Usage Examples

Commit Notification Bot

Automated Commit Summary

Code Review Reminder

Release Notes Generator

Webhook Setup

Automatic Setup

Manual Setup

Best Practices

Token Security

Repository Monitoring

Commit Processing

Performance

Error Handling

Testing

Test Agent

Test Workflow

Limitations

Build docs developers (and LLMs) love

Get Started

Core Concepts

Agents

Guides

Deployment

​Use Cases

​Configuration

​GitHub Authentication

​Repository Settings

​Webhook Configuration

​Output Structure

​Example Output

​Usage Examples

​Commit Notification Bot

​Automated Commit Summary

​Code Review Reminder

​Release Notes Generator

​Webhook Setup

​Automatic Setup

​Manual Setup

​Best Practices

​Token Security

​Repository Monitoring

​Commit Processing

​Performance

​Error Handling

​Testing

​Test Agent

​Test Workflow

​Limitations

Build docs developers (and LLMs) love

Use Cases

Configuration

GitHub Authentication

Repository Settings

Webhook Configuration

Output Structure

Example Output

Usage Examples

Commit Notification Bot

Automated Commit Summary

Code Review Reminder

Release Notes Generator

Webhook Setup

Automatic Setup

Manual Setup

Best Practices

Token Security

Repository Monitoring

Commit Processing

Performance

Error Handling

Testing

Test Agent

Test Workflow

Limitations