> ## Documentation Index
> Fetch the complete documentation index at: https://ara-90a60a07.mintlify.site/llms.txt
> Use this file to discover all available pages before exploring further.

# GitHub

> Connect GitHub to Reason: choose repositories, start a Session on one, work on issues, open and review pull requests, read checks, merge, and wake Loops.

Reason works in your GitHub repositories. Connect GitHub once, and a Session can check out a repository, commit on its own branch, open a pull request, read its checks and reviews, and merge it.

## Connect GitHub

Connecting GitHub signs you in with GitHub and installs the Reason GitHub App on a GitHub account or organization. The installation belongs to your Reason Workspace. Each person also links their own GitHub account in it.

1. In Reason, open [**Customize**, then **GitHub**](https://reasonmachines.com/customize?tab=plugins\&plugin=github) and choose **Connect GitHub**. GitHub opens in a new tab.
2. On GitHub, pick your own account or an organization you own, choose all or only selected repositories, and install. GitHub may first ask you to confirm access with your password, passkey or two-factor code; finish that on the same page. Then approve the authorization step that follows.
3. GitHub returns you to Reason and your repositories appear under **Repositories**.

You do not have to connect anything before you send a message. When a task needs a repository and the Workspace has no GitHub connection, Reason shows a GitHub card in the chat. Choose **Authorize** there; GitHub opens and returns you to the Session.

> [!NOTE]
>
> If GitHub shows a 404 at `github.com/apps/reason-machines/installations`, its confirm-access page expired. Reloading it, or a phone switching to an authenticator app, does this. Nothing was installed. Go back to Reason, choose **Try again** on the notice (or **Connect GitHub**), and finish confirming without leaving the page.

### An organization you do not own

If you are a member but not an owner of a GitHub organization, GitHub sends your install request to the organization's owners. Invite an owner to your Reason Workspace; the repositories appear once they approve the request and connect GitHub there.

### Your GitHub account

The GitHub page shows **Your GitHub account**. If it reads **Not linked**, choose **Link account**. If it shows **Reconnect GitHub**, your sign-in expired; choose it.

Reason uses your linked account when you act as yourself, such as when you approve a pull request from the review pane, and to credit you on commits.

### Add or remove repositories

* **Add:** choose **Add repositories** on the GitHub page, or type `@` in the message box, choose **Repositories**, then **Add repositories**. Both open GitHub, where you choose them.
* **One repository a task needs:** when a Session needs a repository the Workspace cannot reach, Reason shows a card that names it. The card opens GitHub, where you add that repository.
* **Remove:** choose **Configure** on the GitHub page to open the installation's settings on GitHub, and remove the repository there. It then leaves Reason, and Loops woken by its GitHub events stop.
* **Disconnect:** uninstalling the Reason GitHub App on GitHub removes the installation and its repositories from Reason.

## Start work in a repository

* **In the app:** type `@` in the message box and choose **Repositories**, then the repository. The Session works in its own checkout of it.

* **From the CLI:** add `--repo OWNER/REPO` to start cloud work on a repository.

  ```bash theme={null}
  reason "Fix the failing date parser test." --cloud --repo acme/web
  reason run "Fix the failing date parser test." --repo acme/web --wait --json
  ```

* **A Reason's defaults:** a [Reason](https://ara-90a60a07.mintlify.site/docs/reasons.md#create-and-set-up-a-reason) can have up to 6 default repositories that its new Sessions check out when you pick none.

* **On your own computer:** run `reason` in the repository's folder, or pass `--dir PATH`. See [Reason CLI](https://ara-90a60a07.mintlify.site/docs/cli.md).

Cloud work on a private repository needs the Reason GitHub App installed on that repository.

### The Session's branch

A Session works on its own branch, not on the default branch. The branch name starts with `reason/`, followed by a short form of the Session's title and 8 characters of its id, for example `reason/fix-date-parser-1a2b3c4d`.

Through the API, [Create a session](https://ara-90a60a07.mintlify.site/api-reference/sessions/create-a-session.md) can start somewhere else:

| Field | The Session |
| - | - |
| `branch` | Checks out an existing branch and commits onto it. The branch is created off the default branch if it does not exist |
| `pr_number` | Continues an existing pull request: it checks out the head branch and commits back onto it |
| `ref` | Starts a new branch from a commit SHA, a tag or a branch, and opens a new pull request |
| `base_branch` | Opens its pull request against this branch |

`branch`, `pr_number` and `ref` cannot be combined with each other.

## Issues

Ask a Reason, in plain words, to work with issues in a connected repository. It can:

* Read an issue and search issues, across several repositories at once.
* Open an issue, with labels.
* Comment on an issue.
* Close or reopen an issue.

To work on an issue, give the Reason its link or its number and say what you want: "Fix acme/web#412 and open a pull request." When its pull request resolves the issue, Reason links the two with a closing keyword such as `Fixes acme/web#412`.

To start work when something happens to an issue, use a [Loop](#loops-woken-by-github): on a new issue, or when someone adds a label you choose.

## Pull requests

When you ask for a change in a repository, Reason commits on the Session's branch, pushes it and opens a pull request. Ask for a draft when you want one.

* **Author:** on a cloud computer, the Reason GitHub App is the author of the commits and usually of the pull request.
* **Credit:** commits carry a `Co-authored-by` trailer for the people who took part in the Session, using their linked GitHub accounts.
* **Without a pull request:** when a turn ends on a cloud computer, the Session's new commits are pushed to its branch even if no pull request exists. **Create PR** in the review pane opens one.

### The review pane

A Session's pull request opens in the review pane beside the conversation, with the tabs **Description**, **Changes**, **Discussion**, **Commits** and **Checks**. From it you can mark a draft **ready for review**, **update the branch**, convert it back to a draft, close it, and submit a review as **Comment**, **Approve** or **Request changes**.

[**Review**](https://reasonmachines.com/review) lists pull requests in the connected repositories, with **Opened by Reason** first. The sidebar lists Review only after you turn on **Review in sidebar**, under Appearance in **Settings**, **Overview**.

### What brings a Session back to its pull request

A Session that opened a pull request, or pushed to one, follows it. These wake the Session, grouped into one turn when several arrive together:

* The check result for its newest commit, pass or fail.
* A review or a comment from someone with write access to the repository.
* A merge conflict, or a merge that was blocked.
* The pull request merging or closing.

A bot's comments do not wake the Session; it reads them the next time something else does. The Session stops following the pull request when it merges or closes. It also stops after 7 days without activity, after 30 wakes, or when the same check has failed three turns in a row.

### Review someone else's pull request

Give a Reason the pull request's link and ask for a review. It posts a formal GitHub review (approve, request changes or comment) only when you ask for one. It can also reply to review threads and resolve them.

### Approve a pull request Reason opened

GitHub does not let a pull request's author approve it, and Reason does not let a Session approve a pull request it wrote. A person with access to the repository approves it instead:

* In Reason, open the review pane, choose **Review**, then **Approve**. The approval is posted from your own linked GitHub account.
* On GitHub, signed in as yourself, open the pull request, choose **Files changed**, then **Review changes**, select **Approve** and submit.

## Checks

Reason reads a pull request's checks, and for a failed check the steps that failed and the job's log. When a check fails on its own pull request, the Session is woken with the failing checks and an excerpt of each log, so it can reproduce the failure and push a fix.

Ask a Reason to do any of these with GitHub Actions in a connected repository:

* List the workflows and their runs, and read a run's jobs, logs and artifacts.
* Rerun a run, or only its failed jobs, and cancel a run.
* Start a workflow that has a manual trigger, on a branch or tag you name, with inputs.
* Enable or disable a workflow.

These need the Actions permission on your installation of the Reason GitHub App. When it is missing, Reason says so. An organization owner accepts it on GitHub, in the organization's **Settings**, under **GitHub Apps**.

In the review pane, the **Checks** tab reads "All checks have passed", "Some checks were not successful" or "Some checks haven't completed yet".

## Merging

Ask the Reason to merge, or use **Merge** in the review pane, which offers **Create a merge commit**, **Squash and merge** and **Rebase and merge**. When a Reason merges and you name no method, it squashes by default.

Reason merges through GitHub, so your branch protection and repository rules still apply:

* On a base branch with a merge queue, the pull request joins the queue. The queue runs the required checks and merges when they pass.
* Elsewhere, the merge is refused while something blocks it, and Reason says what: the pull request is a draft, a check failed or is still running, a review is required, the branch conflicts with or is behind its base, or a repository rule blocks it.

To keep a Session from merging, start it through the API with `pull_request_policy` set to `draft_only`. Every pull request it opens is then a draft, and marking one ready, merging, queueing and adding labels are refused. Sessions and subagents it starts keep the setting.

## Loops woken by GitHub

A [Loop](https://ara-90a60a07.mintlify.site/docs/loops.md#github-events) can wake on an issue or pull request event in one connected repository: a new issue, a label added to an issue, a new pull request, a draft marked ready, new commits pushed, a review submitted and more. Filters narrow it by label, author or title, and each event opens its own Session in that repository.

Use one for standing work, such as triaging every new issue or fixing issues that get a label you choose. Ask a Reason in chat to set it up, or see [Loops](https://ara-90a60a07.mintlify.site/docs/loops.md) for the events and filters.

## API

Connecting GitHub is done in the web app, not through the API. The rest is in the API reference:

| Do this | Operation | Scope |
| - | - | - |
| List the repositories the Workspace's GitHub App can reach | [List repositories](https://ara-90a60a07.mintlify.site/api-reference/repositories/list-repositories.md) | `repos:read` |
| Read the commit at the tip of a branch, to confirm a merge or push landed | [Get a branch's head commit](https://ara-90a60a07.mintlify.site/api-reference/repositories/get-a-branchs-head-commit.md) | `repos:read` |
| Enable a repository for the Workspace | [Enable a repository](https://ara-90a60a07.mintlify.site/api-reference/repositories/enable-a-repository.md) | `repos:write` |
| Remove a repository's enablement. This does not delete the repository or revoke the GitHub App's access | [Disconnect a repository](https://ara-90a60a07.mintlify.site/api-reference/repositories/disconnect-a-repository.md) | `repos:write` |
| Start a Session on a repository, a branch or a pull request | [Create a session](https://ara-90a60a07.mintlify.site/api-reference/sessions/create-a-session.md) | `run` |
| Wake a Loop on a GitHub event | [Create a Loop](https://ara-90a60a07.mintlify.site/api-reference/loops/create-a-loop.md) | `automations:write` |

## Limits

* GitHub is the only source-control provider. GitLab support has been retired.
* GitHub Projects (boards) are outside the connection. To work on a project, a Reason uses a GitHub token of your own that has project access, stored as a [secret](https://ara-90a60a07.mintlify.site/docs/vault.md).
* Mentioning Reason in a GitHub comment does not start work. Start it from Reason, from [Slack](https://ara-90a60a07.mintlify.site/docs/slack.md) or with a Loop.
* A Session follows its pull request for at most 30 wakes, and stops after 7 days without activity.
* A GitHub Loop names one repository.


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.