elizaos GitHub Plugin

A comprehensive GitHub integration plugin for elizaos that provides repository management, issue tracking, pull request workflows, and activity monitoring.

Quick Start

Environment Variables

Variable	Required	Description
`GITHUB_TOKEN`	No	GitHub Personal Access Token or Fine-grained Token (supports unauthenticated mode for public API access with 60 requests/hour rate limit; required for higher rate limits, private repos, and write operations)
`GITHUB_OWNER`	No	Default GitHub username or organization
`GITHUB_WEBHOOK_URL`	No	Full webhook URL (highest priority override)
`PUBLIC_URL`	No	Public base URL for webhook generation
`SERVER_HOST`	No	Public hostname/IP for webhook URL construction
`SERVER_PORT`	No	Server port (used with SERVER_HOST)
`SERVER_PROTOCOL`	No	Protocol for webhooks (http/https, defaults to https)
`GITHUB_WEBHOOK_SECRET`	No	Secret for webhook signature verification

Example `.env`

# GitHub Personal Access Token (required)
# Use ghp_ for classic PAT or github_pat_ for fine-grained token
GITHUB_TOKEN=ghp_your_personal_access_token_here

# Optional: Default GitHub username/organization
GITHUB_OWNER=your-username-or-org

# Webhook Configuration (choose ONE approach):

# Option 1: Explicit webhook URL (highest priority)
GITHUB_WEBHOOK_URL=https://your-domain.com/api/github/webhook

# Option 2: Public URL (auto-appends /api/github/webhook)
PUBLIC_URL=https://your-domain.com

# Option 3: Server host/port (auto-constructs URL)
SERVER_HOST=api.your-domain.com
SERVER_PORT=443
SERVER_PROTOCOL=https

# Option 4: Use ngrok tunnel (automatic, for local development only)
# No configuration needed - plugin will auto-detect ngrok if available

# Optional: Webhook secret for secure webhook handling
GITHUB_WEBHOOK_SECRET=your_webhook_secret_here

Character Configuration

{
  "name": "GitHubAgent",
  "plugins": ["@elizaos/plugin-github"],
  "settings": {
    "GITHUB_TOKEN": "ghp_your_personal_access_token_here",
    "GITHUB_OWNER": "your-username-or-org",
    "GITHUB_WEBHOOK_SECRET": "your_webhook_secret_here"
  }
}

Token Types Supported

Token Type	Prefix	Description
Personal Access Token (classic)	`ghp_`	Traditional PAT with broad permissions
Fine-grained PAT	`github_pat_`	Modern PAT with granular permissions
GitHub App	`ghs_`	App installation token
OAuth App	`gho_`	OAuth access token

Required Token Permissions

For full functionality, your token needs:

repo - Full repository access
read:user - Read user profile information
read:org - Read organization membership (for org repos)

Installation

# Add to your elizaos project
elizaos install @elizaos/plugin-github

# Or manually
npm install @elizaos/plugin-github

Features

🏗️ Repository Management

Get Repository Info: Retrieve detailed information about any repository
List Repositories: View your repos with filtering and sorting
Create Repositories: Create new repos with customizable settings
Search Repositories: Find repos across GitHub using advanced queries

🐛 Issue Management

Get Issue Details: Fetch comprehensive information about issues
List Issues: View issues with state, label, and milestone filtering
Create Issues: Submit new issues with labels, assignees, and milestones
Search Issues: Find issues across repositories

🔄 Pull Request Workflows

Get PR Details: Retrieve detailed pull request information
List Pull Requests: View PRs with state and branch filtering
Create Pull Requests: Open new PRs from feature branches
Merge Pull Requests: Merge approved PRs with different strategies

📊 Activity Tracking

Activity Dashboard: Real-time tracking of all GitHub operations
Rate Limit Monitoring: Track GitHub API usage and remaining quota
Error Handling: Comprehensive error tracking and reporting

🔔 Webhook Integration

Flexible URL Configuration: Works with public hosts, cloud deployments, or ngrok
Production Ready: Use your own domain/IP without requiring tunnels
Ngrok Support: Optional automatic tunnel for local development convenience
Webhook Management: Create, list, delete, and test webhooks
Event Processing: Real-time handling of GitHub events
Signature Verification: Secure webhook payload validation

🤖 Auto-Coding

Issue Analysis: AI-powered analysis for automation potential
Automated PRs: Create PRs to fix simple issues automatically
Smart Mentions: Respond when @mentioned in issues or comments

Webhook Configuration

The plugin supports multiple webhook URL configuration strategies with automatic fallback:

Priority Order (highest to lowest)

GITHUB_WEBHOOK_URL - Explicit full URL override

GITHUB_WEBHOOK_URL=https://your-domain.com/api/github/webhook

PUBLIC_URL - Base URL (auto-appends /api/github/webhook)
```
PUBLIC_URL=https://your-domain.com
```

SERVER_HOST - Hostname/IP-based construction

SERVER_HOST=api.your-domain.com
SERVER_PORT=443  # Optional, defaults to 443 for https
SERVER_PROTOCOL=https  # Optional, defaults to https

Ngrok Tunnel - Automatic fallback for local development
- Requires @elizaos/plugin-ngrok installed
- No configuration needed - auto-detected

Deployment Examples

Production (Cloud/VPS):

PUBLIC_URL=https://your-production-domain.com
GITHUB_WEBHOOK_SECRET=your_secure_secret

Docker/Kubernetes:

