werkator/docs/prs/2026-10-03-PR#92-forgejo-actions-compatible-config.md

WARNING: This document describes only the change applied in this PR. It may already be outdated once the next PR is merged. Historic PR-documentation is not maintained along with new PRs — treat it as a snapshot, not as current documentation.

The Problem

Werkator's .werkator.yml and the Forgejo Actions workflow format describe the same builds in two ways. Every new build-definition key could widen that gap, and nothing in the repository said that it should not. A project that builds on Forgejo and on Werkator has to keep two CI descriptions in step. Nobody could tell how far apart the two formats are for a given repository.

Non-Goals

• No full Forgejo Actions compatibility; uses:, expressions and matrices stay out.
• Werkator does not read workflows yet; that is step 5 of RFC 0006.
• The converter does not guess host policy: it reads the committed file only.

The Scenarios

Feature: .werkator.yml converts into Forgejo Actions workflows

Scenario#92.01: One workflow per definition that triggers on its own

So that a trigger, which belongs to a workflow in Forgejo, keeps its build.

• Given a .werkator.yml with a pushed default and a deploy without a trigger
• When it is converted
• Then each becomes a workflow with checkout, clean, build and the upload of its artifacts
• And each job carries its effective settings, builds.default applied
• And the deploy workflow has workflow_dispatch only, and that is named

Verified by

• ForgejoWorkflowExporterUnitTest — Scenario#92.01

Scenario#92.02: A branch selector becomes a branches filter

So that the same branches build on both systems.

• Given trigger.branches with *, an exclusion and a ?
• When it is converted
• Then * becomes **, exclusions go last, a filter of exclusions alone starts with **, and ? is escaped and named

Verified by

• ForgejoWorkflowExporterUnitTest — Scenario#92.02

Scenario#92.03: atTimes becomes a schedule

So that a nightly build stays nightly.

• Given atTimes with a daily and an hourly time
• When it is converted
• Then each becomes a cron line
• And a schedule over more than one branch is named, because Forgejo schedules only the default branch

Verified by

• ForgejoWorkflowExporterUnitTest — Scenario#92.03

Scenario#92.04: A follow-up becomes a job with needs

So that a deployment still runs only after a green build.

• Given a chain of follow-ups, one with literal branches, one with a glob, and one whose predecessor is missing
• When it is converted
• Then the chain becomes jobs of the root's workflow with needs
• And literal branches become an if on github.ref_name; the glob and the missing predecessor are named

Verified by

• ForgejoWorkflowExporterUnitTest — Scenario#92.04

Scenario#92.05: Image, environment and timeout

So that a Docker build runs in the same image.

• Given a build with docker.image, docker.env and timeout: 90s, and one with a Dockerfile only
• When it is converted
• Then the first gets container.image, env and timeout-minutes: 2
• And the Dockerfile is named, because a workflow needs a prebuilt image

Verified by

• ForgejoWorkflowExporterUnitTest — Scenario#92.05

Scenario#92.06: Nothing is dropped silently

So that the list of untranslated constructs measures the gap ADR 0010 keeps from growing.

• Given activeWithin, stdoutLog, requirePullRequest, statusContext, a multi-line command and $branch
• When it is converted
• Then each is listed, and written as a comment above the place it belongs to

Verified by

• ForgejoWorkflowExporterUnitTest — Scenario#92.06

Scenario#92.07: Only the committed file is read

So that no secret and no host policy ends up in a committed workflow.

• Given a machine config with a token and a build command, and an instance file with defaults
• When export:forgejo runs
• Then the workflow holds the committed build command only
• And --stdout prints the workflows instead of writing them

Verified by

• ExportForgejoCommandUnitTest — Scenario#92.07

Scenario#92.08: --strict refuses

So that a CI check can demand a complete conversion.

• Given a construct without a workflow counterpart
• When export:forgejo --strict runs
• Then it writes nothing and exits 1
• And without a committed .werkator.yml it exits 2

Verified by

• ExportForgejoCommandUnitTest — Scenario#92.08

Scenario#92.09: What the existing repositories showed

So that the converter's output for the repositories Werkator builds today says what they need.

• Given a builds.default without a trigger, an image built from a Dockerfile, and a follow-up with an empty cleanCommand
• When it is converted
• Then the settings base gets no workflow
• And the Dockerfile is named although the image has a name, and so is the follow-up that builds on its predecessor's worktree

Verified by

• ForgejoWorkflowExporterUnitTest — Scenario#92.09

Scenario#92.10: The workflows go into the target repository

So that the converter can be pointed at any checkout, from anywhere.

• Given a directory inside a git repository whose root holds the .werkator.yml
• When export:forgejo runs on it, with --output-dir .gitea/workflows
• Then the root's .werkator.yml is read, and the workflows are written below the root
• And a directory outside any git repository is a usage error

Verified by

• ExportForgejoCommandUnitTest — Scenario#92.10

The Solution

• ADR 0010 records the direction: 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 proposes one workflow for both systems and the steps towards it.
• Step 1 of the RFC is implemented here:
  • ConfigLoader.loadCommitted binds the committed .werkator.yml alone, builds.default applied.
  • ForgejoWorkflowExporter (new package forgejo) writes one workflow per definition that triggers on its own, with a small YAML writer, so comments can sit where they belong.
  • ExportForgejoCommand (export:forgejo [REPO]) finds the root of the target repository with git rev-parse --show-toplevel, reads the .werkator.yml there, writes .forgejo/workflows/werkator-<build>.yml into it, prints the untranslated constructs on stderr, and refuses under --strict.
  • tools/werkator-to-forgejo runs the command from WERKATOR_BIN, the werkator on PATH, or the jar of the checkout.
• It is a Kotlin command, not a Python script: it binds the file exactly as Werkator does, and its tests run in the existing suite.
• A trial run over the repositories of mih09 and over hs.hsadmin.ng converted every file; RFC 0006 lists what it found. Both forges run Gitea, which reads .gitea/workflows, so --output-dir matters until the RFC settles the default. werkdock.env is converted to env now, since Werkator has no environment outside a sandbox.
• AGENTS.md carries the rule as a hard invariant and lists ADR 0010 among the decisions in force.

Additional Changes

• AGENTS.md asks for column-aligned Markdown tables in new documents.
• docs/configuration.md, docs/llms.md, the architecture skill and the package list in AGENTS.md describe the converter.
• Version 1.29.0 with its release note.

Follow-up PRs

• RFC 0006 step 2: the GITHUB_* and FORGEJO_* variables in every build.