# Connect GitHub

> Connect a GitHub.com account to AI CodeOps with OAuth or a personal access token, the scopes it needs, and what the platform does with your repositories.

Source: https://aicodeops.dev/docs/git/github

AI CodeOps works on your GitHub repositories through a connection you make once. Sessions then clone the repository, write the change on a new branch and open a pull request for review.

## Before you start

- A GitHub.com account with access to the repositories you want to use.
- GitHub Enterprise Server isn't supported. For Git servers you run yourself, AI CodeOps supports [GitLab](https://aicodeops.dev/docs/git/gitlab), [Gitea](https://aicodeops.dev/docs/git/gitea) and [Forgejo](https://aicodeops.dev/docs/git/forgejo).

## Connect with OAuth

1. In your workspace, open **Configure → Settings** and scroll to **Git Providers**.
2. On the **GitHub** card, choose **Connect**.
3. GitHub asks you to authorize AI CodeOps. Approve it, and you return to Settings with the account listed under **Connected Accounts**.

AI CodeOps asks GitHub for these OAuth scopes:

| Scope        | Why                                                                                                                            |
| ------------ | ------------------------------------------------------------------------------------------------------------------------------ |
| `repo`       | Read and write repositories you can access: clone, push a branch, open and merge pull requests. Includes private repositories. |
| `read:user`  | Show which GitHub account is connected.                                                                                        |
| `user:email` | Requested with the sign-in scopes; AI CodeOps doesn't read the address through this connection.                                |

If you see "GitHub sign-in isn't set up on this server", the platform's OAuth app isn't available. Connect with a token instead.

## Connect with a personal access token

On the GitHub card, paste a token into **or access token (no OAuth app)** and choose **Connect with token**. AI CodeOps checks the token against GitHub before saving it; a bad token gets "Token rejected — check the URL and key."

The token needs to read your user profile, read repositories, push branches, and create and merge pull requests. On GitHub that means:

- a **classic** token with the `repo` scope, or
- a **fine-grained** token for the repositories you want, with **Contents** and **Pull requests** set to read and write (Metadata read is included).

Personal access tokens are not refreshed. When the token expires on GitHub, disconnect and connect again with a new one.

## What AI CodeOps does with the repository

- **Browse:** **Develop → Repositories** lists the repositories the account can see, with their branches, files and pull requests.
- **Sessions:** a session clones the project's repository into its sandbox and writes the change there.
- **Branches and pull requests:** when a change is approved and passes its [quality gates](https://aicodeops.dev/docs/quality-gates), AI CodeOps pushes a branch named `codeops/run-<id>` and opens a pull request into the project's default branch. Commits are authored as "AI CodeOps".
- **Merge:** a pull request the console opened can be merged from the console. The release gate runs again first.

AI CodeOps doesn't register webhooks on your repositories or post review comments on GitHub.

## Your token and your access

- Connections belong to you, not the workspace. Each member connects their own account, and workspace permissions still decide what they can do.
- Tokens are encrypted at rest (AES-256-GCM) and are never written into a repository's Git configuration.
- To remove access, choose **Disconnect** next to the account. You can also revoke the app or token on GitHub.

## Next steps

- [Create a project](https://aicodeops.dev/docs/projects) from a GitHub repository.
- [Run your first session](https://aicodeops.dev/docs/sessions).
- [Troubleshooting](https://aicodeops.dev/docs/troubleshooting) if a connection shows **Expired** or a push is refused.