GitHub

The Watari GitHub App gives Watari read access to your repositories, so it can find where an issue lives in your code, and write access to open draft fixes as draft pull requests, nothing more.

Why a GitHub App, not a personal access tokenCopy Anchor Link

A GitHub App installation is scoped to an organization and to specific repositories. Any organization admin can install or uninstall it in one click from GitHub's settings, and revoking it immediately cuts Watari's access to every repo in that installation. Personal access tokens are user-bound, harder to revoke cleanly, and carry broader scope than Watari needs.

Installing the AppCopy Anchor Link

What the App can doCopy Anchor Link

The GitHub App requests the minimum permissions Watari needs:

The App does not have permission to delete branches, force-push, or modify repository settings.

Getting your code readyCopy Anchor Link

After you connect a repository in Watari, Watari reads it and gets it ready to search. For a typical SaaS repository this takes a few minutes. Large monorepos take longer; progress is visible under Codebase in the dashboard, and the repository reads Ready when it is done.

Each push to the default branch is picked up automatically, so Watari keeps searching your latest code without any manual action.

Filing issues in GitHubCopy Anchor Link

Filing is optional. Open Settings → Connected tools → GitHub → Configure and turn on File issues in GitHub, then choose the repository and which issues to file: only the ones Watari found in your code (recommended), or every issue. Turn the switch off and Watari files nothing in GitHub, while finding issues in your code and drafting fixes keep working. The repository you chose is kept, so turning filing back on restores it.

Picking up issues from GitHubCopy Anchor Link

If your team tracks customer problems as GitHub issues rather than in a support desk, Watari can read them the same way it reads a support ticket. This is off until you turn it on, because installing the App for code and pull requests is not the same as asking Watari to read your issues.

Before you startCopy Anchor Link

• Connect the repository first. Watari picks up issues only from repositories you have connected under Codebase. A repository the App can merely see is not enough, and each connected repository counts toward your plan's repository limit, including one you use only for issues.
• Only an owner or admin of your Watari workspace can change these settings.
• Decide how public the repository is. On a private repository, anyone who can write an issue is on your team. On a public one, anyone on the internet can. Watari handles the two differently (see Public repositories below), and the settings dialog marks every repository that is not private.
• Give the people who file issues a format to follow. An issue with a title and one line is hard to find in code. The free bug report template lists the nine fields that matter and copies the result as Markdown for the issue body.

Set it upCopy Anchor Link

1. Open Settings → Connected tools → GitHub → Configure and turn on Pick up issues from GitHub Issues. The pickup settings appear once it is on.
2. Choose the repositories to read issues from: one or more of your connected repositories. Watari looks for an issue in every repository you connected, and reads nothing from repositories you leave unticked.
3. Choose how issues are handed to Watari. You can combine any of these:
   • Label. Someone adds a label you list, such as watari. This is the simplest way to hand over one issue at a time, and it notifies nobody.
   • Mention. Someone types @watariai in the issue's description or a comment. Works on any issue, new or old. Mentioning it again in a comment on an issue Watari already has, with where to look ("@watariai the export runs in reports/csv"), starts it again with that detail when Watari stopped without a draft fix or found the code and is waiting to draft, and Watari replies that it is trying again. A mention with nothing else in it gets a reply with where the issue stands and a link to it in Watari.
   • Assignment. GitHub does not let apps appear in the assignee list. If your team prefers assigning, enter the login of a GitHub account you own, and assign issues to that account. A label works without one.
   • Every new issue. Watari picks up each issue when it is created in one of those repositories. Existing issues are never picked up this way, so switching it on does not pull in your backlog. Add labels to narrow it to new issues that carry one of them.
4. Save. Then label one test issue in one of those repositories (or mention @watariai on it) and watch it appear under Issues within a minute or two.
5. Open the dialog again to see the Recent issues list. It shows each issue Watari has received from those repositories, what your saved settings did with it and, for one that was skipped, why. Change a setting and the list shows what the new one would do with the same issues before you save it. The list starts empty: it fills with issues that are created, edited, labelled or commented on after pickup is on, and does not list the issues you already had.

If you later reconnect Watari to a different GitHub App installation, issue pickup is switched off and its repository list is cleared, because those repositories belonged to the previous installation. Choose the repositories again to turn it back on. Reconnecting to the same installation changes nothing.

Public repositoriesCopy Anchor Link

