github-nix-ci is a simple NixOS & nix-darwin module (wrapping¹ the ones in nixpkgs and nix-darwin) for self-hosting GitHub runners on your machines (which could be a remote server or your personal macbook), so as to provide self-hosted CI for both personal and organization-wide repositories on GitHub.

• What it does
• Getting Started
  • 1. Create system configuration for the machine
  • 2. Create personal access tokens
  • 3. Configure github-nix-ci runners
  • 4. Add the workflow to your repositories
• Production
  • Common issues
• Examples

We provide a NixOS and nix-darwin module¹ that can be imported and utilized as easily as:

{
  services.github-nix-ci = {
    age.secretsDir = ./secrets;
    personalRunners = {
      "srid/nixos-config".num = 1;
      "srid/haskell-flake".num = 3;
    };
    orgRunners = {
      "zed-industries".num = 10;
    };
  };
}

Activating this configuration spins up the required GitHub runners, with appropriate labels (hostname and Nix systems).

In conjunction with nixci (which is installed in the runners by default), your GitHub Actions workflow YAML can be as simple as follows in order to run CI, on your own machines, for your Nix flakes based projects:

jobs:
  nix:
    runs-on: ${{ matrix.system }}
    strategy:
      matrix:
        system: [aarch64-darwin, x86_64-darwin, x86_64-linux]
    steps:
      - uses: actions/checkout@v4
      - run: nixci build --systems "github:nix-systems/${{ matrix.system }}"

Repurposing an existing machine for running self-hosted GitHub runners involves the following steps.

If you do not already have a NixOS (for Linux) or nix-darwin (for macOS) system configuration, begin with the templates provided by nixos-flake. Alternatively, you may start from the minimal example (./example) in this repo. If you use both the platforms, you can keep them in a single flake as the aforementioned example demonstrates.

If you already have a NixOS or nix-darwin system configuration, you can use github-nix-ci as follows:

1. Switch your configuration to using flakes, if not already.²
2. Add this repo as a flake input
3. Add inputs.github-nix-ci.nixosModules.default (if NixOS) or inputs.github-nix-ci.darwinModules.default (if macOS/nix-darwin) to the modules list of your top-level system configuration.

Test that everything is okay by activating your configuration.

For our runners to be able to authorize against GitHub, we need to create fine-grained personal access tokens (PAC) for each user and organization.

1. Go to https://github.com/settings/personal-access-tokens/new
2. Create a fine-grained PAC
   • Under Resource owner, choose the user or organization for whose repositories your runners will be building the CI for.
   • Under Repository access, choose the appropriate option based on your needs
   • Setup the necessary permissions
     • If the token is for a personal account, under Permissions -> Repository permissions, set Administration to "Read and write"
     • If the token is for an organization, under Permissions -> Organization permissions, set Self-hosted runners to "Read and write"

1. Create a ./secrets/secrets.nix containing the SSH keys of yourself and the machines, as well as the list of token .age files (see next point). See ./example/secrets/secrets.nix for reference.
2. Create a .age file for each PAC secret you created in the previous section
   • Run agenix -e secrets/github-nix-ci/NAME.token.age where NAME is the name of the github user or the organization the PAC is associated with, and then paste your token secret in it, saving the file.

Now that you have set everything up, it is time to configure the runners themselves. For both NixOS and nix-darwin, you can add the following configuration:

services.github-nix-ci = {
  age.secretsDir = ./secrets; # Only if you use agenix
  personalRunners = {
    "srid/emanote".num = 1;
    "srid/haskell-flake".num = 3;
  };
  orgRunners = {
    "zed-industries".num = 10;
  };
};

The above configuration adds 3 sets of GitHub runner daemons. Two of them are associated with the personal repos, whereas the 3rd set is associated with the organization (and thus any repository under that organization). The num property will spin-up that many runners for the associated repo or organization. Setting a num value that is greater than 1 enables you to run actions in parallel (upto the value of num).

Activate your configuration, and visit Settings -> Actions -> Runners page of your repository or organization settings to confirm that the runners are ready and healthy.

Finally, you are equipped to add an actions workflow file to one of the repositories to test everything out. Here's an example if you have configured both NixOS and macOS runners:

# ./.github/workflows/nix.yaml
name: "CI"
on:
  push:
    branches:
      - main
  pull_request:
jobs:
  nix:
    runs-on: ${{ matrix.system }}
    strategy:
      matrix:
        system: [aarch64-darwin, x86_64-linux]
      fail-fast: false
    steps:
      - uses: actions/checkout@v4
      - name: nixci
        run: nixci --extra-access-tokens "github.com=${{ secrets.GITHUB_TOKEN }}" build --systems "${{ matrix.system }}"

The above workflow uses nixci to build all outputs of your project flake.

Because nixci supports generating GitHub's workflow matrix configuration, you can use the following workflow YAML to schedule jobs at a fine-grained level to each runner:

# ./.github/workflows/nix.yaml
name: "CI"
on:
  push:
    branches:
      - main
  pull_request:
jobs:
  
  configure:
    runs-on: x86_64-linux
    outputs:
      matrix: ${{ steps.set-matrix.outputs.matrix }}
    steps:
     - uses: actions/checkout@v4
     - id: set-matrix
       run: echo "matrix=$(nixci gh-matrix --systems=x86_64-linux,aarch64-darwin | jq -c .)" >> $GITHUB_OUTPUT
  
  nix:
    runs-on: ${{ matrix.system }}
    permissions:
      contents: read
    needs: configure
    strategy:
      matrix: ${{ fromJson(needs.configure.outputs.matrix) }}
      fail-fast: false
    steps:
      - uses: actions/checkout@v4
      - run: |
          nixci \
            --extra-access-tokens "github.com=${{ secrets.GITHUB_TOKEN }}" \
            build \
            --systems "${{ matrix.system }}" \
            .#default.${{ matrix.subflake}}

See srid/haskell-flake for a real-world example.

Your runner may suddenly crash with an error like this:

Jun 27 22:39:54 dosa Runner.Listener[424134]: An error occured: Error: Forbidden Runner version v2.316.1 is deprecated and cannot receive messages.

To resolve this, you need to update your github runner package by updating the nixpkgs flake input and then re-deploy. See actions/runner#3332 (comment)

• ./example
• srid/nixos-config