Skip to main content
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 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.
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.
  • A Reason’s defaults: 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.
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 can start somewhere else: 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: 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 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 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 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:

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.
  • Mentioning Reason in a GitHub comment does not start work. Start it from Reason, from Slack 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.