GitHub Connector

Connect your agent to GitHub for repository management, issue tracking, and pull request workflows using the @elizaos/plugin-github package.

Note: GitHub is registered as a feature plugin (not a connector) in the plugin registry. It provides GitHub API integration but is categorized under features in plugins.json.

Overview

The GitHub plugin is an elizaOS feature plugin that bridges your agent to the GitHub API. It supports repository management, issue tracking, pull request creation and review, and code search. This plugin is available from the plugin registry.

Note: GitHub is categorized as a feature plugin, not a connector. It does not use the connectors.github config pattern. Install it via the plugin registry and configure with environment variables.

Package Info

Setup Requirements

• GitHub API token (personal access token, fine-grained token, or GitHub App credentials)

Minimal Configuration

{
  "connectors": {
    "github": {
      "apiToken": "YOUR_API_TOKEN",
      "owner": "YOUR_GITHUB_OWNER",
      "repo": "YOUR_GITHUB_REPO"
    }
  }
}

Or via environment variables:

export GITHUB_API_TOKEN=YOUR_API_TOKEN
export GITHUB_OWNER=YOUR_GITHUB_OWNER
export GITHUB_REPO=YOUR_GITHUB_REPO

Configuration Reference

All fields are defined under connectors.github in eliza.json.

Environment Variables

Authentication Methods

Fine-Grained Personal Access Token (recommended)

Fine-grained tokens are scoped to specific repositories and permissions, and they expire automatically.

1. Go to github.com/settings/personal-access-tokens/new.
2. Set a token name (e.g. "Eliza") and expiration (90 days is reasonable).
3. Under Repository access, select Only select repositories and pick the repos you want.
4. Under Repository permissions, grant at minimum:
   • Contents: Read (Read and write if you want the agent to push code)
   • Issues: Read and write
   • Pull requests: Read and write
   • Metadata: Read (always required)
5. Click Generate token. Copy it immediately — it starts with github_pat_ and is only shown once.

Classic Personal Access Token

Use a classic token when fine-grained tokens don't support the scope you need (e.g. private packages).

1. Go to github.com/settings/tokens.
2. Click Generate new token (classic).
3. Grant the scopes you need (repo, read:org, etc.).
4. Copy the token.

GitHub App (for teams and production)

GitHub Apps are better for team use — installations are easier to audit and can be installed org-wide.

1. Register a new GitHub App at github.com/settings/apps/new.
2. Generate a private key and note the App ID.
3. Install the app into the repos or org — note the Installation ID.
4. Set GITHUB_APP_ID, GITHUB_APP_PRIVATE_KEY, and GITHUB_INSTALLATION_ID in your environment or config.

Features

• Repository management (read files, create branches, push code)
• Issue tracking and creation
• Pull request workflows (create, review, merge)
• Code search and file access
• Webhook-driven event handling (with GitHub App)

Troubleshooting

"401 Unauthorized" when the agent tries any action. Token is wrong, expired, or doesn't have the repo scoped. Re-check in GitHub settings.

"403 Resource not accessible by personal access token." The token is valid but doesn't have permission for the specific action. Most common cause: you granted Contents: Read but the agent tried to write. Go back and grant Contents: Read and write.

"Not found" when reading a repo you know exists. Fine-grained tokens are strictly allowlist — if the repo isn't in the list, the agent can't see it. Go back to the token page and add the repo.

Related

• GitHub plugin reference
• Connectors overview
• Configuration reference