SuperCIDocumentation

How it works

The three parts of SuperCI (a dashboard, a control plane in your cloud, a machine per job) and what happens from a push to a finished job.

SuperCI has three parts. All of them run in accounts you control; there is no SuperCI service in between.

The dashboard

A program on your computer, started with npx @superci/cli. It is where you set things up and look at jobs. It answers only on your own computer and keeps nothing between runs: no settings file, no saved sign-in. What it shows, it reads from your cloud and your control plane each time.

The control plane

A small program in your own cloud account, deployed by the dashboard:

WhereWhat it is
CloudflareA Worker with a Durable Object for its state
AWSA Lambda function with a function URL, a DynamoDB table and a two-minute schedule
ModalAn app with a web endpoint, its state in Modal Dicts

It does three things:

  1. It receives job events from GitHub and GitLab, and checks they are really from them.
  2. It starts a machine for each job, in the provider your order picks.
  3. It cleans up: machines whose job never came, and machines past the time limit.

It holds the settings you make in the dashboard (the order, limits, connections) as its own secrets. The dashboard updates it with one click when a new version is out.

A machine per job

Every job gets a machine of its own, of the size its label asks for. The machine registers as a runner for exactly that job, runs it, and is ended when the job ends. Nothing is shared between jobs, and nothing is kept running in between.

A job may run for up to 70 minutes. The limit is enforced by the machine itself, so it holds even if the control plane is unreachable.

From a push to a finished job

  1. You push. GitHub queues a job whose runs-on is superci.
  2. GitHub tells your control plane about it.
  3. The control plane goes down your list of providers and starts a machine at the first one that can run the job.
  4. The machine starts GitHub’s runner, registered for this one job.
  5. The job runs. Its logs are on GitHub, as always.
  6. The job ends, the machine is ended, and the dashboard shows what it cost.