forgerunner/forgerunner.src/ROADMAP.md

ROADMAP.md

Project

Name: custom-gitea-runner

Status: Planning / bootstrap

Objective: Deliver a self-owned, versioned, Docker-first Gitea runner platform that is reliable on Unraid and Linux, easy to debug, and explicitly documented from image build through runtime operations.

---

Guiding outcomes

The project is considered successful when it can:

• run as a pinned Docker image,
• execute checkout + Node-based + Docker build/push workflows reliably,
• register and restart predictably,
• surface actionable logs during failure,
• and be upgraded or rolled back cleanly.

---

Project phases

Phase 0 — Research and design

Status: Complete

Goals

• Define architecture, scope, and first-release constraints.
• Capture prior failure modes as design inputs.
• Establish documentation and decision-tracking structure.

Tasks

• Write AGENT.md
• Write README.md
• Write ROADMAP.md
• Create CHANGELOG.md
• Create .env.example
• Create ADR template under docs/decisions/
• Write docs/architecture.md
• Decide base image strategy
• Decide socket-mount vs DinD position for v1
• Decide registration mode defaults

Exit criteria

• Scope is documented.
• Core repo structure is defined.
• Major open decisions are listed.
• First implementation sequence is agreed.

---

Phase 1 — Base image and bootstrap

Status: Complete

Goals

• Produce the first buildable runner image.
• Eliminate runtime package mutation.
• Establish deterministic startup behavior.

Tasks

• Create docker/runner/Dockerfile
• Pin base image tag
• Pin act_runner source/version
• Install required dependencies at build time:
  • bash
  • curl
  • git
  • jq
  • nodejs
  • npm
  • docker CLI
  • ca-certificates
  • tini
  • tzdata
• Create docker/runner/docker-entrypoint.sh
• Create docker/runner/healthcheck.sh
• Add image metadata labels
• Verify startup prints tool versions

Notes

• First successful build: custom-gitea-runner:v0.1.0 (act_runner v0.2.11, node v20.20.2, npm 10.8.2, git 2.34.1, docker CLI 29.6.1).
• Runtime smoke test passes 17/17 via ./scripts/verify-runtime.sh.

Exit criteria

• Image builds locally.
• Container starts cleanly.
• node, git, docker, and act_runner are all present.
• Healthcheck script returns useful status.

---

Phase 2 — Registration and config flows

Status: Complete

Goals

• Support both mounted-config and env-driven registration.
• Make bootstrap idempotent.
• Ensure config persistence survives restarts.

Tasks

• Create config/runner.example.yaml
• Create config/labels.example.env
• Create scripts/register-runner.sh
• Create scripts/deregister-runner.sh
• Add config path validation
• Add first-boot registration flow
• Add re-run safe bootstrap logic
• Document required environment variables
• Validate restart behavior with existing config

Exit criteria

• Runner can register successfully.
• Existing config is reused without duplicate registration.
• Missing configuration fails fast with clear logs.

Notes

• Validated live against git.alwisp.com (Gitea 1.26.4): runner forgerunner-01 registered as instance-level runner (id 5), came online and healthy, and a container restart reused the existing config with no duplicate registration.
• Registration token obtained via POST /api/v1/admin/actions/runners/registration-token; deregistration via DELETE /api/v1/admin/actions/runners/{id} (act_runner has no unregister command).

---

Phase 3 — Docker workflow support

Status: Active (host-toolchain validated; registry push pending credentials)

Goals

• Prove the runner can handle real Docker-centric CI workloads.
• Ensure JavaScript-based actions work out of the box.

Tasks

• Validate actions/checkout
• Validate Node-based action runtime
• Validate docker/login-action
• Validate docker build
• Validate docker push
• Add support notes for self-hosted Gitea Container Registry
• Validate mounted Docker socket usage
• Document permission expectations for /var/run/docker.sock
• Evaluate buildx as optional enhancement

Notes

