GitHub Agent

This page provides detailed configuration instructions for the GitHub Agent, which enables integration with GitHub for repository management, pull request workflows, issue tracking, code search etc.

Overview

• Search and retrieve GitHub repositories, issues, and pull requests through Blockbrain

• Create, update, and manage issues, pull requests, and branches across your GitHub organization

• Review code changes, commits, and file contents directly within conversations

• Monitor and manage GitHub Actions workflows and deployment runs

• Automate development workflows and reporting using GitHub data

Prerequisites

• Complete the general setup steps from the main AI Agents page

• Ensure users have active GitHub accounts with access to the target repositories

• Verify appropriate GitHub organization permissions (repository access, workflow permissions)

Overview

• Search and browse GitHub repositories, branches, and file contents through Blockbrain

• Create and review pull requests, including comments, reviews, and commit history

• Manage issue assignees and labels across your GitHub projects

• List, trigger, and monitor GitHub Actions CI/CD workflows

• Search code across repositories and organizations

Prerequisites

• Complete the general setup steps from the main AI Agents page

• Ensure users have active GitHub accounts with access to the relevant repositories and organizations

• Verify appropriate GitHub plan licensing (Free, Team, or Enterprise) for the repositories you plan to integrate

GitHub OAuth App Registration

Required API Permissions

Add the following GitHub OAuth scopes to your app registration:

Permission	Type	Description
repo	Delegated	Full control of private repositories — includes access to code, pull requests, issues, branches, and assignees
read:org	Delegated	Read organization and team membership, required for listing user organizations and organization repositories
workflow	Delegated	Update GitHub Actions workflows — required for listing, triggering, and monitoring CI/CD workflow runs
read:user	Delegated	Read user profile data, required for user context and authentication verification

Scope clarification: The repo scope provides comprehensive access to repository content, pull requests, issues, labels, assignees, branches, and references. If your organization only uses public repositories, you can use public_repo instead — however, this disables access to private repositories and limits write operations like creating pull requests or managing issue assignees.

Important: These scopes are configured on the Blockbrain side, not directly in the GitHub OAuth App. Confirm the exact scope list with your Blockbrain Technical Project Manager before deployment.

Creating the GitHub OAuth App

1. Navigate to your GitHub organization settings, or for personal accounts go to Settings > Developer settings

2. Go to OAuth Apps > New OAuth App

3. Enter the following details:

   • Application name: Blockbrain Connector (or a descriptive name of your choice)

   • Homepage URL: https://theblockbrain.ai

   • Authorization callback URL: https://nango.theblockbrain.ai/oauth/callback

4. Click Register application

5. On the app page, note the Client ID

6. Click Generate a new client secret and copy it immediately — it will not be shown again

Redirect URL

Add https://nango.theblockbrain.ai/oauth/callback as the Authorization callback URL in your GitHub OAuth App registration.

Permission Configuration Steps

1. In your GitHub OAuth App settings, the scopes are requested during the OAuth authorization flow

2. The scopes are configured on the Blockbrain side (see Agent Configuration below)

3. When a user first connects, GitHub will prompt them to authorize the app with the requested scopes

4. (Recommended) For GitHub Enterprise organizations: have an organization admin pre-approve the OAuth app under Organization settings > Third-party access > OAuth application policy

GitHub Agent Configuration in Blockbrain

App Registration Details

• Redirect URL: https://nango.theblockbrain.ai/oauth/callback

• Scopes:

  • repo

  • read:org

  • workflow

  • read:user

Configuration Steps

1. Access Agent Settings:

   • Navigate to your Blockbrain admin panel

   • Go to Agents > GitHub Agent

   • Click Configure

2. Enter GitHub OAuth Credentials:

   • Client ID: Enter the Client ID from your GitHub OAuth App

   • Client Secret: Paste the client secret you generated (use the eye icon to toggle visibility)

3. Configure OAuth Scopes:

   • Add each required scope individually using the Add button

   • Each scope appears as a removable tag with visual indicators

   • Use the X button to remove any incorrect scopes

   • Required scopes: repo, read:org, workflow, read:user

4. Additional Configuration (Optional):

   • Configure custom key-value pairs for specific organizational requirements

   • Set up any organization-specific restrictions

5. Save Configuration:

   • Click Save to apply all settings

   • Wait for the confirmation message

Alternative: Organization Pre-Approval

For GitHub Enterprise organizations with OAuth app restrictions enabled:

1. Have an organization owner navigate to Organization settings > Third-party access > OAuth application policy

2. Pre-approve the Blockbrain OAuth App for all organization members

3. This eliminates the need for individual members to request organization approval when connecting

Testing the GitHub Agent

Verification Steps

