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
- In Tara, open Settings › Source hosts and click Connect GitHub. From the terminal, run
ph org github connect. - On GitHub, choose the account to install on. Choose All repositories or Only select repositories.
- Click Install & Authorize. GitHub asks you to authorize the app too. Tara uses that step to confirm who you are.
- GitHub sends you back to Tara, and the page shows the account, the repositories, and the auto-join setting.
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.
| Setting | What happens |
|---|---|
| Off (default) | Nobody joins automatically. You invite people. |
| Viewer | Members of the GitHub organization join as Viewers. Viewers are free and take no seat. |
| Member | They 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
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 # disconnectWhen something goes wrong
| Code | Meaning and what to do |
|---|---|
installation_not_accessible | Your GitHub account can't see that installation. Sign in to GitHub with an account that can install apps on the organization. |
not_account_owner | Only an owner of the GitHub organization can connect it. Ask an owner to run the install. |
repo_not_in_installation | The repository isn't in the installation. Add it to the app's repository access on GitHub, then sync. |
github_not_linked | This organization has no installation. Connect GitHub first. |
installation_suspended | The installation is suspended on GitHub. Unsuspend it in the GitHub organization's settings under GitHub Apps. |
bad_state | The install link expired or belongs to someone else. Start again from Connect GitHub. |
installation_bound | That installation is already linked to another PhillipCLI organization. |
org_already_linked | This organization is already connected. Disconnect it first. |