# Connecting GitHub

_Set up GitHub access for pull requests, CI, and Pro repository linking._

Free users connect through the local [GitHub CLI](https://cli.github.com/) (`gh`). Pro users can connect through the Treq GitHub App without installing `gh`. When `gh` is available on a Pro machine, Treq still uses it for some data fetching.

:::note[Work in progress]

The Treq GitHub App is still under development. App-backed flows such as connected-repo management and the merge queue are incomplete.

:::

## Confirm a GitHub Remote

Treq only enables GitHub UI when `origin` is a `github.com` remote:

```bash
git remote -v
```

SSH and HTTPS GitHub URLs both work. Remotes on other hosts keep ordinary [push](/docs/how-to/pushing-to-remote) behavior without Create PR or CI pills.

## Free: Install and Authenticate `gh`

Install the GitHub CLI, then authenticate on the machine that runs Treq:

```bash
gh auth login
gh auth status
```

Without a working `gh` session, Free-tier Create PR, View PR, the GitHub panel, CI status, and inline review threads stay empty or fail when invoked.

## Pro: Sign In and Install the Treq GitHub App

1. Open Settings → Integrations in the desktop app. If you are signed out, choose **Sign in with Browser** and finish the Treq account flow.
2. Choose **Manage GitHub**. That opens the web dashboard Integrations tab.
3. Start the GitHub App install from the dashboard. Treq mints a single-use install intent, then sends you through GitHub's install screen.
4. Pick the organization or user and the repositories the App may access.
5. Complete the callback so Treq records the installation and repository list.

Back in the desktop app, Connected repositories should list the repos the App can see for your plan. If a repo is missing, re-open Manage GitHub and adjust the App's repository access on GitHub.

Pro users do not need `gh` installed for App-backed connection. If `gh` is present and authenticated, Treq may still use it for some fetches.

## Enable the Merge Queue for a Repo

:::note[Work in progress]

The merge queue is not fully shipped. The Integrations toggle may appear while the end-to-end product is still incomplete.

:::

The merge queue needs Pro, an App-linked repository, and an opt-in under Settings → Integrations:

1. Open the repository in Treq.
2. Go to Settings → Integrations.
3. Under GitHub, turn on **Merge queue**, or choose **Enable merge queue** when the control is available.

If the toggle is missing, the page states the blocker: no GitHub remote, Free plan, or App not installed on that `owner/repo`. See [Using the Merge Queue](/docs/how-to/using-the-merge-queue).

## Verify the Connection

1. Open a non-default-branch [workspace](/docs/concepts/workspaces) that already has a commit.
2. Confirm **Create PR** appears in the workspace header, or **View PR** if a PR already exists.
3. Open **GitHub** in the sidebar and load Pull Requests for the repo.

## Next Steps

- [Creating and Viewing Pull Requests](/docs/how-to/creating-and-viewing-pull-requests)
- [GitHub Integration](/docs/concepts/github-integration)
- [Customizing Settings](/docs/how-to/customizing-settings)
- [Security and Privacy](/docs/security-and-privacy)