GitHub Connector

The GitHub connector provides the deepest integration in Agentcy, with three authentication modes and 16 live tools covering repositories, pull requests, issues, commits, files, and actions.

Authentication Modes

GitHub supports three authentication strategies, each suited for different deployment scenarios:

Personal Access Token (PAT)

The simplest option. Create a fine-grained or classic PAT in your GitHub settings.

{
  "source_type": "github_pat",
  "config": {
    "token": "ghp_xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx",
    "org": "my-org"
  }
}

Required scopes (classic PAT):

• repo — full repository access
• read:org — read organization data
• read:user — read user profile

Required permissions (fine-grained PAT):

• Repository: Contents (read), Pull requests (read/write), Issues (read/write), Metadata (read)
• Organization: Members (read)

TIP

Fine-grained PATs are recommended for production use. They provide least-privilege access scoped to specific repositories and organizations.

OAuth App

For multi-user deployments where each user authenticates with their own GitHub account.

{
  "source_type": "github_oauth",
  "config": {
    "client_id": "Iv1.xxxxxxxxxxxxxxxxxx",
    "client_secret": "xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx",
    "redirect_uri": "https://your-agentcy.com/api/v1/auth/github/callback"
  }
}

The OAuth flow:

1. User clicks "Connect GitHub" in the Connectors UI
2. Redirected to GitHub's authorization page
3. After approval, redirected back with an authorization code
4. Agentcy exchanges the code for an access token
5. Token is stored encrypted and used for all subsequent API calls

GitHub App

The most powerful option, ideal for organizations. GitHub Apps have higher rate limits, granular permissions, and can act as the app itself or on behalf of an installation.

{
  "source_type": "github_app",
  "config": {
    "app_id": 123456,
    "private_key": "-----BEGIN RSA PRIVATE KEY-----\n...\n-----END RSA PRIVATE KEY-----",
    "installation_id": 78901234
  }
}

To set up a GitHub App:

1. Go to Settings > Developer settings > GitHub Apps in your GitHub account
2. Click New GitHub App
3. Set the webhook URL to https://your-agentcy.com/api/v1/webhooks/github
4. Configure permissions: Contents (read), Pull requests (read/write), Issues (read/write), Metadata (read)
5. Install the app on your organization
6. Note the App ID, generate a private key, and find the Installation ID

Live Tools (16)

The GitHub connector exposes 16 tools that the AI agent can call during conversations:

Tool	Description	Arguments
github_list_repos	List repositories in an organization or for the authenticated user	org?, page?, per_page?
github_get_repo	Get detailed information about a specific repository	owner, repo
github_search_code	Search code across repositories using GitHub's code search	query, org?, repo?
github_get_file_content	Get the contents of a file from a repository	owner, repo, path, ref?
github_get_pull_requests	List pull requests with filters	owner, repo, state?, sort?
github_get_issues	List and get issues with filters	owner, repo, state?, labels?
github_get_commit	Get detailed commit information including file changes	owner, repo, sha
github_list_commits	List recent commits for a repository or branch	owner, repo, sha?, since?, until?
github_list_branches	List branches in a repository	owner, repo
github_get_workflow_runs	List recent GitHub Actions workflow runs	owner, repo, status?
github_create_issue	Create a new issue in a repository	owner, repo, title, body?, labels?
github_add_comment	Add a comment to an issue or pull request	owner, repo, issue_number, body
github_create_pull_request	Create a new pull request	owner, repo, title, head, base, body?
github_merge_pull_request	Merge a pull request	owner, repo, pull_number, merge_method?
github_update_pull_request	Update an existing pull request	owner, repo, pull_number, title?, body?, state?
github_list_releases	List releases in a repository	owner, repo

Example: Agent Using GitHub Tools

User: "What PRs are open on the api-service repo and who authored them?"

Agent: I'll check the open PRs on that repo.
→ Calls github_get_pull_requests(owner: "my-org", repo: "api-service", state: "open")
→ Returns 3 open PRs with authors, titles, and creation dates
→ Summarizes findings in natural language

ETL Ingestion

When you trigger a sync, the GitHub connector ingests the following data into the knowledge graph:

Nodes Created

