# 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:** Active ### Goals - Define architecture, scope, and first-release constraints. - Capture prior failure modes as design inputs. - Establish documentation and decision-tracking structure. ### Tasks - [x] Write `AGENT.md` - [x] Write `README.md` - [x] 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:** Planned ### 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 ### 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:** Planned ### 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. --- ## Phase 3 — Docker workflow support **Status:** Planned ### 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 ### 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`.