---
title: GitHub
description: Connect your repositories, and have agents push branches and open pull requests as you.
---

Polaris works on your GitHub repositories through the Polaris GitHub App.
Agents work only in the repositories you choose, and they push branches and
open pull requests under your name, so their work shows up on GitHub like your
own and follows the same rules.

![Settings, GitHub, with one connected GitHub organization and Refresh, Update repository access and Disconnect buttons.](/docs/screenshots/github.webp)

## Connect GitHub

The first time you sign in, setup walks you through it: sign in with GitHub,
select **Install on GitHub**, choose where to install the App, and select the
repositories agents can work in. Back in Polaris, pick the ones that become
Projects. If you joined a team, an owner has usually done this already.

To connect another GitHub account or organization later, open **Settings →
GitHub** and select **Connect GitHub repository** or **Add GitHub connection**.
In a team organization, only Owners and Admins see this page, and it connects a
GitHub organization. Repositories under your own GitHub account go in your
**Personal** organization.

## Choose repositories

Agents reach only the repositories you select for the App. To add or remove
one, open **Settings → GitHub** and select **Update repository access**, which
opens the App's settings on GitHub. If the list doesn't change when you come
back, select **Refresh**.

## What the App can do

The App asks GitHub for the permissions below; GitHub shows the same list when
you install it. Repository permissions reach only the repositories you
selected, and agents never go beyond your own GitHub access.

| Permission | Access | Why Polaris asks for it |
| --- | --- | --- |
| Contents | Read and write | Clone your repository and push the branches and commits agents make. |
| Pull requests | Read and write | Open pull requests, reply to review comments, and update or merge them. |
| Issues | Read and write | Read issues for context, and open or comment on them. |
| Actions | Read and write | Read CI runs and logs to see whether a change passes, and re-run failed jobs. |
| Checks | Read and write | Read check results on commits and pull requests, and re-request checks. |
| Commit statuses | Read and write | See results other services report on commits, and report results of checks agents run. |
| Workflows | Read and write | Change files under `.github/workflows` to set up or fix CI. Workflows run with your repository's secrets, so review these changes carefully. |
| Discussions | Read and write | Read and reply to GitHub Discussions. |
| Merge queues | Read and write | Add a pull request to the merge queue and see its place. |
| Deployments | Read | See which version is deployed and find preview links. |
| Packages | Read | See which versions were published as packages. |
| Pages | Read | Check a repository's GitHub Pages site and its build status. |
| Dependabot alerts | Read | Find and fix vulnerable dependencies. |
| Metadata | Read | Required by GitHub for every App: repository names, owners and settings. |
| Members (organization) | Read | Request reviews from teams and see who belongs to the organization. |
| Email addresses (account) | Read | Sign you in with GitHub when your email is private, and know where to contact you about your account. |

Polaris also receives pull request updates from GitHub, which refresh a pull
request linked to a Session; see
[Pull requests and CI](/docs/pull-requests#find-your-sessions-pull-requests).

## Agents work as you

- **Under your name.** Agents use Git and the GitHub CLI as your GitHub
  account, so branches, commits and pull requests appear as yours. This holds
  in a Session you share, whoever sends the message.
- **Never more than you.** If you can only read a repository, agents can change
  files on the Machine, but GitHub refuses their pushes.
- **Your rules apply.** Branch protection and required reviews apply to agents
  as they do to you. Because agents can merge anything you can, protect your
  main branch if you want a person to approve every merge.

Under **Settings → Your account → General → Git**, two switches are on until
you turn them off: **Add Co-Authored-By to agent commits** credits Polaris on
commits agents make, and **Link pull requests to their Polaris Session** adds a
link back to the Session in pull requests agents open.

## When your GitHub organization needs approval

If your GitHub organization requires approval for apps and you aren't one of
its owners, GitHub sends your install request to them. Setup shows **Waiting
for an owner of your GitHub organization to approve Polaris.** You can close
the page: Polaris checks again when you come back, or select **Check again**.
To start right away, select **Use my personal GitHub account for now**.

## If it doesn't work

- **GitHub access needs attention** in a Session: the Session owner's GitHub
  sign-in expired. They select **Reconnect GitHub**. Agents can keep working on
  the Machine meanwhile.
- **GitHub access is temporarily unavailable:** wait a moment and try again.
- **A push is refused:** check that your GitHub account can write to the
  repository and that it's selected under **Update repository access**.
- **Pending** or **Needs attention** on a connection in **Settings → GitHub:**
  select **Refresh**. If it stays, select **Update repository access** and
  finish setup on GitHub.

If you revoke the Polaris GitHub App in your GitHub settings, agents lose
GitHub access; signing in to Polaris with GitHub again restores it. For other
messages, see [Troubleshooting](/docs/troubleshooting).