Operations

Normal startup sequence

When the container starts, expect to see:

======================================================
  custom-gitea-runner
  Image version : v0.1.0
  Git revision  : abc1234
======================================================
Runtime:
  act_runner : v0.2.11
  node       : v20.x.x
  npm        : 10.x.x
  git        : 2.x.x
  docker     : 24.x.x
Config:
  Config path  : /config/runner.yaml
  Work dir     : /work
  Gitea URL    : https://git.example.com
  Runner name  : unraid-runner-01
  Labels       : ubuntu-latest:docker://node:20-bullseye
======================================================
[OK] All required binaries present.
[INFO] Existing config found at /config/runner.yaml. Skipping registration.
[START] Starting act_runner daemon ...

On first boot with no config:

[BOOTSTRAP] No config found at /config/runner.yaml. Initiating registration.
[BOOTSTRAP] Registration complete. Config at /config/runner.yaml.
[START] Starting act_runner daemon ...

Health check

The container runs a health check every 30s. Check status with:

docker inspect --format='{{.State.Health.Status}}' gitea-runner

Or view health check output:

docker inspect --format='{{json .State.Health}}' gitea-runner | jq .

Expected healthy output from healthcheck.sh:

[HEALTH] OK   : act_runner process is running
[HEALTH] OK   : Config file present at /config/runner.yaml
[HEALTH] OK   : Binary present: act_runner
[HEALTH] OK   : Binary present: git
[HEALTH] OK   : Binary present: node
[HEALTH] OK   : Binary present: npm
[HEALTH] OK   : Docker socket accessible

Smoke test

Before production use, run the smoke test against the image:

./scripts/verify-runtime.sh custom-gitea-runner:v0.1.0

Or directly:

docker run --rm custom-gitea-runner:v0.1.0 /usr/local/bin/smoke-test.sh

Checking runner registration in Gitea

Go to your Gitea instance.
Navigate to Site Administration → Runners (admin panel) or Repository Settings → Runners.
The runner should appear with status Online.

Upgrade procedure

Build or pull the new pinned image tag.
Review CHANGELOG.md for breaking changes.
Stop the existing container.
Update the image tag in your compose file or Unraid template.
Start the container.
Verify startup logs and health check status.
Run a smoke workflow to confirm job execution works.

Rollback procedure

Stop the container.
Revert the image tag to the prior known-good version.
Start the container.
Confirm the registration config is still valid (it should be — it's persisted in the config volume).
Run a smoke workflow.

Re-registration

If you need to re-register the runner (e.g. after a token reset or renaming):

Stop the container.
Delete config/runner.yaml.
Set the new GITEA_RUNNER_TOKEN in your environment.
Start the container — it will register fresh on boot.

Log access

# Tail live logs
docker logs -f gitea-runner

# Last 100 lines
docker logs --tail 100 gitea-runner

3.1 KiB Raw Blame History