# GitHub

> Integrate with GitHub to manage repositories, pull requests, and search code.

Source: https://cotera.co/docs/reference/tools/individual-tools/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](https://docs.github.com/en/authentication/keeping-your-account-and-data-secure/creating-a-personal-access-token).

**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:**

```json
{
  "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:**

```json
{
  "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:**

```json
{
  "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:**

```json
{
  "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:**

```json
{
  "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:**

```json
{
  "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:**

```json
{
  "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:**

```json
{
  "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:**

```json
{
  "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:**

```json
{
  "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