A small Forgejo queue-driven AWS Spot runner controller. This is an original public project licensed under GPL-3.0-only.
- Observes runnable jobs for one Forgejo repository and explicit runner labels.
- Adds up to a configured number of Spot instances (default one, maximum twelve) from an operator-prepared, pinned launch template while the queue has work and the budget allows it.
- Keeps Forgejo as the only scheduler and job-result authority.
- Persists launch intent, ownership, the accepted Spot price and a conservative forward cost commitment before every cloud request, and settles each worker's tracked cost when it terminates.
- Defaults to observation; requires an explicit apply to launch, and offers an independent expiry-cleanup path that never launches.
- Turns the console of the workers it owns into deduplicated events and a metrics textfile, so a launch that never registers is visible as an event rather than as a queue that does not move. The reader is bounded, holds no queue credential and copies no arbitrary console text.
The product source is implemented, covered by standard-library tests and
released. A release is source history, not a deployment: this repository
publishes no image, and the deployment procedure and the live Forgejo contract
qualification are the operator's records. qualification = "fixtures-only" is
the shipped default and blocks apply until an operator records that evidence.
AWS resources, IAM, networking, registration credentials and the runner image
remain operator-owned prerequisites. No cost-saving or absolute AWS-billing-cap
claim has been established.
Requires Python 3.12 or newer. Live use needs the boto3 runtime dependency
(pip install -e .); tests need neither the SDK nor any credential.
python -m ci_burst plan --config deployment.toml
python -m ci_burst apply --config deployment.toml
python -m ci_burst status --config deployment.toml
python -m ci_burst export --config deployment.toml --metrics-file ci-burst.prom
python -m ci_burst reap --config deployment.toml [--apply]A minimal configuration is in docs/operations.md, which also owns the queue contract, the worker image/template contract, labels, cost scope, identities, rollback and status semantics. To build the operator-owned worker prerequisites, including the IAM role, SSM parameter and bootstrap, follow docs/runner-setup.md. Once those exist, the deployment walkthrough sequences the control-plane identities, hosts, configuration, scheduling and live qualification. The pilot checklist is a preparation record, not authorization. Running the controller from a container beside Forgejo, driven by systemd timers, is described in docs/container.md; the image is built locally and none is published. A worker subnet with no internet path of its own needs the optional in-VPC router in docs/router.md.
The delivered product change is archived as the AWS Spot queue-burst change, with its design, acceptance specifications and task record. Its requirements are promoted to the capability specifications, and the next behavioural change needs its own proposal.
A release exists. release-please
maintains the version, CHANGELOG.md and the annotated
v-prefixed tag from merged conventional commits.
CONTRIBUTING.md owns the release boundary: a
maintainer merges the release pull request, and release-please creates the tag
and the GitHub Release whose notes are that changelog section. A release is not
a deployment.
Use Node.js 22.12+, Python 3.12+ and npm:
npm ci --ignore-scripts
npm run check:policy
npm run check:speccheck:policy runs the Python source tests and the workflow-policy tests.
Validation CI is read-only and uses no cloud credentials or billable
operations; it does not prove a live Forgejo/AWS integration. Separate
trusted-default-branch workflows can publish the Gandalf-backed review
status and merge eligible ordinary PRs after maintainer-controlled activation.
They never execute PR-head code with a write token. See
review, merge and activation.
Read CONTRIBUTING.md, AGENTS.md and SECURITY.md. GitHub is the sole source/PR surface. Changes use protected-main pull requests; controlled automated merging is not active merely because this policy exists.
License: GPL-3.0-only. Copyright (C) 2026 ci-burst contributors. No affiliation with Forgejo or Amazon Web Services is implied.