GitHub

Authentication Type: API Key Description: Integrate with GitHub to manage repositories, pull requests, and search code.

Authentication

To authenticate, you'll need a GitHub Personal Access Token. Learn how to create one in the GitHub documentation.

Required Scopes:

• repo - Full control of private repositories
• workflow - Update GitHub Action workflows

Repositories

Operations for GitHub repositories.

Read File

Reads a file from a GitHub repository.

Operation Type: Query (Read)

Parameters:

• owner string (required): The repository owner (username or organization)
• repo string (required): The repository name
• path string (required): The file path within the repository
• ref string (required): The branch, tag, or commit SHA to read from (defaults to main branch)

Returns:

• content string: The file content (base64 decoded)
• encoding string: The encoding of the file content
• size number: The size of the file in bytes
• sha string: The SHA of the file
• path string: The file path

Example Usage:

{
  "owner": "facebook",
  "repo": "react",
  "path": "README.md",
  "ref": "main"
}

Get Branch SHA

Gets the SHA of a specific branch.

Operation Type: Query (Read)

Parameters:

• owner string (required): The repository owner (username or organization)
• repo string (required): The repository name
• branch string (required): The branch name to get the SHA for

Returns:

• sha string: The SHA of the branch
• branch string: The branch name

Example Usage:

{
  "owner": "microsoft",
  "repo": "vscode",
  "branch": "main"
}

Create Branch

Creates a new branch in a GitHub repository.

Operation Type: Mutation (Write)

Parameters:

• owner string (required): The repository owner (username or organization)
• repo string (required): The repository name
• branch string (required): The name of the new branch
• baseSha string (required): The SHA to base the new branch on

Returns:

• ref string: The reference name (refs/heads/branch-name)
• sha string: The SHA of the new branch
• branch string: The branch name

Example Usage:

{
  "owner": "myorg",
  "repo": "myproject",
  "branch": "feature/new-api-endpoint",
  "baseSha": "abc123def456789"
}

Create File

Creates a new file in a GitHub repository.

Operation Type: Mutation (Write)

Parameters:

• owner string (required): The repository owner (username or organization)
• repo string (required): The repository name
• path string (required): The file path within the repository
• message string (required): The commit message
• content string (required): The file content (will be base64 encoded)
• branch string (required): The branch to create the file in

Returns:

• content object: The created file information
  • name string: The file name
  • path string: The file path
  • sha string: The SHA of the file
• commit object: The commit information
  • sha string: The SHA of the commit
  • message string: The commit message

Example Usage:

{
  "owner": "myorg",
  "repo": "myproject",
  "path": "src/components/NewComponent.js",
  "message": "Add new React component for user authentication",
  "content": "import React from 'react';\n\nconst NewComponent = () => {\n  return <div>Hello World</div>;\n};\n\nexport default NewComponent;",
  "branch": "feature/new-component"
}

Update File

Updates an existing file in a GitHub repository.

Operation Type: Mutation (Write)

Parameters:

• owner string (required): The repository owner (username or organization)
• repo string (required): The repository name
• path string (required): The file path within the repository
• message string (required): The commit message
• content string (required): The new file content (will be base64 encoded)
• sha string (required): The SHA of the file being updated
• branch string (required): The branch to update the file in

Returns:

• content object: The updated file information
  • name string: The file name
  • path string: The file path
  • sha string: The SHA of the updated file
• commit object: The commit information
  • sha string: The SHA of the commit
  • message string: The commit message

Example Usage:

{
  "owner": "myorg",
  "repo": "myproject",
  "path": "src/components/ExistingComponent.js",
  "message": "Fix bug in user authentication logic",
  "content": "import React from 'react';\n\nconst ExistingComponent = () => {\n  // Fixed authentication logic\n  return <div>Updated Component</div>;\n};\n\nexport default ExistingComponent;",
  "sha": "def456abc789123",
  "branch": "bugfix/auth-issue"
}

Create Pull Request

Creates a new pull request in a GitHub repository.

Operation Type: Mutation (Write)

Parameters:

• owner string (required): The repository owner (username or organization)
• repo string (required): The repository name
• title string (required): The title of the pull request
• body string (required): The body/description of the pull request
• head string (required): The branch containing the changes (source branch)
• base string (required): The branch to merge into (target branch)
• draft boolean (required): Whether to create the pull request as a draft

Returns:

• number number: The pull request number
• htmlUrl string: The URL to view the pull request
• state string: The state of the pull request
• title string: The title of the pull request

Example Usage:

{
  "owner": "myorg",
  "repo": "myproject",
  "title": "Add user authentication system",
  "body": "This PR introduces a comprehensive user authentication system with the following features:\n\n- JWT token-based authentication\n- Password hashing with bcrypt\n- Login/logout functionality\n- Protected route middleware\n\nFixes #123",
  "head": "feature/user-auth",
  "base": "main",
  "draft": false
}

Pull Requests

Operations for listing and inspecting pull requests.

List Pull Requests

List pull requests in a repository with filtering by state, author, and sort order.

Operation Type: Query (Read)

Parameters:

• owner string (required): Repository owner (username or organization)
• repo string (required): Repository name
• state string (nullable): Filter by PR state (open, closed, all). Defaults to open
• head string (nullable): Filter by head user/org and branch (format: user:ref-name)
• base string (nullable): Filter by base branch name
• sort string (nullable): Sort by (created, updated, popularity, long-running). Defaults to created
• direction string (nullable): Sort direction (asc, desc). Defaults to desc
• perPage number (nullable): Results per page (max 100). Defaults to 30
• page number (nullable): Page number. Defaults to 1

