# Keep an app's code in your GitHub

Topline can send each app's code to a repository in your company's GitHub.
Every saved version becomes a commit on the repository's `main` branch, and
the app shows your GitHub checks (CI) on it. Topline keeps the main copy: you
keep building in Topline, and GitHub gets an up-to-date copy.

This is available when GitHub is turned on for your organization. If you don't
see **Account > GitHub**, ask your Topline contact.

## Who needs what

A single person needs to do anything on GitHub, and only once.

| Who | Needs a GitHub account? | What they do |
| --- | --- | --- |
| A GitHub owner of your organization | Yes, an owner of the GitHub organization | Installs the Topline app on GitHub, once, and creates an empty private repository for each app |
| A Topline account admin | No (can be the same person as the GitHub owner) | Connects GitHub in Topline and chooses which projects can use each repository |
| Builders (anyone who can edit an app) | **No** | Picks a repository for an app, inside Topline |
| Everyone else | No | Nothing |

Builders never sign in to GitHub. Topline writes the commits as its own GitHub
app, so a commit shows up as made by the Topline app, with the app version in
its message.

## Connect GitHub (once)

1. In GitHub, create an **empty, private** repository for the app, without a
   README. Topline's first push needs it empty, and it never sends code to a
   public repository.
2. In Topline, an account admin opens **Account > GitHub** and selects
   **Connect GitHub**.
3. GitHub opens. Choose your organization, choose **Only select
   repositories**, pick the repositories Topline may use, and install. Then
   accept the authorization GitHub asks for. The person doing this must be an
   owner of that GitHub organization.
4. You come back to **Account > GitHub**, which finishes the connection and
   shows the organization.

To give Topline more repositories later, use **Manage on GitHub** next to the
organization, then add them there.

## Choose which projects can use each repository

On **Account > GitHub**, select **Choose projects** next to a repository and
pick the projects whose apps may use it. Each repository holds a single app's
code. Removing a project pauses any app in it that was using the repository.

## Send an app's code (builders)

- **New app:** in the create-app dialog, under **Where the code lives**, pick
  the repository.
- **Existing app:** open the app and select **GitHub** in its header, pick the
  repository, and choose what the first push sends:
  - **Latest version only** (recommended): a single commit with the current code.
  - **Full version history**: a commit per saved version, up to the newest 100.

After that, each saved version is sent within a few seconds. The GitHub panel
shows **Up to date**, the latest commit, and its checks. A project's
**Settings > GitHub** tab lists the repositories the project can use.

## When sending pauses

Topline never force-pushes and never overwrites work in GitHub. When something
would get in the way, it pauses the app and says why in the GitHub panel. Fix
the cause, then select **Retry**.

| What the panel says | What to do |
| --- | --- |
| Someone pushed to main outside Topline | Topline won't overwrite their work. Undo or move that commit off `main`, then Retry. Bringing outside edits back into Topline is coming later. |
| The main branch is protected / a ruleset blocks direct pushes | Allow the Topline app to push to `main`, or use a repository without that rule. |
| This repository already has commits | Use a new, empty repository. |
| This repository is public / archived | Make it private / unarchive it. |
| The code includes GitHub workflow files | The Topline app can't change `.github/workflows`. Remove those files from the app. |
| The code holds what looks like a credential | Remove the key or password from the app's code and save a new version. |
| An admin hasn't made this repository available to this project | An admin adds the project under **Choose projects**. |

## Disconnect

- **A single app:** in the app's GitHub panel, select **Disconnect**. The
  repository and its history stay in GitHub.
- **Your whole GitHub organization:** an admin selects **Disconnect** next to
  it on **Account > GitHub**, or uninstalls the Topline app in GitHub. Apps
  using it pause.

## Security

- The Topline app only asks GitHub for these permissions: read and write
  repository contents, and read metadata, checks and commit statuses. It never
  asks for permission to change GitHub Actions workflows.
- It can reach only the repositories you selected when installing, and each
  push uses a short-lived token for that repository.
- Before each push, Topline scans the code for keys and passwords and pauses
  instead of sending them.