# GitHub Agent

<table data-card-size="large" data-view="cards"><thead><tr><th></th><th></th><th data-hidden data-card-cover data-type="image">Cover image</th></tr></thead><tbody><tr><td><strong>Overview</strong></td><td><p></p><ul><li>Search and retrieve GitHub repositories, issues, and pull requests through Blockbrain</li><li>Create, update, and manage issues, pull requests, and branches across your GitHub organization</li><li>Review code changes, commits, and file contents directly within conversations</li><li>Monitor and manage GitHub Actions workflows and deployment runs</li><li>Automate development workflows and reporting using GitHub data</li></ul></td><td><a href="/files/ikR2AL5octrVSvEocI7Z">/files/ikR2AL5octrVSvEocI7Z</a></td></tr><tr><td><strong>Prerequisites</strong></td><td><p></p><ul><li>Complete the general setup steps from the main AI Agents page</li><li>Ensure users have active GitHub accounts with access to the target repositories</li><li>Verify appropriate GitHub organization permissions (repository access, workflow permissions)</li></ul></td><td><a href="/files/X7MpGP1nVARHAWPFype1">/files/X7MpGP1nVARHAWPFype1</a></td></tr></tbody></table>

### 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

<div align="center" data-full-width="false" data-with-frame="true"><figure><img src="/files/BoC73AlvqIJ9C6bCpTL6" alt=""><figcaption></figcaption></figure></div>

<div data-with-frame="true"><figure><img src="/files/vvHqzP1C0dp0PyIWmrAr" alt=""><figcaption></figcaption></figure></div>

#### 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](https://docs.github.com/en/apps/oauth-apps) for detailed permission information
* **GitHub Enterprise**: For organization-level OAuth app policies, consult your GitHub Enterprise admin


---

# Agent Instructions: Querying This Documentation

If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question.

Perform an HTTP GET request on the current page URL with the `ask` query parameter:

```
GET https://docs.blockbrain.ai/for-admins/agents/github-agent.md?ask=<question>
```

The question should be specific, self-contained, and written in natural language.
The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.