Fallout-build / Fallout-build/Fallout

[RFC] CD deployment agent/runner — lightweight, forge-agnostic, idle-and-wait

Open
#113 1 comment 0 reactions 0 assignees View on GitHub
enhancement RFC target/vNext
Dominant language
C#
Stars
154
Forks
19
Avg merge
1d 22h
Merged PRs (30d)
15

Description

## Problem
CD needs to run deployment steps on machines the forge runner can't reach. Forge runners live in the public cloud; targets often sit behind a firewall (Proxmox host, on-prem VMware, air-gapped subnet, homelab box).

Self-hosted runners are the current workaround, but they're forge-coupled, heavy, and tie deployment topology to one forge. We want something lighter and portable.

## Proposal
A small **Fallout deployment agent**: one binary that runs on a target host, authenticates to a coordinator, and idles for instructions. On an instruction it runs a script (Bash / PowerShell / C# / dotnet-script), streams logs back, and reports status.

It's a script executor with auth and logging — not a workflow engine. Orchestration stays in the CD pipeline (C#, in the Fallout repo); the agent runs the leaves.

### Shape
- **Distribution:** single self-contained `fallout-agent` per OS/arch, and/or a global dotnet tool.
- **Hosting:** everything defining the agent's behaviour (allowed scripts, valid targets, auth secrets) lives in the consumer's git repo. Agent pulls on startup. No external control plane.
- **Idle:** long-poll / WebSocket / SSE to the coordinator. No inbound port on the agent host.
- **Execution:** spawn script with clean env, capture stdout/stderr line-by-line, stream upstream, exit code → status.
- **Auth:** mutual. Agent proves identity (pinned token/cert); coordinator proves the command is signed by an authorised source (forge OIDC, signed payload).
- **Logging:** structured per-run logs, kept on the agent host and streamed to the coordinator. Local retention survives a coordinator outage.

### Forge-agnostic
GitHub is the reference (OIDC from `actions/` runs is easy to verify). Must also work with Gitea, Forgejo, GitLab, Azure DevOps — anything that can sign a JWT or call a webhook. The agent knows nothing about "GitHub", only an abstract "coordinator I trust to sign commands".

## Open questions
- **Wire protocol:** HTTP long-poll (simplest), persistent WebSocket (bidirectional, more state), git-ref pull (everything-in-repo, but git-as-queue has sharp edges), or hybrid (forge issues signed dispatch, agent polls a small endpoint).
- **Coordinator topology:** separate service, or the forge itself (agent talks to GitHub/GitLab API directly)?
- **Auth model:** forge OIDC, pre-shared keys, certs, SPIFFE? Prefer OIDC.
- **Concurrency:** instinct is single-tenant, single-command by default; run multiple agents for parallelism.
- **Script runtime:** pure exec, or a richer C# API (`FalloutAgent.Log()`, `.Artifact()`)? Start with exec/capture/report; add on demand.
- **Updates:** pinned version, auto-update from a release feed, or manual?
- **vs v12 plugin SDK:** separate component or a hosted plugin? Probably separate (different deployment + threat model) — confirm.

## Why v13
The agent is the substrate the rest of CD sits on — environment promotion, approval gates, release tracking all need a way to run commands on real machines. Filed as RFC because the shape is open. Most useful feedback: deployment topologies you'd use Fallout for, and where self-hosted-runner/agent solutions fall short.

Related: parent CD RFC #106.

Contributor guide

Open the contributing guide

Assessment

This issue has not been assessed yet.

Get new issues in your inbox

A short digest of beginner-friendly GitHub issues.