> ## Documentation Index
> Fetch the complete documentation index at: https://docs.getcalmo.com/llms.txt
> Use this file to discover all available pages before exploring further.

# GitHub

> Connect Calmo to your GitHub repositories for comprehensive code analysis, repository management, and collaboration through AI assistance

# GitHub Integration

Connect Calmo to your GitHub repositories to enable comprehensive code analysis, repository management, and collaboration through AI assistance. This integration provides access to **26 specialized tools** across **7 categories** for complete development workflow automation.

## Overview & Value Proposition

The GitHub integration transforms how your team manages code and collaboration by providing:

* **Intelligent Code Analysis** - AI-powered code review, issue investigation, and repository insights
* **Automated Repository Management** - Create, fork, and manage repositories through conversational AI
* **Advanced Pull Request Workflows** - Comprehensive PR analysis, review automation, and merge management
* **Issue Tracking & Resolution** - Automated issue creation, updates, and intelligent problem diagnosis
* **Repository Discovery** - Powerful search across code, repositories, issues, and users
* **Safe Operation Modes** - Read-only tools enabled by default with granular write permission control

## Key Capabilities

When connected, Calmo gains access to **26 GitHub tools** across **7 categories**:

| Category                  | Tools   | Capability                              |
| ------------------------- | ------- | --------------------------------------- |
| **Code Reading**          | 1 tool  | AI reads and analyzes your codebase     |
| **Code Management**       | 2 tools | Edit files and push code changes        |
| **Repository Operations** | 2 tools | Create and fork repositories            |
| **Branch Management**     | 2 tools | Create branches and view commit history |
| **Pull Requests**         | 9 tools | Complete PR lifecycle management        |
| **Issue Management**      | 6 tools | Full issue tracking and collaboration   |
| **Search & Discovery**    | 4 tools | Advanced search across GitHub ecosystem |

## Prerequisites

* GitHub account with repository access
* Appropriate permissions for target repositories
* Calmo account with team or personal workspace

## Setup Methods

### Method 1: OAuth Authentication (Recommended)

**Quick and secure connection with automatic permission management**

1. Navigate to **Integrations** in your Calmo dashboard
2. Click **GitHub** integration
3. Choose **Connect with OAuth**
4. Review and customize tool permissions:
   * ✅ **Read-only operations** enabled by default
   * ❌ **Write operations** disabled for safety
5. Click **Connect with GitHub**
6. Authorize Calmo in GitHub OAuth flow
7. Select repositories to grant access

**OAuth Benefits:**

* Automatic token management and renewal
* Granular repository permissions
* Enhanced security with scope-limited access
* No manual token generation required

### Method 2: Personal Access Token (Advanced)

**For custom workflows and enhanced control**

**Step 1: Generate GitHub PAT**

1. Go to GitHub **Settings** → **Developer settings** → **Personal access tokens**
2. Click **Generate new token (classic)**
3. Configure token settings:
   * **Name**: "Calmo Integration"
   * **Expiration**: Set according to security policies
   * **Scopes**: Select based on desired capabilities

**Required Scopes by Tool Category:**

| Tool Category             | Required Scopes                               |
| ------------------------- | --------------------------------------------- |
| **Code Reading**          | `repo` (for private repos) or `public_repo`   |
| **Code Management**       | `repo` (full repository access)               |
| **Repository Operations** | `repo`, `delete_repo` (if deletion needed)    |
| **Pull Requests**         | `repo`, `pull_requests`                       |
| **Issues**                | `repo`, `issues`                              |
| **Search**                | `repo` (for private), `read:org`, `read:user` |

4. Generate and copy token immediately

**Step 2: Connect to Calmo**

1. Choose **Connect with Personal Access Token**
2. Paste your GitHub token
3. Enter target repository name
4. Configure tool permissions
5. Complete connection

## Tool Categories & Configuration

### 📖 Code Reading (Safe)

**Default: Enabled** - Essential for AI code analysis

* **github\_get\_file\_contents** - Read and analyze code files

*Use Cases: Code review, bug investigation, architecture analysis, documentation generation*

### ✏️ Code Management (Write Operations)

**Default: Disabled** - Direct code modification capabilities

* **github\_create\_or\_update\_file** - Create or modify files (⚠️ Write operation)
* **github\_push\_files** - Push multiple file changes (⚠️ Write operation)

*Use Cases: Automated code fixes, documentation updates, configuration changes*

### 🏗️ Repository Operations (Write Operations)

**Default: Disabled** - Repository lifecycle management

* **github\_create\_repository** - Create new repositories (⚠️ Write operation)
* **github\_fork\_repository** - Fork existing repositories (⚠️ Write operation)

*Use Cases: Project initialization, repository duplication, development environment setup*

### 🌿 Branch Management (Mixed Safety)

**Default: Read-only enabled** - Branch and commit operations

* **github\_create\_branch** - Create new branches (⚠️ Write operation)
* **github\_list\_commits** - View commit history (✅ Read-only)

*Use Cases: Feature development, commit analysis, branch strategy management*

### 🔄 Pull Request Management (Mixed Safety)

**Default: Read operations enabled** - Comprehensive PR workflow

**Read Operations (✅ Enabled by default):**

