OwnCI

Your PR. Your Compute.

OwnCI is a small Go CLI that turns your Linux machine into a GitHub Actions self-hosted runner for one repository, with one command each to set it up, start it, stop it and remove it. It does not implement a CI protocol: it downloads, registers, supervises and cleans up the official actions/runner, and configures it so that every job runs inside a Docker container: either the job declares container: (host mode, the default), or OwnCI runs the runner itself in a container that jobs without container: use as their image (container-runner mode).

Status: MVP. Linux and WSL2 only. Tested end to end on WSL2 with Docker Desktop, amd64. Native Linux (Docker Engine) and arm64 builds are shipped and expected to work, but are not tested yet. Native Windows and macOS are not supported. The real-GitHub validation is described in docs/e2e.md; results are in docs/acceptance.md.

How it works

 GitHub Actions ◄──────────────► official actions/runner     (runs on your host, as you)
 (queues jobs, owns the PR check)        │  supervised by OwnCI: start / stop / status
                                         │  .env: ACTIONS_RUNNER_REQUIRE_JOB_CONTAINER=true
                                         ▼
                                job container (your local Docker)
                                         │
                                         ▼  after every job: OwnCI's job-completed hook
                                wipes the runner's _work (in a throwaway container)

• GitHub still owns workflows, queuing, scheduling and the check shown on the PR.
• ownci owns the runner's lifecycle: download + checksum verification, registration, process supervision, status, cleanup, uninstall.
• A job that does not declare container: is rejected by the runner. That is the isolation boundary OwnCI enforces and verifies; read Security for what it does not protect against. (In container-runner mode such a job runs in the runner's container instead; see below.)

Prerequisites

• Linux or WSL2 on amd64 or arm64 (tested: WSL2 on amd64), and a non-root user (the runner refuses root).
• Docker with a Linux daemon, reachable by your user:
  • WSL2 with Docker Desktop: Docker Desktop → Settings → Resources → WSL integration → enable your distro → Apply & restart. Without it, docker in WSL is a stub that fails.
  • Native Linux / Docker Engine in WSL: install Docker Engine and add yourself to the docker group (sudo usermod -aG docker $USER, then log in again).
• ICU for the runner: Debian/Ubuntu sudo apt-get install -y libicu-dev, Fedora sudo dnf install libicu, openSUSE sudo zypper install libicu. (bin/installdependencies.sh in the runner directory does the same.)
• A GitHub token with admin access to the repository, only for setup, uninstall --unregister and status --remote. In order of preference: GITHUB_TOKEN, GH_TOKEN, or gh auth login (the default scopes work for repositories you administer). A fine-grained PAT needs Administration: Read and write on the repository. The token is never stored.

Run ownci doctor to check all of this.

Install

curl -fsSL https://sparshlabs.com/ownci/install.sh | sh

The script (Linux and WSL2, amd64 and arm64) downloads the latest release, checks it against the release's SHA256SUMS and installs ownci into ~/.local/bin. OWNCI_VERSION pins a version and OWNCI_INSTALL_DIR picks another directory, e.g. … | OWNCI_VERSION=v0.1.0 sh. To remove OwnCI again: ownci uninstall --unregister --purge, then rm ~/.local/bin/ownci.

Or by hand: download the archive for your architecture and SHA256SUMS from the Releases page, then:

sha256sum -c --ignore-missing SHA256SUMS        # must print: ownci_<version>_linux_<arch>.tar.gz: OK
tar -xzf ownci_<version>_linux_<arch>.tar.gz
install -m 0755 ownci ~/.local/bin/ownci        # make sure ~/.local/bin is on your PATH
ownci version

Each archive carries a GitHub build-provenance attestation: gh attestation verify ownci_<version>_linux_<arch>.tar.gz --repo ashfaqc137/ownci.

Data lives in ~/.local/share/ownci by default (--data-dir, $OWNCI_DATA_DIR or $XDG_DATA_HOME/ownci override it). On WSL keep it on the Linux filesystem, not under /mnt/c.

Quick start

ownci doctor                              # everything PASS?
ownci setup --repo owner/name             # downloads + verifies the runner, registers it, installs isolation
ownci start --detach                      # runs in the background (without --detach: foreground, Ctrl-C stops)
ownci status --remote                     # online, idle

Then target the runner from a workflow. Both lines are required:

jobs:
  build:
    runs-on: [ownci]            # the opt-in label OwnCI registers (not "self-hosted")
    container: ubuntu:24.04     # mandatory: jobs without a container are rejected
    steps:
      - uses: actions/checkout@v4
      - run: make test

Stop contributing compute with ownci stop; ownci start brings the same registration back.

Run every job in a container (no container: needed)

Workflows written for GitHub-hosted runners usually have no container: line. With container-runner mode they run unchanged (to switch an existing runner: ownci stop, then ownci setup --force --mode container-runner):

ownci setup --repo owner/name --mode container-runner
ownci start --detach

jobs:
  build:
    runs-on: [ownci]           # no container: needed
    steps:
      - uses: actions/checkout@v4
      - run: sudo apt-get install -y jq && make test

How it works:

以上为 README 的开头部分。其余内容请阅读原文。 查看完整 README ↗