miandmhoennig
923b605e57
- **ADR 0010** (accepted): the build configuration stays expressible as a Forgejo Actions workflow. A new build-definition key needs a workflow counterpart; host-side keys are exempt. - **RFC 0006** (proposed): one workflow for Forgejo and Werkator, and the steps towards it. Step 1 is implemented here. - **`werkator export:forgejo`**, wrapped by **`tools/werkator-to-forgejo`**: converts the committed `.werkator.yml` (never the `.git` layers or `~/.werkator.yml`) into `.forgejo/workflows/werkator-<build>.yml`, one per definition that triggers on its own, follow-ups as jobs with `needs`. Untranslatable constructs become comments and stderr lines; `--strict` refuses. - `AGENTS.md`: the ADR 0010 rule as a hard invariant; column-aligned Markdown tables. - v1.28.0 On Werkator's own `.werkator.yml` the converter names two constructs: `builds.deploy` has no committed trigger (the host adds it), and `werkdock.env` is sandbox environment. PR-doc: `docs/prs/2026-10-03-PR#92-forgejo-actions-compatible-config.md` 🤖 Generated with [Claude Code](https://claude.com/claude-code) Co-authored-by: mhoennig <michael@hoennig.de> Reviewed-on: #92
97 lines
5.1 KiB
Markdown
97 lines
5.1 KiB
Markdown
# The Build Configuration Stays Expressible as Forgejo Actions
|
|
|
|
**Status:**
|
|
- proposed: 2026-10-03
|
|
- accepted: 2026-10-03
|
|
- rejected: -
|
|
- superseded: -
|
|
|
|
**Decision [accepted]:** Werkator's build configuration moves towards the Forgejo Actions workflow format.
|
|
From now on, a key or concept is added to a build definition only when a Forgejo Actions workflow can express it.
|
|
A feature request that a workflow cannot express is reshaped until one can, or it is turned down.
|
|
The first step is [RFC 0006](../rfcs/0006-one-workflow-for-forgejo-and-werkator.md): a developer can write one workflow for their own project that runs on Forgejo and on Werkator unchanged.
|
|
This ADR records the direction and the rule, not an implementation.
|
|
|
|
## Context and Problem Statement
|
|
|
|
Werkator has its own configuration format: `.werkator.yml` with named `builds`, each with a `trigger` block (ADR 0007).
|
|
Forgejo and Gitea ship Forgejo Actions and Gitea Actions, both of them dialects of the GitHub Actions workflow format.
|
|
A project that wants to build on both, or move from one to the other, has to describe its CI twice today and keep the two in step.
|
|
|
|
Every new key in `.werkator.yml` widens the gap, unless it is chosen with the workflow format in mind.
|
|
The gap is cheap to avoid while it is small, and expensive to close once it is large.
|
|
Full compatibility is not the goal: running arbitrary foreign workflows needs an action runtime (`uses:`), an expression language and an artifact and cache server, which is what forgejo-runner is, and is not what a lightweight CI is.
|
|
|
|
### Technical Background
|
|
|
|
Most of today's build definition already has a workflow counterpart:
|
|
|
|
| Werkator | Forgejo Actions |
|
|
| ---------------------------------------------------------- | -------------------------------------- |
|
|
| a build definition | a job |
|
|
| `trigger.onPush`, `trigger.branches` (globs, `!` excludes) | `on.push.branches` |
|
|
| `trigger.atTimes` (daily `HH:MM` UTC) | `on.schedule` with `cron: "M H * * *"` |
|
|
| `trigger.afterSuccessOf` | `needs` |
|
|
| `buildCommand`, `cleanCommand` | `steps[].run` |
|
|
| `artifactDirs` | `actions/upload-artifact` with `path` |
|
|
| `docker.image` | `container.image` |
|
|
| `docker.env` | `container.env`, `env` |
|
|
| `timeout` | `timeout-minutes` |
|
|
|
|
Some existing concepts have no counterpart, and stay what they are:
|
|
|
|
- `trigger.activeWithin` — no workflow filter on the age of a branch head.
|
|
- `docker.dockerfile` and `docker.context` — a workflow names a prebuilt image; Werkator builds it from the repository.
|
|
- `stdoutLog`, `stderrLog`, and the retention keys — they shape Werkator's own storage, not the build.
|
|
|
|
Host-side configuration is outside the rule.
|
|
In Forgejo terms, it is the runner's and the instance's configuration, not the workflow's: `server`, `executor`, `watcher`, `gitea`, `git`, `metrics`, the registry, and the pinned sandbox and trust policy (`docker.enabled`, `docker.network`, `docker.socket`, `werkdock.*`, `requirePullRequest`, `statusContext`, `restartsInstance`).
|
|
A new host-side key needs no workflow counterpart.
|
|
|
|
## Considered Options
|
|
|
|
* Constrain the build configuration to what a workflow can express — chosen
|
|
* Keep the own format free
|
|
* Replace the own format by the workflow format now
|
|
|
|
### Constrain the Build Configuration
|
|
|
|
Good:
|
|
|
|
- The gap stops growing, and closing it later stays possible.
|
|
- A feature request gets checked against a format that many developers already know.
|
|
- No code changes now; the rule costs a question per new key.
|
|
|
|
Bad:
|
|
|
|
- Some features have to be reshaped, or fall away.
|
|
- The existing deviations listed above remain until somebody decides about them.
|
|
|
|
### Keep the Own Format Free
|
|
|
|
Good:
|
|
|
|
- Every feature can take the shape that suits Werkator best.
|
|
|
|
Bad:
|
|
|
|
- Each new key makes a shared workflow less likely, and none of them is ever paid back.
|
|
|
|
### Replace the Own Format Now
|
|
|
|
Good:
|
|
|
|
- One format, no translation.
|
|
|
|
Bad:
|
|
|
|
- Without `uses:`, expressions and matrix support, most real workflows would still not run, and with them Werkator becomes a second forgejo-runner.
|
|
- Every existing `.werkator.yml` would have to be migrated, for no gain on the hosts that run Werkator today.
|
|
|
|
## Decision Outcome
|
|
|
|
The build configuration is constrained to what a Forgejo Actions workflow can express.
|
|
Before a new key or concept goes into a build definition, its design names the workflow construct it corresponds to.
|
|
If there is none, the feature is reshaped until there is one, or it stays out; a host-side key is exempt.
|
|
RFC 0006 describes the first step: a defined subset of the workflow format that Werkator reads, so that one file serves both systems for projects that write it on purpose.
|