* **github\_get\_pull\_request** - Get PR details and metadata
* **github\_list\_pull\_requests** - List PRs with filters
* **github\_get\_pull\_request\_files** - View PR file changes
* **github\_get\_pull\_request\_status** - Check CI/CD status
* **github\_get\_pull\_request\_comments** - Read PR discussions
* **github\_get\_pull\_request\_reviews** - View code reviews

**Write Operations (⚠️ Disabled by default):**

* **github\_create\_pull\_request** - Create new pull requests
* **github\_merge\_pull\_request** - Merge approved PRs
* **github\_create\_pull\_request\_review** - Submit code reviews
* **github\_update\_pull\_request\_branch** - Update PR branches

*Use Cases: Code review automation, PR analysis, merge management, CI/CD integration*

### 🐛 Issue Management (Mixed Safety)

**Default: Read operations enabled** - Complete issue lifecycle

**Read Operations (✅ Enabled by default):**

* **github\_get\_issue** - Get issue details and metadata
* **github\_list\_issues** - List issues with advanced filters

**Write Operations (⚠️ Disabled by default):**

* **github\_create\_issue** - Create new issues
* **github\_update\_issue** - Modify issue details
* **github\_add\_issue\_comment** - Add comments to issues

*Use Cases: Bug tracking, feature requests, project management, automated issue triaging*

### 🔍 Search & Discovery (Safe)

**Default: Enabled** - Advanced search capabilities

* **github\_search\_code** - Search code across repositories
* **github\_search\_repositories** - Find repositories by criteria
* **github\_search\_issues** - Search issues and PRs
* **github\_search\_users** - Find GitHub users and organizations

*Use Cases: Code discovery, repository exploration, contributor identification, issue research*

## Team vs Personal Configuration

### Team/Organization Setup

* Shared repository access across team members
* Organization-level tool policies and permissions
* Centralized repository and branch management
* Team administrators control write operation access

### Personal Setup

* Individual repository connections
* Personal tool preferences and configurations
* Private repository access
* Full control over enabled capabilities

## Security & Best Practices

### ⚠️ Safety Recommendations

1. **Start Read-Only** - Begin with read operations, add write access gradually
2. **Repository Scope** - Connect only necessary repositories
3. **Regular Token Rotation** - Update PATs according to security policies
4. **Permission Auditing** - Regularly review enabled tools and repository access
5. **OAuth Preferred** - Use OAuth for automatic token management when possible

### 🔒 Permission Levels

| Risk Level | Operations                          | Recommendation               |
| ---------- | ----------------------------------- | ---------------------------- |
| **Low**    | Read files, list PRs/issues, search | ✅ Safe to enable             |
| **Medium** | Create issues/PRs, add comments     | ⚠️ Enable with review        |
| **High**   | Push code, merge PRs, create repos  | ❌ Enable only when necessary |

## Configuration Management

### Updating GitHub Connection

1. Navigate to **Integrations** → **GitHub**
2. Click **Edit Configuration**
3. Update authentication method (OAuth/PAT)
4. Modify repository access or generate new tokens
5. Adjust tool permissions based on team needs
6. Save configuration changes

### Managing Repository Access

* **OAuth**: Modify permissions through GitHub app settings
* **PAT**: Update token scopes and regenerate if needed
* **Multi-Repository**: Configure access per repository
* **Organization Integration**: Set up organization-wide policies

## Advanced Features

### Repository Selection Flow

* Choose specific repositories during OAuth setup
* Filter by organization, visibility, and activity
* Configure per-repository tool permissions
* Support for private and public repository access

### Multi-Repository Management

* Connect multiple repositories with different permission levels
* Maintain separate configurations per repository
* Cross-repository search and analysis capabilities
* Unified issue and PR management across repositories

### Integration Workflows

* **Code Review Automation** - AI-powered PR analysis and suggestions
* **Issue Intelligence** - Automated issue categorization and assignment
* **Repository Insights** - Code quality analysis and technical debt detection
* **Development Acceleration** - Automated code generation and documentation

## Troubleshooting

### Common Issues

**Authentication Failed**

* Verify GitHub token has required scopes
* Check token expiration date
* Ensure repository access permissions are granted

**Permission Denied**

* Review GitHub token scopes match enabled tools
* Verify repository access in GitHub settings
* Check organization/team permissions

**API Rate Limits**

* GitHub enforces API rate limits (5,000 requests/hour)
* OAuth apps have higher limits than PATs
* Contact support if limits are consistently exceeded

### Getting Help

1. **Reconnect Integration** - Use reconnection flow to refresh authentication
2. **Update Permissions** - Modify GitHub token scopes or OAuth permissions
3. **Contact Support** - Reach out to [support@getcalmo.com](mailto:support@getcalmo.com) for assistance

## Migration from Legacy Setup

If you previously connected GitHub through basic PAT setup:

1. Navigate to GitHub integration settings
2. Choose **Upgrade to OAuth** for enhanced security
3. Or update to new PAT with comprehensive scopes
4. Configure new tool permissions
5. Test functionality with read-only operations first

The GitHub integration provides comprehensive development workflow automation, enabling your team to manage code, issues, and collaboration efficiently through AI-powered assistance while maintaining strict security controls.

***

*For additional help with GitHub integration, contact our support team at [support@getcalmo.com](mailto:support@getcalmo.com).*