# GitHub (AI pull requests)

Connect a GitHub repository to Usero and two things happen. Your GitHub issues flow into the feedback inbox, and from any feedback
item you can have Usero open a pull request with a working first pass at the fix. You review the PR and merge it. This is the part
of Usero that turns a user report into shipped code.

Connection is a GitHub App install, not a personal access token and not classic OAuth. You install the Usero app on the repos you
choose, and Usero acts through that installation.

## What it does

- **Issue import.** Existing and new issues in the connected repo become feedback items in your inbox, so reports from GitHub sit
  next to widget, email, and Slack feedback and feed the same clustering and analysis.
- **AI-authored PRs.** From a feedback item, click **Create PR**. Usero reads the repo, writes a fix on a new branch, and opens a
  pull request. The PR links back to the feedback (and to the original issue, if the feedback came from one).

## Prerequisites

- A Usero account. Anonymous visitors can browse but cannot connect GitHub or create PRs; the buttons prompt you to sign up first.
- A GitHub repository you can install a GitHub App on (you need admin rights on the repo or org to approve the install).
- The repo should contain the code you want changed. Usero writes against the default branch.

## Connect GitHub

1. Open your project, then go to **Integrations** (the URL is `usero.io/YOUR_CLIENT_ID/integrations`). To open your own
   integrations page, [go here](/integrations).
2. Find the **GitHub** card and click **Connect GitHub**.
3. You land on GitHub's app install screen. Choose the account or org, then pick **All repositories** or **Only select
   repositories** and choose the repos you want Usero to work in. Approve the install.
4. GitHub sends you back to Usero. If the install grants access to exactly one repository, Usero configures it for you. If it
   grants access to several, you pick one in the next step.

You can also start the install from **Settings**, in the GitHub section. The card shows **GitHub App Installed** or **GitHub App
Not Installed** so you can confirm the connection at a glance.

## Choose the repository

PRs are created against one repository per project. After the app is installed:

1. Open **Settings** and scroll to the GitHub section (or use the `#github` anchor).
2. Under **Select Repository**, pick the repo from the dropdown. Only repos you granted the app access to appear here.
3. The selected repo shows as `owner/repo` with a link. To switch later, click **Change Repository**.

If the dropdown is empty, the install did not grant access to any repo. Re-run the install from the GitHub card and grant access
to at least one repository.

## Import issues (optional)

Once a repo is selected, you can pull its issues into the inbox.

1. In the GitHub section of **Settings**, find **Import GitHub Issues** and turn the switch on.
2. Issues from the repo are imported as feedback items and run through the same AI analysis as everything else.
3. **Label filter (optional):** restrict the import to issues carrying specific labels. Leave it empty to import every open issue.
   The label picker lists the real labels from your repo.

New issues opened after you enable import are picked up on an ongoing basis, so you do not have to re-run a backfill for each one.

## Create a PR from feedback

1. Open any feedback item in the inbox.
2. Click **Create PR**. The button shows **Creating...** while the request is queued.
3. Usero creates the PR record immediately and starts generating the fix in the background. You are taken to a status page for
   that PR. Generation takes a few minutes; the page updates as it moves from queued to ready.
4. When it is ready, follow the link to the pull request on GitHub, review the diff, and merge if it looks right.

If the repo is not connected yet when you click **Create PR**, Usero sends you to the GitHub install flow first and brings you
back to the same feedback item afterward, so you do not lose your place.

PR creation is idempotent. Clicking **Create PR** on the same feedback item twice does not open a second pull request; you are
returned to the existing one.

## What the PR looks like

- **Branch:** a fresh branch named from the page and a timestamp, for example `feedback/checkout-form-1718291503`. Usero never
  commits to your default branch directly.
- **Title:** reflects the kind of feedback, for example a `Fix:` prefix for a reported bug or a `Feature:` prefix for a request.
- **Body:** the user's comment and the page or URL they were on, the environment, device context, a recommended action, and a link
  back to the feedback item in your dashboard. If the feedback was imported from a GitHub issue, the body includes `Fixes #NNN` so
  merging closes the issue.
- The PR is a first pass written by AI. Treat it as a draft to review, not a change to merge blind.

## Troubleshooting

**"Repository not configured."** The app is installed but no repo is selected. Go to **Settings**, GitHub section, and pick a repo
under **Select Repository**.

**No repositories in the dropdown.** The install did not include any repo Usero can reach. Re-run **Connect GitHub** and grant the
app access to at least one repository, or widen an existing install from the repo's or org's GitHub settings.

**The Create PR button is missing or disabled on a feedback item.** Not every feedback source can become a PR. Captures that lack
the context to act on (for example a raw highlight grab) do not offer PR creation. Items with a page, a comment, and enough
context do.

**"GitHub App not installed" when configuring a repo.** The installation was removed or never finished. Click **Connect GitHub**
again from the GitHub card and complete the GitHub install screen.

**You hit a PR limit.** PR creation is metered by plan. If you have used your allowance for the period, the PR page shows an
upgrade prompt instead of generating. Upgrade or wait for the period to reset.

**A PR fails to generate.** Generation can fail on infrastructure or repo-specific issues. The PR is marked failed on its status
page. Try again from the feedback item; if it keeps failing, [contact us](/contact?subject=GitHub%20AI%20PR%20generation) with the
feedback item link.

## Next

- [Integrations overview](/docs/integrations)
- [Find your clientId](/docs/find-your-client-id)
- [POST /api/feedback reference](/docs/api/feedback)