# GitHub

## What it does

Once connected, Speedwave can work with a repository the way a developer would: browse its contents, follow a pull request through commits and CI runs, and post review feedback.

## What it consists of

GitHub runs as its own worker, a container with access to GitHub tokens only. Speedwave writes your token to the project's token directory and mounts it read-only into the worker at `/tokens/token`, so the container can reach GitHub.com and nothing else. See [Credentials](/docs/security/credentials/) for how that mount and file permissions work across every integration.

## How it works

You connect through the GitHub OAuth device flow: Speedwave shows a code, you approve it at `https://github.com/login/device`, and the token lands on disk without ever passing through the project's web UI. The Speedwave OAuth App requests the `repo` and `read:user` scopes: read/write on private and public repos, issues, pull requests, releases, and Actions, plus reading your account for the connection test.

A manual token is the fallback when the device flow doesn't fit, for example a headless setup. Paste a token starting with `gho_` (an OAuth App user token), `github_pat_` (fine-grained PAT), or `ghp_` (classic PAT); the worker reads whichever one you give it without checking the prefix, so make sure it covers the same scopes as above.

From there, the worker exposes 45 tools grouped by area: repositories, pull requests, pull request review, branches, commits, repository content, Actions, issues, labels, and releases. A few worth knowing: `createPrComment` posts a general comment on the conversation, while `createPrReviewComment` posts an inline comment anchored to a diff line, since these are separate GitHub endpoints; `createPrReview` and `listPrReviews` work at the review level, which matters for [code review](/docs/features/code-review/). `getRunLogs` and `downloadArtifact` return a short-lived download URL pointing at a ZIP rather than fetching and unpacking it for you, so download promptly. `createRelease` creates the tag for you if it doesn't already exist, so there's no need to call `createTag` first.

The worker only reaches GitHub.com through `https://api.github.com`; GitHub Enterprise Server is not supported. There is also no blame tool, since GitHub's REST API has no line-level blame endpoint.

## What Speedwave can do

| Tool | What it does |
| --- | --- |
| `listRepos` | Lists or searches repositories the account can see. |
| `getRepo` | Reads details of one repository. |
| `searchCode` | Searches code across GitHub, optionally scoped to a repo. |
| `listPullRequests` | Lists pull requests with state, branch, or base filters. |
| `getPullRequest` | Reads details of one pull request. |
| `createPullRequest` | Opens a new pull request, draft or ready. |
| `updatePullRequest` | Changes a pull request's title, body, base, or state. |
| `mergePullRequest` | Merges a pull request. Destructive. |
| `getPrDiff` | Returns a pull request's unified diff as text. |
| `getPrFiles` | Lists a pull request's changed files with per-file stats. |
| `listPrCommits` | Lists the commits included in a pull request. |
| `listPrReviews` | Lists reviews submitted on a pull request. |
| `createPrReview` | Submits a review: approve, request changes, or comment, with optional inline comments. |
| `listPrComments` | Lists general (non-review) comments on a pull request. |
| `createPrComment` | Adds a general comment to a pull request. |
| `createPrReviewComment` | Adds a review comment anchored to a diff line. |
| `listBranches` | Lists a repository's branches. |
| `getBranch` | Reads details of one branch. |
| `createBranch` | Creates a branch from a commit or another branch. |
| `deleteBranch` | Deletes a branch. Destructive. |
| `compareBranches` | Diffs two branches or commits. |
| `listCommits` | Lists commits with filters for branch, path, author, and date range. |
| `listBranchCommits` | Lists commits on a specific branch. |
| `searchCommits` | Searches commit messages across GitHub. |
| `getCommitDiff` | Returns one commit's unified diff as text. |
| `getTree` | Lists a repository's file or directory tree. |
| `getFileContents` | Reads a file's contents; errors if the path is a directory. |
| `createOrUpdateFile` | Writes a file with a commit, fetching the current blob SHA if you don't supply one. |
| `listWorkflowRuns` | Lists Actions workflow runs, filterable by branch or status. |
| `getWorkflowRun` | Reads details of one workflow run. |
| `getRunLogs` | Returns a short-lived ZIP download URL for a run's logs. |
| `rerunWorkflow` | Reruns an existing workflow run. |
| `triggerWorkflow` | Fires a manual `workflow_dispatch` run. |
| `listWorkflowRunArtifacts` | Lists artifacts produced by a workflow run. |
| `downloadArtifact` | Returns a short-lived ZIP download URL for an artifact. |
| `listIssues` | Lists issues, excluding pull requests, with state and label filters. |
| `getIssue` | Reads details of one issue. |
| `createIssue` | Opens a new issue. |
| `updateIssue` | Changes an issue's title, body, state, labels, or assignees. |
| `closeIssue` | Closes an issue. |
| `listLabels` | Lists labels defined in a repository. |
| `createLabel` | Creates a new label. |
| `createTag` | Creates a Git tag, lightweight or annotated. |
| `deleteTag` | Deletes a Git tag. Destructive. |
| `createRelease` | Creates a release, creating its tag first if needed. |

## Set it up

1. Open the project's integrations and select **GitHub**.

2. Click **Sign in with GitHub** and approve the device code Speedwave shows you at `https://github.com/login/device`.

3. Speedwave writes the resulting token to the project's token directory once you approve, and GitHub appears ready to use in the project.

<DesktopFrame screen="integrations" />

When a GitHub call fails, the worker maps the response to plain guidance:

| Status | Meaning |
| --- | --- |
| `401` | Token no longer valid. Connect GitHub again to get a new one. |
| `403`, rate limited | Rate limit exhausted. The worker already retries up to twice on its own; wait and try again after that. |
| `403`, permission | Token can't do this. Reconnect via OAuth to re-grant scopes, or check the manual PAT's permissions. |
| `404` | Item not found. |
| `422` | Validation failed; the message names what was wrong. |
| `5xx` | GitHub had a server error. |
| Network error | Worker couldn't reach `api.github.com`; check your connection. |

## Security boundaries

The GitHub worker can read GitHub tokens only. It has no access to any other service's credentials, and [the hub that routes tool calls to it holds no tokens of its own](/docs/under-the-hood/tool-gateway/), so a compromised worker's reach stops at GitHub. That boundary holds even when Speedwave is posting automated [code review](/docs/features/code-review/) comments: the worker can act on a pull request but still cannot see credentials for any other integration.