- Rust 97.2%
- Shell 2.3%
- Makefile 0.5%
| Filename | Latest commit message | Latest commit date |
|---|---|---|
Pi Coding Agent
42b68ae124
Replace the previous cache and artifact proxy plan with a new design
centered on a daemon trust boundary and S3 storage via pre-signed URLs.
The agent-side cache server speaks the Forgejo Runner-compatible REST
protocol (/_apis/artifactcache/) and runs on 127.0.0.1:8080 inside the
VM. The daemon validates repository and branch on every operation and
provides pre-signed S3 URLs scoped to cache/{repo}/{branch}/. The agent
has no S3 credentials and cannot bypass isolation.
Key decisions:
- Artifact proxy removed (VM can reach Forgejo directly)
- S3 storage: s3s-fs on daemon for Firecracker, native S3 for cloud
- Eviction: periodic background task, reservations blocked near capacity
- PR branches can read main-branch caches, writes restricted to own branch
- Daemon unreachable: graceful cache miss, job continues
Configuration: [cache] with enabled, endpoint, bucket, total_size, repo_size.
Four implementation PRs: daemon S3 server, REST cache handler, agent
integration, cloud S3 support.
|
||
| .forgejo/workflows | ||
| contrib | ||
| docs/plans | ||
| scripts | ||
| src | ||
| .dockerignore | ||
| .gitignore | ||
| AGENTS.md | ||
| ampoule-threat-model-20260624.md | ||
| ampoule-threat-model-20260707.md | ||
| Cargo.lock | ||
| Cargo.toml | ||
| config.toml.example | ||
| DIFFERENTIAL_REVIEW_2026-06-21.md | ||
| DIFFERENTIAL_REVIEW_2026-07-07.md | ||
| Makefile | ||
| README.md | ||
Ampoule — Forgejo Actions Runner
Ampoule is a Forgejo Actions runner that executes each job inside an ephemeral, isolated environment. The initial backend uses Firecracker microVMs; the architecture supports alternative backends (cloud VMs, etc.) through a pluggable executor interface.
Introduction
Forgejo is a software forge, like GitHub and GitLab. It contains Forgejo Actions, which is modeled closely on GitHub Actions, but not entirely the same.
A Runner is a tool that takes job definitions from an Actions workflow and executes them.
Motivation
Since a job is essentially just some random executable code, inherently it cannot be trusted. Therefore it needs to be isolated. To combat that, this project provides a runner that creates a lightweight virtual machine to run this code in.
Naming
The project is named ampoule — a hermetically sealed, single-use glass container used in medicine and chemistry. The metaphor fits: each job gets a clean, sealed environment that is discarded after use. The name has no association with any specific technology or vendor, which is intentional given that the executor backend is designed to be swappable.