werkrevisor/docs/prs/2026-10-08-PR#48-integration-guide.md

PR#48: The README tells other developers how to integrate werkrevisor

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.

The Problem

The README describes werkrevisor as it runs on mih09: as a Werkator build, with werkdock and a rootfs archive. A developer who wants to use werkrevisor elsewhere does not find out what werkrevisor needs from its environment, which parts are specific to Werkator, and which forges it supports. GitHub, the most likely question, is not supported, and the README does not say so.

Non-Goals

• No support for GitHub or another forge than Gitea; the README names what a port needs.
• No renamed environment variables: the WERKATOR_* names stay, any runner can set them.
• No published image; a user builds it from the Dockerfile.
• No change of the Werkator sections.

The Scenarios

Feature: the README tells other developers how to integrate werkrevisor

Scenario#48.01: a developer learns what werkrevisor needs from a CI system

So that werkrevisor runs in any CI system that can start a container for a pull request.

• Given a developer with a Gitea or Forgejo instance and a CI system other than Werkator
• When the developer reads the section "Integration" of the README
• Then the README names the trigger, the environment, the secrets, the gate status and the trust rules
  • and it shows an example for Gitea Actions

Verified by

• no automated test: a documentation change, see README.md

Scenario#48.02: a developer learns that GitHub is not supported

So that nobody spends time on a setup that cannot work.

• Given a developer with GitHub repositories
• When the developer reads the section "Integration" of the README
• Then the README says that werkrevisor talks only to the Gitea API
  • and it names what a port to another forge needs

Verified by

• no automated test: a documentation change, see README.md

The Solution

• A new README section "Integration", before "Operations", independent of Werkator and of mih09.
• The introduction of the README names Werkator as one possible runner.
• The example for Gitea Actions is a sketch: it was not run on a Gitea runner, so the README says to try it on past PRs with tools/dry-run first and to start with yellow_gate = "block".

Prerequisite PRs

• PR#46: werkrevisor 0.22.0, merged.