> For clean Markdown of any page, append .md to the page URL.
> For a complete documentation index, see https://docs.runtype.com/llms.txt.
> For AI client integration (Claude Code, Cursor, etc.), connect to the MCP server at https://docs.runtype.com/_mcp/server.

# GitHub integration

Connect GitHub so your Agents can file issues from error reports, open and comment on pull requests, read files, search code, and commit changes to a branch. Agents and prompt steps in a Flow can call the GitHub tools. There is no dedicated GitHub Flow step.

## Before you begin

Create a [personal access token](https://github.com/settings/tokens) in GitHub before you connect the integration. Choose a fine-grained personal access token when it supports your use case, then select the repositories that the tools work with. For a classic token, select the `repo` scope for private repository access and the `read:org` scope to read organization membership.

A fine-grained token needs the following repository permissions for each group of tools:

| Tools                                                               | Permission                                |
| ------------------------------------------------------------------- | ----------------------------------------- |
| Repository, file, branch, and commit reads                          | **Metadata**: Read and **Contents**: Read |
| `list_issues`, `list_issue_comments`                                | **Issues**: Read                          |
| `create_issue`, `update_issue`, `create_pr_comment`                 | **Issues**: Read and write                |
| `list_pull_requests`, `get_pull_request`, `list_pull_request_files` | **Pull requests**: Read                   |
| `create_pull_request`                                               | **Pull requests**: Read and write         |
| `create_branch`, `commit_files`                                     | **Contents**: Read and write              |

Treat the token as a password. Do not share it or commit it to source control.

## Connect GitHub

Runtype stores the token with the GitHub integration, not in an Agent's tool configuration. After you connect GitHub once, every Agent and prompt step in your account can add GitHub tools.

To connect GitHub while you configure an Agent, follow these steps:

1. In the Agent editor, click the **+** button in the tools area. In some layouts, the button reads **Add tool**. The tool picker opens.
2. Select **GitHub**. If GitHub has no credential, the setup form opens.
3. Enter your token in **Personal access token**.
4. Click **Connect GitHub**. Runtype saves the credential and adds every GitHub tool to the Agent, including the tools that write to GitHub.
5. Optional: Clear the GitHub tools that the Agent must not call.

A prompt step in a Flow uses the same tool picker and setup form.

## Verify the connection

To confirm that the token works, run the Agent with a prompt that reads a repository that the token can see. For example: "Get the details of the `your-org/your-repo` repository." When the Agent has the `get_repo` tool, it can call that tool and return details such as the repository's default branch and visibility. If the call fails, see [Troubleshooting](#troubleshooting).

## Available tools

GitHub provides the following tools.

### Repositories

Use these tools to list repositories and view repository details:

* `list_repos`: Lists repositories for the authenticated account or an organization. The tool returns GitHub's default first page of 30 results and ignores its `type`, `sort`, and `per_page` inputs.
* `get_repo`: Gets repository details.

### Issues

Use these tools to create, list, and update issues:

* `create_issue`: Creates an issue with optional labels, assignees, and a milestone.
* `list_issues`: Lists the open issues in a repository. GitHub includes open pull requests in this list. The tool returns GitHub's default first page of 30 results and ignores its `state`, `labels`, `assignee`, and `per_page` inputs.
* `update_issue`: Updates an issue's title, body, state, or labels.

### Pull requests

Use these tools to create, list, inspect, and comment on pull requests:

* `create_pull_request`: Creates a pull request, optionally as a draft, from a head branch to a base branch.
* `list_pull_requests`: Lists pull requests filtered by state, head branch, and base branch. Set `per_page` to return up to 100 results. The tool returns only the first page.
* `get_pull_request`: Gets pull request details.
* `create_pr_comment`: Adds a comment to a pull request.
* `list_pull_request_files`: Lists every file that a pull request changes, with GitHub patch data.
* `list_issue_comments`: Lists every comment on an issue or pull request.

`list_pull_request_files` and `list_issue_comments` return the full list. When a pull request changes more than 3,000 files, or an issue has more than 3,000 comments, the tool returns an error instead of a partial list.

### Branches

Use these tools to create branches and compare revisions:

* `create_branch`: Creates a branch at a commit SHA. If the branch already exists at the same commit, the call succeeds and reports `created: false`. If the branch already exists at a different commit, the tool returns an error. Choose a new branch name, or use `commit_files` on the existing branch.
* `compare_commits`: Compares two branches, tags, or commit SHAs.

### Files

Use these tools to inspect and change repository files:

* `get_file_content`: Reads a file from a repository. The `ref` parameter accepts a branch, tag, or commit SHA and defaults to the repository's default branch. The response is GitHub's file object, and the file text is base64-encoded in its `content` field. Use `list_directory` for a directory.
* `list_directory`: Lists files and subdirectories at the repository root or a directory path. Use `ref` to inspect a branch, tag, or commit.
* `get_repository_tree`: Returns a Git tree for a branch, tag, commit, or tree SHA. Set `recursive` to list nested paths. GitHub can truncate the result for a very large repository.
* `commit_files`: Writes and deletes 1 to 100 paths in one atomic commit, then fast-forwards the branch. For its inputs, see [Commit files](#commit-files).
* `search_code`: Searches for code across GitHub repositories.

### Commit files

`commit_files` takes the following parameters:

* `owner`, `repo`, and `branch`: The branch to commit to.
* `message`: The commit message.
* `changes`: A list of 1 to 100 file changes.
* `expected_head_sha`: Optional. The commit that you expect the branch to point to. If another commit moved the branch first, the tool returns an error and writes nothing.

Each entry in `changes` has these fields:

* `path`: A repository-relative path such as `docs/intro.md`. A path cannot start or end with `/`, and it can appear only once in a commit.
* `content`: The complete UTF-8 text of the file. The text replaces the whole file. The tool does not accept patches, diffs, or binary files.
* `delete`: Set to `true` to delete the file. Each change needs either `content` or `delete: true`, not both.
* `mode`: Optional. Use `100755` for an executable file or `120000` for a symlink. The default is `100644`, a regular file.

The following example adds one file and deletes another:

```json
{
  "owner": "your-org",
  "repo": "your-repo",
  "branch": "docs-update",
  "message": "Update the getting started guide",
  "expected_head_sha": "HEAD_COMMIT_SHA",
  "changes": [
    { "path": "docs/getting-started.md", "content": "# Getting started\n\nInstall the CLI.\n" },
    { "path": "docs/old-guide.md", "delete": true }
  ]
}
```

Replace `HEAD_COMMIT_SHA` with the branch's current commit SHA, or leave out `expected_head_sha`. The response includes `commitSha`, `commitUrl`, and `changedPaths`.

## Respond to GitHub events

To run an Agent when something happens in GitHub, such as a pull request being opened, add a webhook Surface that uses the **GitHub** signature provider. For setup, see [Setting up a webhook surface](/user-guide/products-surfaces/setting-up-a-webhook-surface). The surface's test panel sends a signed GitHub test delivery and uses the GitHub token that you connected on this page.

## Troubleshooting

The following failures are the most common:

* **The call fails with a 401 error**: The token has expired or was revoked. Create a new token in GitHub. The setup form opens only when GitHub has no credential, so replace the stored token through the API: send `POST /v1/integrations/github/credentials` with the body `{"token": "YOUR_GITHUB_TOKEN"}`. A scoped API key needs the `INTEGRATIONS:WRITE` permission.
* **The call fails with a 404 error for a repository that exists**: The token can't see that repository. For a fine-grained token, add the repository to the token in GitHub. For a classic token, select the `repo` scope.
* **Reads work, but writes fail with a 403 error**: The token lacks write permission for that tool. Grant the permission that the tool needs from the table in [Before you begin](#before-you-begin).

## Remove GitHub access

To stop an Agent from using GitHub, remove the GitHub tools from that Agent in the tool picker.

To stop all GitHub access from Runtype, revoke the token in your [GitHub token settings](https://github.com/settings/tokens). To delete the stored credential from Runtype, send `DELETE /v1/integrations/github/credentials` with your API key. GitHub tool calls fail until you connect a new token.

## Next steps

Continue with one of these pages:

* [Agent tools](/user-guide/agents/agent-tools): add and configure tools on an Agent.
* [Setting up a webhook surface](/user-guide/products-surfaces/setting-up-a-webhook-surface): trigger an Agent from GitHub events.
* [Linear integration](/user-guide/integrations/linear-integration): connect another issue-tracking integration.