# GitHub integration

Install the Annot8 GitHub App, choose a repository, and turn feedback into GitHub issues.

Source: https://docs.annot8.app/docs/integrations/github



**Pro and above.** A workspace admin authorizes GitHub, installs the Annot8
GitHub App on the repositories it should reach, and picks one. There's no
personal access token to create or paste.

## Connect [#connect]

<Steps>
  <Step>
    ### Start from Integrations [#start-from-integrations]

    **Integrations** in the sidebar → **GitHub** → **Continue with GitHub**.
  </Step>

  <Step>
    ### Authorize and install the app [#authorize-and-install-the-app]

    GitHub asks you to authorize Annot8. If the Annot8 GitHub App isn't installed on
    your account or organization yet, the dashboard shows **One more step: install
    the app**. Install it and grant access to the repositories Annot8 should use,
    either all repositories or only the ones you select.

    Installing on an organization needs an organization owner, or approval from one.
  </Step>

  <Step>
    ### Choose a repository and base branch [#choose-a-repository-and-base-branch]

    Back in the dashboard, pick the repository and its **base branch**. The branch
    defaults to the repository's default branch. [Agent](/docs/ai/overview) pull
    requests branch off this base and open as drafts.
  </Step>

  <Step>
    ### Save and test [#save-and-test]

    **Save** runs a test straight away. The integration row then shows **Working**
    or the error GitHub returned. Use **Test** at any time to check again.
  </Step>
</Steps>

Once saved, the connection applies to **every project** in the workspace. To
keep a project out of GitHub, switch it off under **Project → Integrations**.

<Callout type="info">
  Connected GitHub with a personal access token before guided setup arrived? The
  integration row shows **Reconnect needed**. Choose **Reconnect** and authorize
  GitHub. The existing connection is updated in place, so there's no need to
  disconnect first.
</Callout>

## Two ways issues get created [#two-ways-issues-get-created]

**Automatically**, for every new thread on a project where GitHub is on. The
issue is titled `[Feedback] <comment>`, with the author, the comment, and a link
to the page in the body.

**On demand**, from a single thread: right-click it in the inbox and choose
**Create issue → Create GitHub issue**, or use **Links** in the thread's detail
panel. This issue carries the full thread context: page path and URL, issue
type, priority, status, expected and actual behaviour, the element selector,
and the page title.

<Callout type="warn">
  With GitHub on, every piece of feedback on that project becomes an issue. On a
  repository where issues are your actual backlog, switch GitHub off for the
  project and create issues on demand instead.
</Callout>

## Permissions [#permissions]

Annot8 can only reach the repositories the GitHub App was granted. It reads the
repository you choose, creates issues in it, and can open draft pull requests
for Agent fixes you approve.

The authorization belongs to the admin who connected it. If they leave the
workspace or revoke Annot8 in GitHub, the row shows **Reconnect needed**, and
another admin can **Reconnect** with their own account. To switch accounts at
any time, open **Configure** and choose **Use a different GitHub account**.

## Different repositories per project [#different-repositories-per-project]

Under **Project → Integrations**, choose **Route…** next to GitHub, pick a
different repository and branch, and **Save route**. The repository must be one
the GitHub App can access. **Use workspace default** removes the route again.

## Troubleshooting [#troubleshooting]

**No repositories listed.** The GitHub App has no repository access yet. Choose
**Update access** and grant at least one repository.

**"That GitHub repository is not available to Annot8."** The app's repository
access no longer includes it. In GitHub, open the Annot8 app's installation
settings and add the repository back, or pick a different one.

**"Your GitHub connection expired."** Choose **Reconnect** on the integration
row and authorize again.

**Issues aren't created.** Check that issues are enabled on the repository, then
check the integration row's status for the error GitHub returned.