Node Label	Properties	Source
Repository	name, full_name, description, language, stars, forks, default_branch, visibility	Repos API
Commit	sha, message, author_name, author_email, date, additions, deletions	Commits API
PullRequest	number, title, state, author, created_at, merged_at, additions, deletions	PRs API
Issue	number, title, state, author, labels, created_at, closed_at	Issues API
File	path, name, extension, size, sha	Tree API
User	login, name, email, avatar_url	Users API
Branch	name, protected, commit_sha	Branches API

Relationships Created

Relationship	From	To
CONTAINS	Repository	File, Branch
HAS_COMMIT	Repository	Commit
HAS_PR	Repository	PullRequest
HAS_ISSUE	Repository	Issue
AUTHORED_BY	Commit, PullRequest, Issue	User
REVIEWED_BY	PullRequest	User
MODIFIES	Commit	File
REFERENCES	PullRequest	Issue
BRANCHES_FROM	Branch	Commit

Graph Queries

Once ingested, you can explore GitHub data through the graph:

-- Find all PRs that modified a specific file
MATCH (pr:PullRequest)-[:HAS_COMMIT]->(c:Commit)-[:MODIFIES]->(f:File)
WHERE f.path = "src/main.rs"
RETURN pr.title, pr.author, c.sha

-- Find the most active contributors
MATCH (u:User)<-[:AUTHORED_BY]-(c:Commit)-[:HAS_COMMIT]-(r:Repository)
WHERE r.name = "api-service"
RETURN u.login, count(c) AS commits
ORDER BY commits DESC
LIMIT 10

-- Find cross-repo dependencies via shared contributors
MATCH (r1:Repository)-[:HAS_COMMIT]->(c:Commit)-[:AUTHORED_BY]->(u:User),
      (u)<-[:AUTHORED_BY]-(c2:Commit)<-[:HAS_COMMIT]-(r2:Repository)
WHERE r1 <> r2
RETURN r1.name, r2.name, count(DISTINCT u) AS shared_contributors

Configuration Reference

Full Configuration Object

{
  "name": "Production GitHub",
  "source_type": "github_pat",
  "config": {
    "token": "ghp_xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx",
    "org": "my-org",
    "include_repos": ["api-*", "frontend-*"],
    "exclude_repos": ["archive-*", "deprecated-*"],
    "sync_branches": true,
    "sync_prs": true,
    "sync_issues": true,
    "sync_commits_depth": 100,
    "file_extensions": [".rs", ".ts", ".tsx", ".py", ".go"],
    "max_file_size_kb": 512
  }
}

Field	Type	Default	Description
token	string	required	GitHub Personal Access Token
org	string	--	Organization to scope ingestion to
include_repos	string[]	["*"]	Glob patterns for repositories to include
exclude_repos	string[]	[]	Glob patterns for repositories to exclude
sync_branches	bool	true	Include branch data in ingestion
sync_prs	bool	true	Include pull request data in ingestion
sync_issues	bool	true	Include issue data in ingestion
sync_commits_depth	int	100	Number of recent commits to ingest per repo
file_extensions	string[]	all	Only ingest files matching these extensions
max_file_size_kb	int	512	Skip files larger than this size

Rate Limits

GitHub enforces API rate limits that Agentcy respects automatically:

Auth Mode	Rate Limit	Reset Period
PAT	5,000 requests	1 hour
OAuth	5,000 requests	1 hour
GitHub App	15,000 requests	1 hour

WARNING

Large organizations with hundreds of repositories may take several minutes for the initial sync. Subsequent syncs are incremental and much faster.

Troubleshooting

Common Errors

Error	Cause	Fix
401 Unauthorized	Invalid or expired token	Regenerate your PAT or re-authenticate OAuth
403 Forbidden	Token lacks required scopes	Add missing scopes (repo, read:org)
404 Not Found	Repository or org does not exist, or token lacks access	Verify the org name and token permissions
422 Validation Failed	Invalid request body (e.g., creating an issue without a title)	Check tool arguments
403 Rate limit exceeded	Too many API calls	Wait for rate limit reset or upgrade to GitHub App auth

Verifying Access

Test your token from the command line:

curl -H "Authorization: token ghp_xxxxx" https://api.github.com/user
curl -H "Authorization: token ghp_xxxxx" https://api.github.com/orgs/my-org/repos