forgerunner/docs/operations.md

# 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:

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

Or view health check output:

```bash
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:

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

Or directly:

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

---

## Checking runner registration in Gitea

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

---

## Upgrade procedure

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

---

## Rollback procedure

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

---

## Re-registration

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

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

---

## Log access

```bash
# Tail live logs
docker logs -f gitea-runner

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