On a repository that is not private, Watari acts only on a mention, label or assignment from someone with write access to it: an owner, a member of your organization, or a collaborator. Someone outside your team cannot have an issue picked up by typing the handle, and an issue template that applies a label on their behalf does not count either. Their comment on one of your own issues does not start anything, even when that issue already carries your label, and what they wrote is not read. A maintainer hands such an issue over the same way as any other: by adding the label, assigning it, or mentioning Watari in a comment. Anything skipped for this reason is listed in the dialog as "came from someone outside your team", so nothing is silently ignored.

Internal repositories are treated like public ones, since everyone in your enterprise can read them.

What happens nextCopy Anchor Link

Watari works on each issue it picks up the same way as on a support ticket. Questions that are not code defects (a configuration change, a usage question, a how-to) get a suggested answer for your team instead of a draft fix. An issue counts toward your Mapped Issue allowance only if Watari finds it in your code. If you pick up every new issue on a trial, which includes a limited number of Mapped Issues, start with a label or with mentions so the allowance goes to the issues you care about most.

An issue Watari picked up is its own issue: Watari posts progress on it and does not file a second one beside it, in any repository, even when issue filing to GitHub is switched on. Issues Watari files for reports that came from somewhere else (a support desk, for example) are never picked up as new reports, so the two features can run in the same repository.

Watari comments on each issue it picks up, and keeps it to what someone needs to read: that it is looking for the cause, then "Your move · Ready for a fix" once it finds the code, "Your move · Review the fix" once it drafts one, "Your move · Needs an engineer" if it cannot find the code or stops without a fix, and "Your move · Watari asks" when it is missing one fact. The full list is in What Watari's comments say. Comments never list file paths or scores; those are in Watari, one click from the comment. When the draft fix opens, Watari adds a "Source issue" comment on its pull request, so the pull request points at the issue and GitHub shows the pull request on the issue's timeline. It does not use a closing keyword: merging the pull request never closes your issue for you.

On a repository that is not private, comments carry where the issue stands and a link to Watari only: no pull request link, no investigation notes, no suggested answer, and no text from any other report. The customer update (what went wrong and how it was fixed) is posted on the issue only when its repository is private; otherwise it stays in Watari for your team to pass on. You review and approve that update on the issue's page in Watari first, and the page reminds you of this before you approve. A "Source issue" comment is also left off when the issue and the pull request are in different repositories and the pull request's repository is not private, so the name of one repository is never published in another. You can turn Watari's comments off in the same dialog.

A transferred issue is not treated as new in the repository it arrives in. If Watari was already working on it, it follows the issue to its new home; otherwise, mention Watari in a comment to hand it over.

CODEOWNERS-driven reviewer routingCopy Anchor Link

If your repository has a .github/CODEOWNERS file, Watari uses it to assign reviewers to draft fixes automatically. When an issue is found in a file owned by a specific team or individual, that owner is added as a reviewer.

The CODEOWNERS rule behind each reviewer is shown on the issue page.

If your repository does not have a CODEOWNERS file, an owner or admin can ask Watari to suggest owners from recent changes: open the repository under Codebase, choose Who owns this code, then Suggest owners. Use these owners opens a pull request that adds the file; Not right turns the suggestion down. You are not required to adopt it. Draft fixes still open; they just don't have reviewers assigned automatically. Members can read who owns each folder but cannot ask for or use a suggestion.

Branch protection prerequisitesCopy Anchor Link

Watari opens draft fixes against your repository's default branch (usually main). If your branch protection rules require status checks to pass before merge (for example, CI must be green), Watari respects those rules: the pull request stays a draft and Watari watches CI as checks run.

Watari does not bypass branch protection. If your protection requires a minimum number of approvals, the pull request will not merge until human reviewers give them.

Multi-repo supportCopy Anchor Link

If an issue is found in code across more than one repository in the same GitHub App installation, Watari opens linked draft fixes in each repository and tracks them together. The customer update is held until every one of them merges and a successful production deploy is confirmed in every affected repository.

DisconnectingCopy Anchor Link

Uninstalling the Watari GitHub App from your GitHub organization settings immediately revokes access to all repositories in that installation. Past issues, where they were found in your code, and customer updates remain in your Watari workspace for 30 days after disconnect, then are purged. You can reconnect at any time.

To remove a single repository from Watari without uninstalling the App entirely, update the repository selection in the GitHub App settings on GitHub. Watari stops reading and opening pull requests in any repository removed from the selection.

---

Next: Routing and notifications: Slack, Microsoft Teams, Linear, and Jira setup: configure team chat, Linear, Jira, and GitHub Issues sync.