Skip to content

Connect GitHub or GitLab ​

Phillip, Bandum, and manual testing all work with issues and PRs under your name, so they need access to your GitHub or GitLab account. This page covers three tasks: signing in to Tara, letting Phillip connect to your repos, and creating a token yourself when you can't use the Authorize button. It takes about 5 minutes. Joining an PhillipCLI organization is a separate step, in Create or join an organization.

Sign in to Tara ​

Anyone with a GitHub account can sign in to Tara. Tara doesn't check which GitHub organization you belong to, and your PhillipCLI organization is separate from your GitHub one. Open Tara, click Continue with GitHub, and click Authorize. Then create or join an PhillipCLI organization.

Two other sources are available today. If your organization uses GitLab or OpenID Connect, an Owner or Admin can set up the organization's own SSO from the Portal (Organization SSO), and the sign-in button for it appears on the Tara sign-in page. The first time, GitLab asks whether to let Tara read your profile. Click Authorize Tara.

Tara asks only to read your profile, email, and list of groups.

Sign in other ways, and connect your company's GitHub

You can also sign in with Google or an email link, and join an organization automatically with a verified work email. See Sign-in options. An Owner or Admin can install the PhillipCLI GitHub App on the company's GitHub organization, so its members join on their own and Bandum and Ryoma read issues and PRs without personal tokens: Connect GitHub (GitHub App).

Connect your company's GitLab

An Owner or Admin can connect a GitLab group (gitlab.com or self-managed) with OAuth or a Group Access Token. Members then join on their own, and Bandum and Ryoma read issues and merge requests without personal tokens: Connect GitLab.

Let Phillip connect ​

In the project repo directory, run:

bash
ph connect

Phillip reads the host from the repo's origin, then looks for a way to connect in this order.

  1. A token already on your machine, from gh, glab, or git credential. Phillip always asks before using it.
  2. If an operator registered an application for Phillip, the browser opens the Authorize screen. Click to agree and you're done.
  3. For GitHub, if the machine can't open a browser (for example, a remote host), Phillip prints an 8-character code. Open github.com/login/device on another machine, enter the code, and click Continue.
  4. If none of the above works, Phillip asks you to paste a token. How to create one is in the next section.
Enter the code that Phillip prints in the terminal. Don't enter a code that someone else sends you.

Phillip stores the token in the machine's secret store and doesn't write it to the repo. Verify with ph kit check kit-scm-github --live or ph kit check kit-scm-gitlab --live.

Create a token yourself ​

You need to create a token only when Phillip asks you to paste one, or when manual testing on the Bandum website shows the Connect box. The token must be your own, because commits, comments, and approvals are made in your name.

PlatformToken typePermissions needed
GitHubFine-grained (recommended)Contents, Issues, and Pull requests all set to Read and write, on the project repo only
GitHubClassicThe repo scope
GitLabPersonal access tokenThe api scope, and you're a Developer or higher in the project

GitHub: fine-grained token ​

  1. Go to your avatar › Settings › Developer settings › Personal access tokens › Fine-grained tokens › Generate new token.
  2. Set a recognizable Token name, such as phillip-laptop, and choose an Expiration.
  3. Under Resource owner, choose the GitHub organization that owns the repo, not your personal account. Under Repository access, choose Only select repositories and then select the project repo.
  4. Under Permissions, click Add permissions, add Contents, Issues, and Pull requests, then change all three to Read and write.
  5. Click Generate token and copy the token right away, because GitHub shows it only once.
Choose the organization under Resource owner. If you don't see the organization, you may not have accepted the invitation.
Three Read and write permissions. Metadata is required and is always Read-only.

If the organization requires token approval, the token stays pending until an owner approves it. While it's pending, Phillip reports that the token has no access to the repo.

GitHub: classic token ​

If the organization doesn't allow fine-grained tokens yet, go to Personal access tokens › Tokens (classic) › Generate new token (classic). Set a Note, choose an Expiration, check the repo scope, and click Generate token. A classic token has access to every repo you can reach, so set a short expiration.

A classic token needs only repo checked. Leave the other scopes empty.

GitLab: personal access token ​

  1. Go to your avatar › Edit profile › Personal access tokens › Add new token.
  2. Set a Token name, such as phillip-laptop, and choose an Expiration date.
  3. Under Select scopes, check only api.
  4. Click Generate token and copy the token right away.
Check only the api scope. When the token expires, create a new one and run ph connect again.

With the token in hand, run ph connect again and paste it when asked, or run ph connect --method paste to go straight to the paste step.

Already have repositories? ​

If your company's repositories and issues already exist on GitHub or GitLab, you don't need to start from zero, and nothing is written to your repositories. An Owner or Admin does this once, after connecting GitHub (the GitHub App) or a GitLab group:

  1. Import repositories. On the Projects page, or in step 2 of the setup guide, click Import repositories. Tara lists the connected repositories that aren't in a project yet. Select the ones you want, and each becomes its own project (you can edit the key), or tick the option to put the selected repositories into one project. From the terminal: ph project import --all, or ph project import --repo owner/repo.
  2. Map your labels. Open Settings › Labels. The page lists the labels your repositories already use, such as bug, enhancement or in progress, with a suggested meaning for each (a status, a type or a size). Fix the ones that are wrong, then click Save and confirm. Phillip, Bandum and Ryoma apply the mapping when they read an issue, so the numbers fill in without relabeling anything. An issue that already has a status:, type: or level: label keeps it. In the terminal: ph org labels suggest, then ph org labels set --file map.json --confirm. If your repositories have no labels yet, the same step offers to create the standard set instead.
  3. Bring your team. With GitHub connected, ph org github auto-join member (or the Portal setting) lets members of your GitHub organization join when they sign in with GitHub. It never grants Admin or Owner. See Connect GitHub (GitHub App).

Ryoma then counts the period before AI from the earlier of the first telemetry and the day the project was created, so imported repositories show a "before" number right away.

When you hit an error ​

MessageWhat to do
After signing in, Tara shows Get started instead of your organizationYou aren't in an PhillipCLI organization yet. Create one, or ask an Owner or Admin for an invitation. See Create or join an organization
Tara says you must choose an organization (org_required)You belong to several organizations. Pick one in the switcher, or run ph login --org <slug>
Phillip says the token has no access to the repoThe token is missing the project repo or write permission. For a GitHub fine-grained token, check whether the token is waiting for owner approval
Phillip asks you to paste a token even though there's an OAuth appThe host in origin isn't registered by an operator. Tell your Owner or Admin, or paste a token to continue

Installing Tara yourself? See the developer site.