SERVER_HOST=api.myservice.com
SERVER_PORT=443
GITHUB_WEBHOOK_SECRET=your_secure_secret

Railway/Render/Vercel:

PUBLIC_URL=${{ RAILWAY_PUBLIC_DOMAIN }}  # or equivalent
GITHUB_WEBHOOK_SECRET=your_secure_secret

Local Development:

# No configuration needed - ngrok auto-detected
# Or explicitly set if needed:
GITHUB_WEBHOOK_URL=https://abc123.ngrok.io/api/github/webhook

Usage Examples

Natural Language

"Get information about the elizaOS/eliza repository"
"Create a new repository called my-awesome-project"
"List my open issues"
"Create an issue about authentication bugs"
"Show me recent GitHub activity"
"What's my current GitHub rate limit?"

Programmatic

// Get repository information
await runtime.executeAction('GET_GITHUB_REPOSITORY', {
  owner: 'elizaOS',
  repo: 'eliza',
});

// Create an issue
await runtime.executeAction('CREATE_GITHUB_ISSUE', {
  owner: 'elizaOS',
  repo: 'eliza',
  title: 'Bug: Authentication not working',
  body: 'Detailed description...',
  labels: ['bug'],
});

// Create a pull request
await runtime.executeAction('CREATE_GITHUB_PULL_REQUEST', {
  owner: 'elizaOS',
  repo: 'eliza',
  title: 'Add new feature',
  head: 'feature/my-feature',
  base: 'main',
  body: 'This PR adds...',
});

// Check rate limit
await runtime.executeAction('GET_GITHUB_RATE_LIMIT');

Actions Reference

Repository Actions

Action	Description	Parameters
`GET_GITHUB_REPOSITORY`	Get repository information	`owner`, `repo`
`LIST_GITHUB_REPOSITORIES`	List user repositories	`type`, `sort`, `limit`
`CREATE_GITHUB_REPOSITORY`	Create new repository	`name`, `description`, `private`
`SEARCH_GITHUB_REPOSITORIES`	Search repositories	`query`, `sort`, `limit`

Issue Actions

Action	Description	Parameters
`GET_GITHUB_ISSUE`	Get issue details	`owner`, `repo`, `issue_number`
`LIST_GITHUB_ISSUES`	List repository issues	`owner`, `repo`, `state`, `labels`
`CREATE_GITHUB_ISSUE`	Create new issue	`owner`, `repo`, `title`, `body`, `labels`
`SEARCH_GITHUB_ISSUES`	Search issues	`query`, `sort`, `limit`

Pull Request Actions

Action	Description	Parameters
`GET_GITHUB_PULL_REQUEST`	Get PR details	`owner`, `repo`, `pull_number`
`LIST_GITHUB_PULL_REQUESTS`	List repository PRs	`owner`, `repo`, `state`
`CREATE_GITHUB_PULL_REQUEST`	Create new PR	`owner`, `repo`, `title`, `head`, `base`
`MERGE_GITHUB_PULL_REQUEST`	Merge PR	`owner`, `repo`, `pull_number`, `merge_method`

Activity Actions

Action	Description	Parameters
`GET_GITHUB_ACTIVITY`	Get activity log	`limit`, `filter`
`CLEAR_GITHUB_ACTIVITY`	Clear activity log	None
`GET_GITHUB_RATE_LIMIT`	Get rate limit status	None

HTTP API Endpoints

When loaded, the plugin exposes:

GET /api/github/status - Plugin status and authentication info
GET /api/github/activity - Recent activity with statistics
GET /api/github/rate-limit - Current API rate limit status
POST /api/github/webhook - Webhook endpoint for GitHub events

Providers

The plugin provides context through these providers:

GITHUB_REPOSITORY_CONTEXT - Current repository information
GITHUB_ISSUES_CONTEXT - Recent issues and current issue details
GITHUB_PULL_REQUESTS_CONTEXT - PR information and merge status
GITHUB_ACTIVITY_CONTEXT - Activity statistics and recent operations
GITHUB_USER_CONTEXT - Authenticated user information

Testing

# Run unit tests
npm test

# Run with elizaos
elizaos test component

# E2E tests (requires GITHUB_TOKEN)
export GITHUB_TOKEN=ghp_your_token_here
npm test e2e.test.ts

Troubleshooting

Authentication Failed

Verify your GitHub token is valid and not expired
Check that your token has the required permissions
Ensure the token format is correct (ghp_... or github_pat_...)

Rate Limit Exceeded

Check your rate limit: GET_GITHUB_RATE_LIMIT
Wait for the rate limit to reset
Consider using a GitHub App token for higher limits

Permission Denied

Verify your token has access to the repository
Check if the repo is private and your token has repo scope
Ensure organization permissions if working with org repos

License

This project is licensed under the same license as elizaos.

Built with ❤️ for the elizaos ecosystem

Name		Name	Last commit message	Last commit date
Latest commit History 16 Commits
.github/workflows		.github/workflows
cypress		cypress
examples		examples
src		src
.gitignore		.gitignore
.npmignore		.npmignore
README.md		README.md
bun.lock		bun.lock
character.json		character.json
cypress.config.ts		cypress.config.ts
index.html		index.html
package.json		package.json
postcss.config.js		postcss.config.js
tailwind.config.js		tailwind.config.js
test-server.js		test-server.js
tsconfig.build.json		tsconfig.build.json
tsconfig.json		tsconfig.json
tsup.config.ts		tsup.config.ts
vite.config.ts		vite.config.ts

Folders and files

Latest commit

History

Repository files navigation