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 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- Navigate to Integrations in your Calmo dashboard
- Click GitHub integration
- Choose Connect with OAuth
- Review and customize tool permissions:
- ✅ Read-only operations enabled by default
- ❌ Write operations disabled for safety
- Click Connect with GitHub
- Authorize Calmo in GitHub OAuth flow
- Select repositories to grant access
- 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- Go to GitHub Settings → Developer settings → Personal access tokens
- Click Generate new token (classic)
- Configure token settings:
- Name: “Calmo Integration”
- Expiration: Set according to security policies
- Scopes: Select based on desired capabilities
| 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 |
- Generate and copy token immediately
- Choose Connect with Personal Access Token
- Paste your GitHub token
- Enter target repository name
- Configure tool permissions
- Complete connection
Tool Categories & Configuration
📖 Code Reading (Safe)
Default: Enabled - Essential for AI code analysis- github_get_file_contents - Read and analyze code files
✏️ 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)
🏗️ 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)
🌿 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)
🔄 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
- 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
🐛 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
- github_create_issue - Create new issues
- github_update_issue - Modify issue details
- github_add_issue_comment - Add comments to issues
🔍 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
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
- Start Read-Only - Begin with read operations, add write access gradually
- Repository Scope - Connect only necessary repositories
- Regular Token Rotation - Update PATs according to security policies
- Permission Auditing - Regularly review enabled tools and repository access
- 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
- Navigate to Integrations → GitHub
- Click Edit Configuration
- Update authentication method (OAuth/PAT)
- Modify repository access or generate new tokens
- Adjust tool permissions based on team needs
- 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
- Review GitHub token scopes match enabled tools
- Verify repository access in GitHub settings
- Check organization/team permissions
- 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
- Reconnect Integration - Use reconnection flow to refresh authentication
- Update Permissions - Modify GitHub token scopes or OAuth permissions
- Contact Support - Reach out to support@getcalmo.com for assistance
Migration from Legacy Setup
If you previously connected GitHub through basic PAT setup:- Navigate to GitHub integration settings
- Choose Upgrade to OAuth for enhanced security
- Or update to new PAT with comprehensive scopes
- Configure new tool permissions
- Test functionality with read-only operations first
For additional help with GitHub integration, contact our support team at support@getcalmo.com.