Perch
Guide contents

Field guideGet set up

Authentication

Perch can use your GitHub CLI login or a token you provide. The permissions you need depend on what you do on GitHub.

Where Perch looks for a token

Perch calls GitHub's API directly. It uses the first token it finds in this list.

  1. GITHUB_TOKEN
  2. GH_TOKEN
  3. gh auth token
  4. token in ~/.perch/config.toml
  5. GITHUB_TOKEN, then GH_TOKEN, as your login shell exports them

Signing in from the desktop

If you open Perch from Finder or the Dock, it may miss variables you export in your terminal. Run gh auth login once to sign in from both places. Perch picks up a new GitHub CLI login or a change to the token setting on its next poll.

If the first four sources return nothing, Perch starts $SHELL as an interactive login shell and waits up to five seconds for the two variables. It tries this once per launch. Restart Perch after adding an export to your shell profile.

Required GitHub permissions

Your token needs permission to read your repositories and to read and update notifications. Other actions need write access on the repository where you take the action.

  • Contents: write lets you merge a pull request or push a branch from a clone Perch manages.
  • Pull requests: write lets you open a pull request, comment, approve, request changes, resolve a thread, or add a reaction to a PR or its comments.
  • Issues: write lets you react to an issue, close it, or use Close as issue.