# GitHub

Use GitHub in a repository thread to read pull requests and their checks, find out why a check failed, comment, and merge or push only after you approve.

## Before you start

Connect your GitHub account under **Data** and choose the repositories Redbelt may use. Repository threads start on a computer with a checkout of the repository, where the agent commits, pushes its own branch, and opens pull requests with `git` and `gh` when you ask.

This plugin covers what needs your approval or works without a computer. Check **Enabled** and **Approval** for its tools under **Customize → Plugins**. See [action approvals](/threads/approvals/).

## Fix a failing check

1. Ask Redbelt for the pull request's state and checks.
2. Ask why a check failed. Redbelt reads the end of each failed GitHub Actions log.
3. Redbelt fixes the cause in the checkout, commits, pushes, and checks again.

> Check the pull request for this branch. If a check failed, read its log, fix the cause, push, and tell me when the checks pass.

## Merge and push with approval

Redbelt merges a pull request only when you ask. It reads the pull request first, and you approve the merge in the thread. The merge is refused if the branch moved after it was read.

Redbelt can push freely to a branch the thread created. To push to another branch, it asks you first; once you approve, it pushes again. Protected branches are never allowed, so Redbelt opens a pull request instead. The computer refuses merges and branch deletions made with `git` or `gh`.

## Tool Reference

Thread and workflow availability are listed separately. A tool must also be enabled for your task and allowed by its account and administrator policy.

### Available Tools

| Tool                             | Required Fields                    | Thread | Workflow |
| -------------------------------- | ---------------------------------- | ------ | -------- |
| `github.allow_branch_push`       | `repository`, `branch`             | Yes    | No       |
| `github.comment_on_pull_request` | `repository`, `number`, `body`     | Yes    | No       |
| `github.get_check_logs`          | `repository`, `number`             | Yes    | No       |
| `github.get_pull_request`        | `repository`, `number`             | Yes    | No       |
| `github.list_pull_requests`      | `repository`                       | Yes    | No       |
| `github.merge_pull_request`      | `repository`, `number`, `head_sha` | Yes    | No       |

Required fields above are the schema minimum. The target, selected operation, or account can impose additional requirements.

**`github.allow_branch_push`** — Ask the person to let this thread push to an existing branch it did not create.

**`github.comment_on_pull_request`** — Add a comment to a pull request's thread.

**`github.get_check_logs`** — Read why a pull request's checks failed: each failed check's summary and the end of its log (GitHub Actions).

**`github.get_pull_request`** — Read one pull request: state, branches, head commit, whether it can merge, and a summary of its checks.

**`github.list_pull_requests`** — List a repository's pull requests (newest first, at most 50), optionally only those from one branch.
Optional fields: `head_branch`, `state`.

**`github.merge_pull_request`** — Merge a pull request after the person approves.
Optional fields: `method`.

## Troubleshoot

If a repository is missing, check that it is chosen for your GitHub connection under **Data**. If a push says it needs approval, approve the request in the thread and let Redbelt push again.

Provider details: [GitHub documentation](https://docs.github.com/en/pull-requests).
