CloudNebulaProject/solstice-ci
SHA256
1
0
Fork 0
mirror of https://codeberg.org/Toasterson/solstice-ci.git synced 2026-04-10 13:20:41 +00:00
Code Issues Projects Releases Packages Wiki Activity Actions
solstice-ci/docs/ai/decisions/001-runner-only-architecture.md
Till Wegmueller d6c2c3662c Add architecture plans and decision records 
Plans:
- 001: vm-manager migration (completed)
- 002: runner-only architecture (active)

Decision records (ADRs):
- 001: Runner-only architecture — retire webhooks + logs service
- 002: Direct QEMU over libvirt
- 003: Ephemeral SSH keys with opt-in debug access
- 004: User-mode (SLIRP) networking for VMs
2026-04-09 22:03:12 +02:00

1.9 KiB
Raw Blame History

ADR-001: Runner-Only Architecture

Date: 2026-04-09 Status: Accepted Deciders: Till Wegmueller

Context

Solstice CI started as a full CI/CD system with webhook receivers, a custom log storage service, and platform-specific integration layers. This resulted in 7+ services to maintain, a custom log viewer that was worse than GitHub/Forgejo's native UI, and security/multi-tenancy challenges around log access control, webhook secrets, and artifact storage.

The system's unique value is VM orchestration for non-Linux operating systems (illumos, omnios, OpenIndiana) — something no other CI runner handles well.

Decision

Act exclusively as a native runner for GitHub and Forgejo. Retire all webhook ingestion, log storage, and custom status reporting. Let the platforms handle everything except job execution.

Consequences

Positive

  • 7 services reduced to 3: orchestrator, forgejo-runner, github-runner
  • Security solved by delegation: log access, webhook secrets, artifacts, user auth all handled by the platform
  • Better UX: logs appear in GitHub/Forgejo native UI instead of a custom dashboard
  • Standard workflow format: users write GitHub Actions YAML, not custom KDL
  • Lower maintenance burden: no custom dashboard, no log retention policy, no artifact storage

Negative

  • No custom KDL workflows for external users: KDL remains as internal superset but external users must use Actions YAML
  • Feature limitations: can only execute run steps, not uses actions (no container support, no marketplace actions)
  • Platform dependency: tied to GitHub/Forgejo runner protocols
  • GitHub runner protocol complexity: significantly more complex than Forgejo's connect-rpc (RSA JWT, OAuth tokens, heartbeats)

Neutral

  • Internal projects can still use .solstice/workflow.kdl for setup scripts and multi-OS abstractions
  • RabbitMQ remains as the internal job buffer between runners and orchestrator