Returns:

• pullRequests array of objects: Array of pull requests
  • number number: PR number
  • title string: PR title
  • state string: PR state (open or closed)
  • htmlUrl string: URL to PR on GitHub
  • createdAt string: Creation timestamp
  • updatedAt string: Last updated timestamp
  • closedAt string (nullable): Closed timestamp
  • mergedAt string (nullable): Merged timestamp
  • draft boolean: Whether this is a draft PR
  • user string: Author username
  • labels array of strings: Label names
  • head string: Head branch name
  • base string: Base branch name
• totalCount number: Number of pull requests returned

Example Usage:

{
  "owner": "facebook",
  "repo": "react",
  "state": "closed",
  "head": null,
  "base": "main",
  "sort": "updated",
  "direction": "desc",
  "perPage": 10,
  "page": 1
}

Get Pull Request

Get full details of a pull request including description, diff stats, files changed with patches, reviewers, and all comments.

Operation Type: Query (Read)

Parameters:

• owner string (required): Repository owner (username or organization)
• repo string (required): Repository name
• pullNumber number (required): Pull request number

Returns:

• number number: PR number
• title string: PR title
• body string (nullable): PR description/body
• state string: PR state
• htmlUrl string: URL to PR on GitHub
• createdAt string: Creation timestamp
• updatedAt string: Last updated timestamp
• closedAt string (nullable): Closed timestamp
• mergedAt string (nullable): Merged timestamp
• draft boolean: Whether this is a draft PR
• mergeable boolean (nullable): Whether the PR can be merged
• user string: Author username
• labels array of strings: Label names
• head string: Head branch name
• base string: Base branch name
• additions number: Total lines added
• deletions number: Total lines deleted
• changedFiles number: Number of files changed
• reviewers array of strings: Requested reviewer usernames
• files array of objects: Files changed in the PR
  • filename string: File path
  • status string: File status (added, removed, modified, renamed)
  • additions number: Lines added in this file
  • deletions number: Lines deleted in this file
  • changes number: Total line changes
  • patch string (nullable): Diff patch for this file
• comments array of objects: All comments (issue comments and review comments)
  • id number: Comment ID
  • user string: Comment author username
  • body string: Comment body
  • createdAt string: Comment creation timestamp
  • path string (nullable): File path if review comment, null for issue comments

Example Usage:

{
  "owner": "facebook",
  "repo": "react",
  "pullNumber": 28472
}

Code Search

Search for code across GitHub repositories.

Search Code

Search for code with filters for owner, repository, path, file extension, and language. Returns matching files with text fragments.

Operation Type: Query (Read)

Parameters:

• query string (required): Search query (supports GitHub code search syntax)
• owner string (nullable): Filter to repositories owned by this user or org
• repo string (nullable): Filter to a specific repository (format: owner/repo)
• path string (nullable): Filter to files in this path
• extension string (nullable): Filter by file extension (e.g., "ts", "py")
• language string (nullable): Filter by programming language
• perPage number (nullable): Results per page (max 100). Defaults to 30
• page number (nullable): Page number. Defaults to 1

Returns:

• totalCount number: Total number of matching results
• items array of objects: Search result items
  • name string: File name
  • path string: Full file path in the repo
  • sha string: File SHA
  • htmlUrl string: URL to view file on GitHub
  • repository string: Full repository name (owner/repo)
  • score number: Relevance score
  • textMatches array of objects: Text match fragments with context
    • fragment string: Text fragment containing the match
    • matches array of objects: Individual matches
      • text string: Matched text
      • indices array of numbers: Start and end indices

Example Usage:

{
  "query": "useEffect cleanup",
  "owner": null,
  "repo": "facebook/react",
  "path": "packages",
  "extension": "ts",
  "language": null,
  "perPage": 10,
  "page": 1
}

Repository Content

Browse repository file trees and get file metadata.

Get Repository Content

List directory contents or get file metadata for a path in a GitHub repository.

Operation Type: Query (Read)

Parameters:

• owner string (required): Repository owner (username or organization)
• repo string (required): Repository name
• path string (nullable): Path within the repository. Use empty or null for root directory
• ref string (nullable): Branch, tag, or commit SHA. Defaults to default branch

Returns:

• type string: Whether the path is a file or directory
• entries array of objects: Directory entries or single file entry
  • name string: File or directory name
  • path string: Full path within the repository
  • type string: Entry type (file, dir, submodule, symlink)
  • size number: File size in bytes (0 for directories)
  • sha string: Git SHA
  • htmlUrl string: URL to view on GitHub

Example Usage:

{
  "owner": "facebook",
  "repo": "react",
  "path": "packages/react/src",
  "ref": "main"
}

Common Use Cases

Pull Request Management:

• List recently closed PRs by a specific author to review their work
• Get full PR details with diffs, comments, and review status for code review
• Create pull requests automatically after completing automated code changes

Code Search & Discovery:

• Search for code patterns, function definitions, or security issues across repositories
• Find files by extension or language to understand project structure
• Browse repository contents to explore unfamiliar codebases

Development Workflow Automation:

• Create feature branches, make file changes, and open PRs in a single workflow
• Update version files, changelogs, and documentation as part of CI/CD pipelines
• Read and analyze repository files for automated code quality checks

Team Activity Tracking:

• List merged PRs sorted by recency to generate release notes
• Monitor PR activity across repositories for team status updates
• Review PR comments and review feedback for coaching and process improvement