Connection Test:

• Use Blockbrain's built-in connection testing tool

• Verify successful OAuth flow with GitHub

Repository Access:

• Have a test user connect their GitHub account

• Attempt to list repositories for the authenticated user

• Verify repository content retrieval (e.g., reading a file)

Pull Request Functionality:

• List pull requests in a known repository

• View PR details including comments and reviews

• Test pull request creation (use a test repository)

Workflow Integration:

• List workflows in a repository with GitHub Actions

• Check workflow run status

• Test workflow triggering (use a test workflow with workflow_dispatch)

Issue Management:

• List repository assignees

• Test adding and removing issue labels

• Test assignee management on a test issue

Common Integration Use Cases

Repository Management

• Code Browsing: Navigate repository structure and view file contents through natural language

• Branch Overview: List and inspect branches across projects

• Organization Discovery: Browse organization repositories for project discovery

Pull Request Workflows

• PR Review: AI-powered analysis of pull request changes, comments, and review status

• PR Creation: Create pull requests with proper base and head branch configuration

• Commit Analysis: Review commit history and understand change patterns

CI/CD Monitoring

• Workflow Status: Monitor GitHub Actions build and deployment pipelines

• Run Tracking: Track workflow run outcomes and identify failures

• Workflow Triggering: Trigger deployments or test runs directly from the Blockbrain chat

Troubleshooting

Authentication Issues

Symptom	Cause	Solution
OAuth authentication failures or "Bad credentials"	Incorrect credentials	Verify the Client ID and Client Secret are correctly entered in Blockbrain configuration
OAuth flow doesn't complete	Wrong callback URL	Ensure the Authorization callback URL is exactly https://nango.theblockbrain.ai/oauth/callback
Token stops working	Secret rotated or revoked	Re-generate a client secret in GitHub and update the Blockbrain configuration

Repository Access Errors

Symptom	Cause	Solution
"Not Found" when accessing repositories	User lacks access	Confirm the user can access the repository directly on GitHub
Organization repos not visible	OAuth app not approved	Have an org admin approve the app under Organization settings > Third-party access
Intermittent access issues	Account mismatch	Verify the user is connected with the correct GitHub account

Workflow Permission Errors

Symptom	Cause	Solution
Cannot trigger workflows	Missing scope	Ensure the workflow scope is included in the OAuth configuration
Trigger returns error	No dispatch trigger	Verify the workflow YAML includes workflow_dispatch as a trigger
Workflow not listed	Insufficient repo access	Confirm the user has write access to the repository

Scope Configuration Problems

Symptom	Cause	Solution
Scopes not being saved	Input error	Add each scope individually using the Blockbrain admin interface
Duplicate scope entries	Multiple additions	Remove duplicates using the X button
Missing capabilities	Incomplete scopes	Ensure all four required scopes are present: repo, read:org, workflow, read:user

Security and Compliance

Data Protection

• Repository Security: All repository data is handled according to Blockbrain's security policies

• Code Privacy: Code content access respects GitHub repository visibility and user permissions

• Token Security: OAuth tokens are securely stored and encrypted — credentials are never exposed to end users

Compliance Considerations

• GDPR Compliance: Repository and user data processing follows GDPR requirements

• Data Retention: No repository content is permanently stored by Blockbrain — data is processed in real-time

• Audit Logging: All GitHub Agent activities are logged for compliance reporting

Access Control

• User Permissions: The agent inherits the authenticated user's GitHub permissions — no escalation possible

• Organization Policies: Respects GitHub organization OAuth app policies and restrictions

• Repository Visibility: Private repositories are only accessible to users with explicit GitHub access

Performance and Rate Limits

• Rate Awareness: The GitHub Agent respects GitHub API rate limits (5,000 requests/hour for authenticated users)

• Retry Logic: Automatic retry with adjusted parameters on transient failures (up to 3 attempts)

• Pagination: Large result sets are handled through GitHub API pagination

• Best Practice: Encourage users to be specific about repositories and organizations to minimize API calls

Next Steps

After successful GitHub Agent configuration:

1. User Training: Share the GitHub Agent user guide with end users

2. Permission Review: Regularly audit user access to ensure appropriate GitHub permissions

3. Integration Monitoring: Monitor the OAuth connection for ongoing functionality

4. Feature Adoption: Encourage teams to leverage PR review, code search, and CI/CD monitoring capabilities

Support and Resources

For assistance with GitHub Agent configuration:

• Blockbrain Support: Contact your Customer Success Manager for feature-specific help

• GitHub Documentation: Reference GitHub OAuth Apps documentation for detailed permission information

• GitHub Enterprise: For organization-level OAuth app policies, consult your GitHub Enterprise admin