Skip to content

Setting up the CI runner

This repository uses Forgejo Actions for CI. The workflows live in .forgejo/workflows/ and run in containers built from our own distroless images (build, security, docs).

The project is hosted on CodeFloe (codefloe.com), a Forgejo-based forge. CodeFloe provides hosted runners — including a docker label that runs the job inside a Docker-in-Docker (dind) environment. The CI images are published to the CodeFloe container registry and referenced by their full URL in the workflows, so no self-hosted runner is needed.

This guide covers the hosted-runners setup and, as an alternative, a self-hosted runner.

1. Enable Forgejo Actions

Forgejo Actions is a per-repository setting. In the repository settings, enable the Actions unit (Settings → Units → Overview → Actions).

2. Use the hosted runner

  1. Go to https://codefloe.com/user/settings/actions/runners to see the available hosted runner labels (login required).
  2. The workflows use runs-on: docker, which maps to the hosted docker label.
  3. No runner registration is needed — the hosted runners pick up the jobs.

Our workflows are already compatible:

  • .forgejo/workflows/ci.yaml : build (codefloe.com/st4713/nfcscreen-app:build), security (...:security), docs (...:docs).
  • .forgejo/workflows/pages.yaml : builds mkdocs and deploys to the pages branch.

3. Update the CI images

When a containers/*.Dockerfile changes, rebuild and re-push the images to the registry:

CODEFLOE_TOKEN=... containers/ensure-images.sh

4. Alternative: self-hosted runner

If you prefer to run the jobs on your own machine (more control, or if the hosted docker runner is unavailable), install forgejo-runner:

  1. Register a runner in https://codefloe.com/st4713/nfcscreen-app/settings/actions/runners (or https://codefloe.com/user/settings/actions/runners for all your repositories) and copy the UUID and token.
  2. Generate the default config: bash docker run --rm data.forgejo.org/forgejo/runner:13 \ forgejo-runner generate-config > runner.yml
  3. Configure the CodeFloe connection: yaml server: connections: codefloe: url: https://codefloe.com/ uuid: 00000000-0000-0000-0000-000000000000 # your UUID token: d4fe2db46a4c6bdc434a9ce3378d9a1489c1b30e # your token
  4. Define the docker label (any base image works because every job overrides container:): ```yaml runner: labels:
    • docker:docker://data.forgejo.org/oci/alpine:3.20 ```
  5. Start the runner: bash forgejo-runner daemon --config runner.yml The jobs pull the CI images from the CodeFloe container registry, so the host does not need to build or pre-load them.

Troubleshooting

  • no matching runner is online : no runner with the docker label is available. Check the hosted runner list or connect a self-hosted runner.
  • Image pull fails in a job : the codefloe.com/st4713/nfcscreen-app:* images are not available or not public. Run CODEFLOE_TOKEN=... containers/ensure-images.sh to rebuild and re-push them.