• .gitea/workflows/ci-smoke.yml (run 110, success) validated on the live runner via the host label: actions/checkout@v4, bundled node/npm/git/docker versions, and Docker-socket access (docker info) all pass.
• Image published: registry.alwisp.com/jason/custom-gitea-runner:v0.1.0 + :latest (login via the jason Gitea account succeeded; push validated the registry round-trip).
• docker/login-action + docker build + docker push from a workflow still pending: needs repo Action secrets REGISTRY_USER/REGISTRY_TOKEN. Recommend a dedicated scoped package token rather than the admin API token. Corrected sample workflows (test/sample-workflows/docker-login.yml, docker-build-push.yml) are ready to run on the host label once the secrets exist.

Exit criteria

• Standard Docker build/push workflows pass.
• No runtime install hacks are needed.
• Node-based actions work on first boot.

---

Phase 4 — Test harness and smoke validation

Status: Planned

Goals

• Convert operational pain into repeatable tests.
• Establish confidence before release.

Tasks

• Create docker/runner/smoke-test.sh
• Create scripts/verify-runtime.sh
• Create scripts/test-local-runner.sh
• Add test/sample-workflows/checkout.yml
• Add test/sample-workflows/node-action.yml
• Add test/sample-workflows/docker-login.yml
• Add test/sample-workflows/docker-build-push.yml
• Add regression test cases for:
  • missing node
  • broken Docker socket access
  • invalid registration config
  • startup tool validation failures
• Document how to run smoke tests locally

Exit criteria

• Smoke tests are runnable by an operator.
• Known painful regressions are covered.
• Runtime validation is part of the normal release flow.

---

Phase 5 — Unraid packaging and docs

Status: Planned

Goals

• Make deployment smooth in the real target environment.
• Provide operational documentation that matches actual host usage.

Tasks

• Create docker/compose/docker-compose.example.yml
• Create docker/compose/unraid-template-notes.md
• Write docs/unraid.md
• Write docs/operations.md
• Write docs/troubleshooting.md
• Document update procedure
• Document rollback procedure
• Document appdata path recommendations
• Document Docker socket trust model
• Optionally create Unraid XML/template artifact

Exit criteria

• Operator can deploy from docs alone.
• Unraid-specific steps are explicit.
• Upgrade and rollback are documented and tested.

---

Phase 6 — Hardening and enhancements

Status: Backlog

Goals

• Expand safety and flexibility after the baseline runner is stable.

Candidate enhancements

• Rootless variant
• DinD variant
• Dedicated BuildKit support
• Ephemeral single-job runner mode
• Structured JSON logging
• Metrics/exporter support
• Label policy controls
• Custom CA bootstrap helpers
• Small helper CLI in TypeScript
• Multi-runner orchestration concepts

Exit criteria

• Enhancements are prioritized based on real operational need.
• Stability is not regressed by added flexibility.

---

Immediate next actions

Next 10 actions

1. Create CHANGELOG.md
2. Create .env.example
3. Scaffold repo directories
4. Write docs/architecture.md
5. Write first ADR: base image choice
6. Create initial Dockerfile
7. Create docker-entrypoint.sh
8. Create healthcheck.sh
9. Build first local image
10. Verify runtime toolchain inside container

---

Risks and watch items

Technical risks

• Upstream act_runner behavior may still impose constraints even with a custom wrapper image.
• Docker socket usage is convenient but increases host trust exposure.
• Self-registration flows can become brittle if not made idempotent.
• Docker build/push success does not guarantee all third-party actions behave as expected.

Process risks

• Letting docs lag implementation will erode the value of the project quickly.
• Overengineering v1 will delay a usable baseline.
• Supporting too many runtime modes too early may reduce stability.

---

Decision log to create

Create ADRs for:

• Base image selection
• Runner binary acquisition strategy
• Runtime user model
• Docker socket vs DinD
• Registration strategy
• Release and tagging policy

---

Definition of done for v0.1.0

v0.1.0 should mean:

• image builds reproducibly,
• runner registers successfully,
• startup validation is clear,
• actions/checkout works,
• Node-based actions work,
• Docker login/build/push works,
• docs cover install, operation, upgrade, rollback, and troubleshooting,
• and the release is tagged and documented in CHANGELOG.md.