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.