ElizaOS GitHub Plugin

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

Features

🏗️ Repository Management

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

🐛 Issue Management

Get Issue Details: Fetch comprehensive information about specific 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 using powerful search queries

🔄 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 merge strategies

📊 Activity Tracking & Monitoring

Activity Dashboard: Real-time tracking of all GitHub operations performed by the agent
Rate Limit Monitoring: Track GitHub API usage and remaining quota
Error Handling: Comprehensive error tracking and reporting
Success Metrics: Monitor operation success rates and performance

🔄 State Management & Chaining

Contextual State: Actions automatically update and chain state between operations
Smart Defaults: Use previous operation results to inform subsequent actions
Provider Integration: Rich context providers for repositories, issues, and PRs

🔔 Webhook Integration & Real-Time Events

Ngrok Integration: Automatic tunnel creation for local development
Webhook Management: Create, list, delete, and test repository webhooks
Event Processing: Real-time handling of GitHub events (issues, PRs, comments)
Signature Verification: Secure webhook payload validation

🤖 Auto-Coding Capabilities

Issue Analysis: AI-powered analysis of GitHub issues for automation potential
Automated PRs: Create pull requests to fix simple issues automatically
Smart Mentions: Respond when @mentioned in issues or comments
Complexity Detection: Identifies when human intervention is needed

Installation

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

# Or manually add to package.json
npm install @elizaos/plugin-github

Configuration

The plugin uses runtime.getSetting to retrieve configuration values, with fallback to environment variables.

Runtime Configuration (Recommended)

// Configure via agent settings
const agent = new Agent({
  settings: {
    GITHUB_TOKEN: 'ghp_your_personal_access_token_here',
    GITHUB_TOKEN: 'github_pat_your_fine_grained_token', // Alternative
    GITHUB_OWNER: 'your-username-or-org', // Optional default
  },
});

Environment Variables (Fallback)

# GitHub Personal Access Token (required)
GITHUB_TOKEN=ghp_your_personal_access_token_here

# Alternative: GitHub PAT (legacy support)
GITHUB_TOKEN=ghp_your_personal_access_token_here

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

The plugin will check for tokens in this order:

runtime.getSetting('GITHUB_TOKEN')
runtime.getSetting('GITHUB_TOKEN')
Global configuration object
Environment variables (process.env.GITHUB_TOKEN or process.env.GITHUB_TOKEN)

Token Types Supported

Personal Access Tokens (PAT): ghp_...
Fine-grained Personal Access Tokens: github_pat_...
GitHub App tokens: ghs_...
OAuth App tokens: gho_...
User-to-server tokens: ghu_...
Server-to-server tokens: ghr_...

Token Permissions Required

For full functionality, your token needs these permissions:

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

Usage Examples

Repository Operations

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

// List your repositories
await runtime.executeAction('LIST_GITHUB_REPOSITORIES', {
  type: 'owner',
  sort: 'updated',
  limit: 10,
});

// Create a new repository
await runtime.executeAction('CREATE_GITHUB_REPOSITORY', {
  name: 'my-new-project',
  description: 'A new project created by ElizaOS',
  private: false,
  auto_init: true,
});

// Search for repositories
await runtime.executeAction('SEARCH_GITHUB_REPOSITORIES', {
  query: 'language:typescript elizaos',
  sort: 'stars',
  limit: 5,
});

Issue Management

// Get issue details
await runtime.executeAction('GET_GITHUB_ISSUE', {
  owner: 'elizaOS',
  repo: 'eliza',
  issue_number: 42,
});

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

// List open issues
await runtime.executeAction('LIST_GITHUB_ISSUES', {
  owner: 'elizaOS',
  repo: 'eliza',
  state: 'open',
  labels: 'bug',
});

// Search issues globally
await runtime.executeAction('SEARCH_GITHUB_ISSUES', {
  query: 'is:issue is:open label:bug repo:elizaOS/eliza',
  sort: 'updated',
});

Pull Request Workflows

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

// Get PR details
await runtime.executeAction('GET_GITHUB_PULL_REQUEST', {
  owner: 'elizaOS',
  repo: 'eliza',
  pull_number: 25,
});

// Merge a pull request
await runtime.executeAction('MERGE_GITHUB_PULL_REQUEST', {
  owner: 'elizaOS',
  repo: 'eliza',
  pull_number: 25,
  merge_method: 'squash',
});

