Skip to content

Connect GitHub (GitHub App) ​

The PhillipCLI GitHub App links your GitHub organization to your PhillipCLI organization. You install it once, and it does three things:

  • Auto-join. Members of your GitHub organization join your PhillipCLI organization when they sign in with GitHub, with the role you choose.
  • Repositories. Tara lists the repositories you gave the app, and a repository counts as yours only when it is in the installation.
  • Issues and PRs. Ryoma and Bandum sync tasks and PRs with a short-lived, read-only token that Tara requests from GitHub. Nobody pastes a personal token.

The app only reads. It asks for read access to Contents, Issues, Pull requests, and Metadata, plus read access to your organization's members.

Who can connect ​

You need both of these:

  • You are an Owner or Admin of the PhillipCLI organization.
  • You are an owner of the GitHub organization (or the GitHub account itself, if you install on your personal account). GitHub shows the installation to ordinary members too, so Tara checks that you really own the account.

One installation links to one PhillipCLI organization, and one PhillipCLI organization links to one installation.

Install ​

  1. In Tara, open Settings › Source hosts and click Connect GitHub. From the terminal, run ph org github connect.
  2. On GitHub, choose the account to install on. Choose All repositories or Only select repositories.
  3. Click Install & Authorize. GitHub asks you to authorize the app too. Tara uses that step to confirm who you are.
  4. GitHub sends you back to Tara, and the page shows the account, the repositories, and the auto-join setting.
After the install, the GitHub section shows the account, the auto-join setting and the repositories the app can see.

The install link is valid for 15 minutes and works only for the person who started it. If you wait longer, start again.

To add or remove repositories later, change the app's repository access on GitHub. Tara picks the change up when GitHub reports it, or click Sync now (ph org github sync).

Let people join on their own ​

Under Auto-join, choose who may join when they sign in with GitHub.

SettingWhat happens
Off (default)Nobody joins automatically. You invite people.
ViewerMembers of the GitHub organization join as Viewers. Viewers are free and take no seat.
MemberThey join as Members and take a seat.

Auto-join works only when the app is installed on a GitHub organization, and it never gives Admin or Owner. Change it with ph org github auto-join off|viewer|member.

  • If no seat is free, sign-in still works. The person is listed on the GitHub page as skipped, and you can free a seat or invite them.
  • Someone who leaves the GitHub organization loses access to the PhillipCLI organization, but only if they joined this way. Owners, invited people, and people you added by hand stay.
  • If an Admin removes a person, or the person leaves on their own, auto-join does not bring them back. Invite them again to undo that.
  • Disconnecting turns people who joined this way into ordinary members.

Tara reads membership from its own copy, which updates when GitHub reports a change, every hour, and when you click Sync now. Every join and removal appears in the audit log.

Repositories, tasks, and PRs in Ryoma and Bandum ​

Once connected, add the repositories to a project (ph project edit <key> --add-repo owner/repo). Ryoma and Bandum then read that project's issues and PRs through the installation. Only repositories in the installation work. For a repository outside it, Tara refuses to issue a token.

Tokens last about an hour, cover only the repositories asked for, and are logged. Members' personal tokens can't request them. Only the services (Ryoma and Bandum) and Owners or Admins can.

Connect from the terminal ​

bash
ph org github                      # status, auto-join role, repositories, people skipped
ph org github connect              # print the install address and open it
ph org github auto-join member     # off, viewer, or member
ph org github sync                 # refresh repositories and members now
ph org github unlink --yes         # disconnect

When something goes wrong ​

CodeMeaning and what to do
installation_not_accessibleYour GitHub account can't see that installation. Sign in to GitHub with an account that can install apps on the organization.
not_account_ownerOnly an owner of the GitHub organization can connect it. Ask an owner to run the install.
repo_not_in_installationThe repository isn't in the installation. Add it to the app's repository access on GitHub, then sync.
github_not_linkedThis organization has no installation. Connect GitHub first.
installation_suspendedThe installation is suspended on GitHub. Unsuspend it in the GitHub organization's settings under GitHub Apps.
bad_stateThe install link expired or belongs to someone else. Start again from Connect GitHub.
installation_boundThat installation is already linked to another PhillipCLI organization.
org_already_linkedThis organization is already connected. Disconnect it first.

Further reading ​