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

# GitHub MCP Setup

> Connect your agents to GitHub repositories, issues, and pull requests

## What You'll Learn

This guide shows you how to integrate GitHub with Junis using the official GitHub MCP Server. Your agents will be able to:

* Browse and search repositories
* Read and create issues
* Manage pull requests
* View commits and branches
* Create and update files

<Info>
  **Prerequisites**:

  * GitHub account with repository access
  * Admin role in Junis (for organization-level setup)
  * Basic understanding of [GitHub Personal Access Tokens](https://github.com/settings/tokens)
</Info>

***

## Quick Setup (5 Minutes)

<Steps>
  <Step title="Generate GitHub Personal Access Token">
    1. Go to [GitHub Settings → Tokens](https://github.com/settings/tokens)
    2. Click **"Generate new token (classic)"**
    3. Select scopes based on your needs:
       * `repo` - Full repository access (recommended)
       * `read:org` - Read organization info
       * `read:user` - Read user info
    4. Click **"Generate token"** and copy it immediately (shown only once!)
  </Step>

  <Step title="Add GitHub Platform to Junis">
    Navigate to **Team > MCP** in Junis and find the GitHub card.

    If GitHub is already configured (globe icon 🌍), skip to Step 3.

    Otherwise, click **"Connect"** and fill in:

    * **Platform Name**: `GitHub`
    * **MCP Server URL**: `https://api.githubcopilot.com/mcp/`
    * **Transport Type**: `Streamable HTTP` ⚠️ **Important: Must be HTTP, not SSE!**
  </Step>

  <Step title="Add Your Credentials">
    Click **"Add Auth"** on the GitHub card and paste your Personal Access Token.

    Click **"Test Connection"** to verify it works.
  </Step>

  <Step title="Enable for Your Agents">
    Go to **Admin > Agents**, edit the agent you want to connect, and check **"GitHub"** in the MCP Platforms section.

    Save and test by asking: *"List repositories in the JunisAI organization"*
  </Step>
</Steps>

***

## Authentication Levels

GitHub MCP supports all three authentication levels:

<Tabs>
  <Tab title="👤 User-Level (Personal GitHub)">
    **Use Case**: Access your personal repositories and private GitHub account

    **Setup**: User Settings > MCP Credentials > GitHub

    **Example**:

    * Your personal projects
    * Private repos under your account
    * Creating issues in repos you own

    **Scopes Needed**: `repo`, `read:user`
  </Tab>

  <Tab title="🏢 Organization-Level (Shared)">
    **Use Case**: Access company/team repositories shared by all team members

    **Setup**: Admin > MCP > GitHub > Organization Credentials (Admin only)

    **Example**:

    * Company repositories
    * Team projects
    * Shared organization resources

    **Scopes Needed**: `repo`, `read:org`, `read:user`
  </Tab>

  <Tab title="🌍 System-Level (Global Default)">
    **Use Case**: Fallback authentication when no user/org credentials exist

    **Setup**: Automatically configured by Junis Super Admins

    **Example**:

    * Public repositories
    * Trial/demo purposes

    **Scopes Needed**: `public_repo` (read-only)
  </Tab>
</Tabs>

**Priority**: User > Organization > System (highest to lowest)

***

## GitHub PAT Scopes Explained

### Minimal Scopes (Read-Only)

```
✅ repo:status - Repository status
✅ public_repo - Public repositories only
```

**Good for**: Browsing public repos, reading issues (no write access)

### Recommended Scopes (Read + Write)

```
✅ repo - Full repository access (includes private repos)
✅ read:org - Read organization information
✅ read:user - Read user profile
```

**Good for**: Full agent capabilities (create issues, PRs, commit files)

### Optional Scopes (Advanced)

```
✅ workflow - Manage GitHub Actions workflows
✅ admin:repo_hook - Manage repository webhooks
✅ delete_repo - Delete repositories (⚠️ Use with caution!)
```

**Good for**: Advanced automation and repository management

<Warning>
  **Security Best Practice**: Only grant the minimum scopes your agents need. You can always create a new token with more scopes later.
</Warning>

***

## Available GitHub Tools

Your agents can use these GitHub MCP tools:

### Repositories

<CardGroup cols={2}>
  <Card title="github_list_repositories" icon="list">
    List all repositories for a user or organization
  </Card>

  <Card title="github_get_repository" icon="book">
    Get detailed information about a specific repository
  </Card>

  <Card title="github_search_repositories" icon="magnifying-glass">
    Search repositories by keyword or criteria
  </Card>

  <Card title="github_create_repository" icon="plus">
    Create a new repository
  </Card>
</CardGroup>

### Issues

<CardGroup cols={2}>
  <Card title="github_list_issues" icon="list-check">
    List issues in a repository
  </Card>

  <Card title="github_get_issue" icon="bug">
    Get details of a specific issue
  </Card>

  <Card title="github_create_issue" icon="circle-plus">
    Create a new issue
  </Card>

  <Card title="github_update_issue" icon="pen-to-square">
    Update an existing issue (title, body, labels, assignees)
  </Card>
</CardGroup>

### Pull Requests

<CardGroup cols={2}>
  <Card title="github_list_pull_requests" icon="code-pull-request">
    List pull requests in a repository
  </Card>

  <Card title="github_get_pull_request" icon="code-compare">
    Get details of a specific PR
  </Card>

  <Card title="github_create_pull_request" icon="code-branch">
    Create a new pull request
  </Card>

  <Card title="github_merge_pull_request" icon="code-merge">
    Merge a pull request
  </Card>
</CardGroup>

### File Operations

<CardGroup cols={2}>
  <Card title="github_get_file_contents" icon="file">
    Read file contents from a repository
  </Card>

  <Card title="github_create_or_update_file" icon="file-pen">
    Create or update a file in a repository
  </Card>

  <Card title="github_push_files" icon="upload">
    Push multiple files in a single commit
  </Card>
</CardGroup>

### Commits & Branches

<CardGroup cols={2}>
  <Card title="github_list_commits" icon="clock-rotate-left">
    View commit history
  </Card>

  <Card title="github_get_commit" icon="code-commit">
    Get details of a specific commit
  </Card>

  <Card title="github_list_branches" icon="code-branch">
    List all branches
  </Card>

  <Card title="github_create_branch" icon="code-fork">
    Create a new branch
  </Card>
</CardGroup>

***

## Example Use Cases

### DevOps Automation Agent

**Agent Prompt**:

```
You are a DevOps automation agent. Monitor GitHub repositories for:
- New issues and pull requests
- Failed CI/CD builds
- Pending code reviews

When you detect issues, create reports and notify the team.
```

**Connected MCP**: GitHub + Slack

**Example Interaction**:

```
User: "Check if there are any failed builds in the main branch"
Agent: [Uses github_list_commits + GitHub Actions status]
       "Found 3 failed builds in the last 24 hours. Creating a report..."
```

### Code Review Assistant

**Agent Prompt**:

```
You are a code review assistant. When given a pull request URL:
1. Fetch the PR details and changed files
2. Analyze code quality and potential issues
3. Leave constructive review comments
```

**Connected MCP**: GitHub only

**Example Interaction**:

```
User: "Review PR #123 in the junis-ai repo"
Agent: [Uses github_get_pull_request, github_get_file_contents]
       "Reviewed 5 changed files. Here are my suggestions:
       - Add error handling in api.py (line 45)
       - Consider using async/await in database.py
       ..."
```

### Issue Triage Agent

**Agent Prompt**:

```
You help triage GitHub issues by:
- Reading new issues
- Analyzing content and assigning labels
- Assigning to appropriate team members
- Prioritizing based on severity
```

**Connected MCP**: GitHub + Notion (for team member database)

**Example Interaction**:

```
User: "Triage all new issues from the last 3 days"
Agent: [Uses github_list_issues, github_update_issue]
       "Triaged 12 new issues:
       - 5 bugs (assigned to engineering team)
       - 4 feature requests (added to backlog)
       - 3 documentation updates (assigned to tech writers)"
```

***

## Troubleshooting

<AccordionGroup>
  <Accordion title="Error: 405 Method Not Allowed" icon="exclamation-triangle">
    **Symptom**: Connection fails with `405 Method Not Allowed for url 'https://api.githubcopilot.com/mcp/'`

    **Cause**: Transport type is set to `sse` instead of `streamable-http`

    **Solution**:

    1. Go to Admin > MCP > GitHub
    2. Edit the platform configuration
    3. Change Transport Type to **"Streamable HTTP"**
    4. Save and test connection
  </Accordion>

  <Accordion title="Error: 401 Unauthorized" icon="lock">
    **Symptom**: Tools load but API calls fail with 401 errors

    **Cause**: Invalid or expired Personal Access Token

    **Solution**:

    1. Generate a new PAT at [https://github.com/settings/tokens](https://github.com/settings/tokens)
    2. Update your MCP credentials in Junis
    3. Test connection again
  </Accordion>

  <Accordion title="Error: 403 Forbidden" icon="ban">
    **Symptom**: Some operations fail with 403 errors

    **Cause**: PAT lacks necessary scopes (permissions)

    **Solution**:

    1. Check which operation failed (e.g., creating issues)
    2. Generate a new PAT with additional scopes:
       * Issues: `repo` scope
       * Private repos: `repo` scope
       * Organization: `read:org` scope
    3. Update credentials and retry
  </Accordion>

  <Accordion title="Tools Not Showing Up" icon="eye-slash">
    **Symptom**: Agent is connected to GitHub but no tools appear

    **Possible Causes**:

    * MCP connection failed
    * Agent cache not refreshed
    * Transport type misconfigured

    **Solution**:

    1. Check logs: Admin > Dashboard > Recent Activity
    2. Look for error messages mentioning "GitHub" or "MCP"
    3. Verify connection in Team > MCP > GitHub > Test Connection
    4. If all looks good, restart the agent (edit and save without changes)
  </Accordion>

  <Accordion title="Rate Limit Exceeded" icon="gauge-high">
    **Symptom**: API calls start failing after many requests

    **Cause**: GitHub API rate limit reached (5,000 requests/hour for authenticated users)

    **Solution**:

    * **Short-term**: Wait 1 hour for rate limit reset
    * **Long-term**: Implement caching in your agent logic to reduce API calls
    * **Check status**: Ask agent "What's my GitHub API rate limit status?"
  </Accordion>
</AccordionGroup>

***

## Security Best Practices

<Check>
  **✅ DO**:

  * Use user-level credentials for personal repositories
  * Use organization-level credentials for shared team resources
  * Rotate PATs every 90 days
  * Grant only the minimum required scopes
  * Store PATs in a password manager
</Check>

<Warning>
  **❌ DON'T**:

  * Share your Personal Access Token with anyone
  * Commit PATs to code repositories
  * Use admin-level tokens for routine operations
  * Grant `delete_repo` scope unless absolutely necessary
</Warning>

***

## Advanced Configuration

### Using GitHub Enterprise Server

If your organization uses GitHub Enterprise Server:

```json theme={null}
{
  "mcp_server_url": "https://github.your-company.com/api/mcp/",
  "transport_type": "streamable-http",
  "additional_auth_config": {
    "headers": {
      "Authorization": "Bearer ghp_your_enterprise_token"
    }
  }
}
```

### Rate Limit Monitoring

Create an agent that monitors GitHub API rate limits:

**Agent Instruction**:

```
When asked about rate limits, use the github_get_rate_limit tool
to check remaining API calls and reset time.
```

***

## What's Next?

<CardGroup cols={2}>
  <Card title="Firecrawl MCP" icon="spider" href="/guides/mcp/firecrawl">
    Web scraping and crawling
  </Card>

  <Card title="Custom MCP Servers" icon="cog" href="/guides/mcp/custom">
    Build your own MCP integrations
  </Card>

  <Card title="MCP Overview" icon="arrow-left" href="/guides/mcp/overview">
    Back to MCP Integration overview
  </Card>
</CardGroup>

***

## Additional Resources

* **GitHub MCP Server**: [https://github.com/github/github-mcp-server](https://github.com/github/github-mcp-server)
* **GitHub PAT Guide**: [https://docs.github.com/en/authentication/keeping-your-account-and-data-secure/creating-a-personal-access-token](https://docs.github.com/en/authentication/keeping-your-account-and-data-secure/creating-a-personal-access-token)
* **GitHub API Docs**: [https://docs.github.com/en/rest](https://docs.github.com/en/rest)
* **MCP Protocol**: [https://modelcontextprotocol.io/](https://modelcontextprotocol.io/)

<Note>
  **Need Help?** Contact us at [contact@junis.ai](mailto:contact@junis.ai) for assistance with GitHub automation workflows and integration support.
</Note>