# GitHub

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](/docs/github-enterprise).

## Connect an organization

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

1. **Create the App.** The dashboard opens GitHub's own page with the App filled in. You press **Create**.
2. **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:

```sh
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:

```yaml
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](/docs/labels).

## 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](/docs/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.

More in [Troubleshooting](/docs/troubleshooting).

## Disconnect

```sh
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.