GitHub · SuperCI

SuperCI runs GitHub Actions jobs on machines in your own cloud. It connects to GitHub through a GitHub App that is yours: the dashboard creates it in your organization, and nothing is shared with a third party.

For a server of your own, see GitHub Enterprise.

Connect an organization

Under Repositories, choose GitHub and name the organization (or your own account).

Create the App. The dashboard opens GitHub’s own page with the App filled in. You press Create.
Install it. GitHub asks where: all repositories, or the ones you pick.

You come back to the dashboard with the organization connected.

GitHub lets only an organization’s owners create its App. If you are not one, the dialog has a note to copy and send to an owner. In a terminal:

superci connections create github acme            # opens GitHub's pages
superci connections create github acme --dry-run  # prints the note for an owner

Run a job

In a workflow, name your label:

jobs:
  test:
    runs-on: superci
    steps:
      - uses: actions/checkout@v5
      - run: npm test

A larger machine, Arm, a GPU or Windows go in the label: see Labels and machines.

What the App may do

Permission	For
Self-hosted runners: write (organization)	Registering a runner for each job, for that job alone.
Actions: write	Reading a job’s log for the dashboard, and running a job again when AWS took its spot machine back.
Metadata: read	Listing the repositories it is installed on.

It hears one event, workflow_job: a job was queued, started or finished. It cannot read your code.

The App is private to its owner and is named after your CI. Its key is kept in your control plane’s secrets, nowhere else.

On a personal account GitHub has no organization runners, so the App asks for Administration: write on its repositories, which is broad. Prefer an organization.

One runner per job

Each job gets a fresh machine and a runner that GitHub accepts for exactly one job. When the job ends, the machine is gone.

GitHub gives a waiting job to any idle runner with its label, so two jobs with the same label, queued together, may run on each other’s machines. Those are the same size.

Several organizations

Repositories → Add an organization connects another. Each has its own App, and their jobs share your providers and limits. One control plane can serve github.com and a GitHub Enterprise server at once.

Public repositories and forks

Jobs from public repositories are refused unless you allow the repository, because anyone can open a pull request there. Even then, a fork’s pull request is refused. See Public repositories.

When a job never starts

The label. The job’s runs-on must be one of your labels: superci labels list.
The repository. The App must be installed on it. Under Repositories, check that it is listed.
What GitHub sent. superci deliveries list shows the events GitHub says it sent to your control plane, with what each got back.

SuperCI also looks for queued jobs GitHub never told it of, so one lost event does not lose a job.

Disconnect

superci connections delete github acme --confirm

That uninstalls the App from the organization. Change the runs-on of its workflows first: a job that still names your label would wait for a runner that never comes.

The App itself stays listed in the organization’s settings on GitHub, under GitHub Apps, where you can delete it.