Get started

Step 1

• Linux or WSL2 on amd64 or arm64, and a non-root user (the runner refuses root). Tested end to end on WSL2 with Docker Desktop (amd64); native Linux and arm64 are built but not yet tested. Native Windows and macOS are not supported.
• Docker with a Linux daemon that your user can reach. On WSL2 with Docker Desktop, enable your distro under Settings → Resources → WSL integration. On native Linux, install Docker Engine and add yourself to the docker group.
• ICU for the runner: sudo apt-get install -y libicu-dev on Debian/Ubuntu, sudo dnf install libicu on Fedora.
• A GitHub token with admin access to the repository, only for setup, uninstall --unregister and status --remote. OwnCI looks at GITHUB_TOKEN, then GH_TOKEN, then gh auth login. A fine-grained token needs Administration: Read and write on the repository. The token is never stored.

Step 2

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

The script downloads the latest release for your architecture, 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.

Download the archive for your architecture and SHA256SUMS from the Releases page, then verify and install it:

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.

With Go installed (see go.mod for the version), build the release configuration yourself:

git clone https://github.com/ashfaqc137/ownci.git
cd ownci
git checkout "$(git describe --tags --abbrev=0)"   # the latest release
make build                                      # builds bin/ownci
install -m 0755 bin/ownci ~/.local/bin/ownci

OwnCI keeps its data in ~/.local/share/ownci. --data-dir, $OWNCI_DATA_DIR or $XDG_DATA_HOME/ownci override it. On WSL, keep it on the Linux filesystem, not under /mnt/c.

Step 3

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

ownci doctor is read-only: it checks the platform, your user, the data directory, ICU, Docker and the isolation settings, and exits with code 3 if something fails.

Step 4

In host mode (the default), 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

Open a pull request and watch the check run on your machine. For workflows without a container: line, see container-runner mode.

Step 5

ownci stop                                # stop taking jobs; registration and files are kept
ownci start --detach                      # the same registration comes back
ownci uninstall --unregister --purge      # remove it from GitHub and delete OwnCI's files

ownci uninstall without flags only stops the runner and explains what is left. The binary itself stays; remove it afterwards with rm ~/.local/bin/ownci (or wherever OWNCI_INSTALL_DIR put it). See all commands.