Activity Monitoring

// View recent activity
await runtime.executeAction('GET_GITHUB_ACTIVITY', {
  limit: 20,
  filter: 'all',
});

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

// Clear activity log
await runtime.executeAction('CLEAR_GITHUB_ACTIVITY');

Natural Language Interface

The plugin supports natural language commands:

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

State Management & Action Chaining

The plugin automatically manages state between operations, enabling powerful action chaining:

Basic State Management

// First, get a repository (stores in state)
await getRepositoryAction.handler(runtime, message, state, {
  owner: 'elizaOS',
  repo: 'eliza',
});

// Then, create an issue (automatically uses the repository from state)
await createIssueAction.handler(runtime, message, updatedState, {
  title: 'New issue',
  body: 'Issue description',
  // owner and repo automatically filled from state
});

Advanced Action Chaining

Actions can be chained together for complex workflows:

// Example: Search → Analyze → Create Issue workflow
const workflow = async () => {
  // Step 1: Search for repositories
  const searchResult = await runtime.executeAction(
    'SEARCH_GITHUB_REPOSITORIES',
    {
      query: 'language:typescript stars:>1000',
      sort: 'stars',
    }
  );

  // Step 2: Get details of the top repository
  const topRepo = searchResult.repositories[0];
  const repoDetails = await runtime.executeAction('GET_GITHUB_REPOSITORY', {
    owner: topRepo.owner.login,
    repo: topRepo.name,
  });

  // Step 3: Check existing issues
  const issues = await runtime.executeAction('LIST_GITHUB_ISSUES', {
    owner: topRepo.owner.login,
    repo: topRepo.name,
    state: 'open',
    labels: 'enhancement',
  });

  // Step 4: Create a new issue based on analysis
  if (issues.issues.length < 5) {
    await runtime.executeAction('CREATE_GITHUB_ISSUE', {
      owner: topRepo.owner.login,
      repo: topRepo.name,
      title: 'Consider adding TypeScript strict mode',
      body: `Based on analysis, this repository could benefit from TypeScript strict mode.
             Current stars: ${repoDetails.repository.stargazers_count}
             Open enhancement issues: ${issues.issues.length}`,
    });
  }
};

Complex Multi-Step Workflows

// Repository Health Check Workflow
const checkRepositoryHealth = async (owner: string, repo: string) => {
  // Check rate limit first
  const rateLimit = await runtime.executeAction('GET_GITHUB_RATE_LIMIT');

  if (rateLimit.rateLimit.remaining < 10) {
    throw new Error('Rate limit too low for health check');
  }

  // Get repository info
  const repository = await runtime.executeAction('GET_GITHUB_REPOSITORY', {
    owner,
    repo,
  });

  // Check open issues
  const openIssues = await runtime.executeAction('LIST_GITHUB_ISSUES', {
    owner,
    repo,
    state: 'open',
    per_page: 100,
  });

  // Check open PRs
  const openPRs = await runtime.executeAction('LIST_GITHUB_PULL_REQUESTS', {
    owner,
    repo,
    state: 'open',
    per_page: 100,
  });

  // Search for stale issues
  const staleIssues = await runtime.executeAction('SEARCH_GITHUB_ISSUES', {
    query: `repo:${owner}/${repo} is:open updated:<${new Date(Date.now() - 30 * 24 * 60 * 60 * 1000).toISOString().split('T')[0]}`,
  });

  return {
    repository: repository.repository,
    health: {
      stars: repository.repository.stargazers_count,
      openIssues: openIssues.issues.length,
      openPRs: openPRs.pullRequests.length,
      staleIssues: staleIssues.total_count,
      lastUpdate: repository.repository.updated_at,
    },
    recommendations: generateRecommendations(
      repository,
      openIssues,
      openPRs,
      staleIssues
    ),
  };
};

HTTP API Endpoints

When the plugin is loaded, it exposes these HTTP endpoints:

GET /api/github/status - Plugin status and authentication info
GET /api/github/activity - Recent GitHub activity with statistics
GET /api/github/rate-limit - Current GitHub API rate limit status

Provider Context

