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

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.

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.
• 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:

{
  "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. 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.

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. 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: add and configure tools on an Agent.
• Setting up a webhook surface: trigger an Agent from GitHub events.
• Linear integration: connect another issue-tracking integration.