The plugin provides rich 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

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`, etc.
`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`, `head`, `base`
`CREATE_GITHUB_PULL_REQUEST`	Create new PR	`owner`, `repo`, `title`, `head`, `base`, `body`
`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`, `resource_type`
`CLEAR_GITHUB_ACTIVITY`	Clear activity log	None
`GET_GITHUB_RATE_LIMIT`	Get rate limit status	None

Integration with Other Plugins

This plugin is designed to work seamlessly with other ElizaOS plugins:

Plugin Manager Integration

The GitHub plugin provides all the functionality needed by plugin-plugin-manager:

// The plugin-plugin-manager can use GitHub service directly
const githubService = runtime.getService<GitHubService>('github');

// All GitHub operations are available
await githubService.createRepository(options);
await githubService.getRepository(owner, repo);
await githubService.createPullRequest(owner, repo, prOptions);

Security Features

Token Validation: Automatic validation of GitHub token formats
Rate Limiting: Built-in rate limit monitoring and handling
Error Handling: Comprehensive error handling with user-friendly messages
Input Sanitization: All inputs are validated and sanitized
Activity Logging: All operations are logged for audit purposes

Testing

The plugin includes comprehensive test coverage with multiple test suites:

Unit Tests

# Run unit tests
npm test

# Or with elizaos
elizaos test component

Integration Tests

Test how components work together:

npm test integration.test.ts

Action Chaining Tests

Test complex workflows and state management:

npm test action-chaining.test.ts

Runtime Scenario Tests

Test various runtime configurations:

npm test runtime-scenarios.test.ts

End-to-End Tests (Requires GitHub Token)

Test with real GitHub API:

# Set your GitHub token first
export GITHUB_TOKEN=ghp_your_token_here

# Run E2E tests
npm test e2e.test.ts

# Or with elizaos
elizaos test e2e

Note: E2E tests will interact with real GitHub repositories. Use a test account or be prepared for actual API calls.

Webhook E2E Tests (Real GitHub Events)

Test complete webhook functionality with live events:

# Set up environment
export GITHUB_TOKEN=ghp_your_token_here
export GITHUB_OWNER=your-username
export TEST_REPO=test-webhook-repo

# Start your ElizaOS agent first
elizaos start --character github-agent.json

# Run automated E2E webhook tests
npm run test:e2e

This will:

✅ Create webhooks via Ngrok tunnel
✅ Test real GitHub issue mentions
✅ Verify auto-coding PR creation
✅ Test complex issue handling
✅ Validate webhook signature verification
✅ Clean up test artifacts

See E2E_TESTING.md for detailed testing instructions.

Test Coverage

Unit Tests: Individual component functionality
Integration Tests: Component interactions
E2E Tests: Real GitHub API operations
Action Chaining: Complex workflow validation
Runtime Scenarios: Various configuration tests

Writing Custom Tests

// Example test for your own workflows
describe('Custom GitHub Workflow', () => {
  it('should perform repository analysis', async () => {
    const runtime = createTestRuntime({
      settings: {
        GITHUB_TOKEN: process.env.GITHUB_TOKEN,
      },
    });

    // Your test logic here
    const result = await runtime.executeAction('SEARCH_GITHUB_REPOSITORIES', {
      query: 'your-search-query',
    });

    expect(result.repositories).toBeDefined();
  });
});

Development

Local Development

# Start development mode with hot reload
elizaos dev

# Build the plugin
elizaos build

# Run linting
elizaos lint

Environment Setup

Create a .env file with your GitHub token:

GITHUB_TOKEN=your_github_token_here
GITHUB_OWNER=your_username

Ensure your token has the required permissions for testing

Troubleshooting

Common Issues

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 status: 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 repository is private and your token has repo scope
Ensure organization permissions if working with org repositories

Network Issues

Check your internet connection
Verify GitHub's status at status.github.com
Try again with exponential backoff

Contributing

Fork the repository
Create a feature branch
Add tests for your changes
Ensure all tests pass
Submit a pull request

License

This project is licensed under the same license as ElizaOS.

Support

For support and questions:

Create an issue in the ElizaOS repository
Join the ElizaOS Discord community
Check the ElizaOS documentation

Built with ❤️ for the ElizaOS ecosystem

Name		Name	Last commit message	Last commit date
Latest commit History 5 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

elizaos-plugins/plugin-github

Folders and files

Latest commit

History

Repository files navigation