docs(integration): the default-branch guide says the toolkit assumes main, offers two override routes that cannot reach it, and omits the wrapper triggers #1565

New issue

Open

opened 2026-10-06 12:05:17 +02:00 by claude · 0 comments

claude commented

2026-10-06 12:05:17 +02:00

Member

docs/integration.md's "Default branch (#370)" section is the adopter's guide for a repository whose branch is not main. It opens by saying the toolkit assumes main "in most places", which is no longer true. It also offers two override routes that cannot reach the toolkit. And it never tells the adopter to change the branches: [main] triggers in the wrappers they copy.

Measured

All reads are on live origin/main 6a36090, 2026-10-06.

1. "Assumes main in most places" (docs/integration.md:633) is out of date. Every path that targets the default branch now resolves it through the layered resolver, prep.DefaultBranchResolver (internal/prep/git.go:299-320):

rt prep: the rolling PR's base (cmd/rt/prep.go:718-732).
rt post-cut: the manifest push (cmd/rt/post_cut.go:272-275).
rt manifest-pr: the manifest PR's base (cmd/rt/manifest_pr.go:149).
rt default-branch: used by recover-pending-cut (reusable-recover-pending-cut.yml:414) and by the cut's post-condition step (reusable-release.yml:983).

The "main" literals left in cmd/rt:

rt prep's last-resort backstop, reached only when every layer fails (prep.go:731).
Env-only fallbacks in manifest-precheck (:111), which no workflow calls, and in manifest-postcondition (:282), whose result CI overrides.
--branch/--base flag defaults on status-context-check, pre-push and repin, which are toolkit-side tools.

2. The "dispatch input" route does not exist.

The docs name it three times: :580 ("default_branch ranks an explicit dispatch input at the top"), :590 ("which a dispatch input can set") and the layer-1 row at :639.
None of the four reusable workflows declares an input that carries a branch. Their workflow_call inputs were listed at 6a36090, and no name contains "branch".
An adopter's own dispatch input can only reach a reusable through with:, and there is no with: slot for this.

3. The "Environment override example" (:666-675) cannot reach rt.

It puts env: RT_DEFAULT_BRANCH: trunk on a job that calls the reusable through uses:.
Each step that reads layer 1 sets RT_DEFAULT_BRANCH: ${{ vars.RT_DEFAULT_BRANCH }} in its own env: (reusable-release.yml:615, reusable-recover-pending-cut.yml:256). Under Actions env precedence a step-level key replaces any inherited value, with an empty string when the variable is unset. So even if Forgejo passed the caller's env: into the called workflow, trunk would not reach rt.
Not measured: whether Forgejo rejects env: on a uses: job, as GitHub's workflow syntax does, or ignores it.

4. The wrapper triggers are left at main, and the section does not say to change them. The wrappers the docs ask adopters to copy trigger on branches: [main]:

docs/integration.md:866 (release.yml), :1197 (pr.yml) and :1370 (prepared-uncut-check.yml);
README.md:249;
the four example wrappers in examples/{go,node}-project/.forgejo/workflows/{release,pr}.yml.

An adopter on master who copies them as they are gets no automatic cut: release.yml runs only through its workflow_dispatch trigger. The PR gates never run at all. Nothing in the "Default branch" section mentions this.

5. "Picked up automatically" holds at two of three callsites. :677 says the reusable picks up vars.RT_DEFAULT_BRANCH automatically. That is true at the act-on-decision step and at recover-pending-cut. It is not true at the cut's post-condition step: #1564 covers that in code.

Why it matters

This section is what an adopter on master, trunk or develop reads first. Today it tells them the toolkit mostly assumes main, which would put them off for no reason, and it offers two override routes that do nothing. It also misses the one edit they really need, the wrapper triggers. Without that edit, a push never starts a release, and the PR gates never run.

Acceptance criteria

:633 describes the current behaviour. The toolkit resolves the default branch wherever it targets it, and refuses rather than guessing. Name the one remaining guess, rt prep's backstop, if it still exists when this lands.
The dispatch-input route is removed from :580, :590 and the layer-1 row at :639. The section names the two routes that do reach the toolkit: the vars.RT_DEFAULT_BRANCH repo variable and default_branch: in release-toolkit.yml.
The "Environment override example" (:666-675) is removed, or replaced with the repo-variable route.
The section tells an adopter whose branch is not main to change branches: [main] in each wrapper they copy, and names the wrappers.
:677 stays accurate after #1564 lands, or names the step it does not yet cover.
rt register-check and scripts/anchor-check.py pass on every changed doc.

`docs/integration.md`'s "Default branch (#370)" section is the adopter's guide for a repository whose branch is not `main`. It opens by saying the toolkit assumes `main` "in most places", which is no longer true. It also offers two override routes that cannot reach the toolkit. And it never tells the adopter to change the `branches: [main]` triggers in the wrappers they copy. ## Measured All reads are on live `origin/main` `6a36090`, 2026-10-06. **1. "Assumes `main` in most places" (`docs/integration.md:633`) is out of date.** Every path that targets the default branch now resolves it through the layered resolver, `prep.DefaultBranchResolver` (`internal/prep/git.go:299-320`): - `rt prep`: the rolling PR's base (`cmd/rt/prep.go:718-732`). - `rt post-cut`: the manifest push (`cmd/rt/post_cut.go:272-275`). - `rt manifest-pr`: the manifest PR's base (`cmd/rt/manifest_pr.go:149`). - `rt default-branch`: used by recover-pending-cut (`reusable-recover-pending-cut.yml:414`) and by the cut's post-condition step (`reusable-release.yml:983`). The `"main"` literals left in `cmd/rt`: - `rt prep`'s last-resort backstop, reached only when every layer fails (`prep.go:731`). - Env-only fallbacks in `manifest-precheck` (`:111`), which no workflow calls, and in `manifest-postcondition` (`:282`), whose result CI overrides. - `--branch`/`--base` flag defaults on `status-context-check`, `pre-push` and `repin`, which are toolkit-side tools. **2. The "dispatch input" route does not exist.** - The docs name it three times: `:580` ("`default_branch` ranks an explicit dispatch input at the top"), `:590` ("which a dispatch input can set") and the layer-1 row at `:639`. - None of the four reusable workflows declares an input that carries a branch. Their `workflow_call` inputs were listed at `6a36090`, and no name contains "branch". - An adopter's own dispatch input can only reach a reusable through `with:`, and there is no `with:` slot for this. **3. The "Environment override example" (`:666-675`) cannot reach `rt`.** - It puts `env: RT_DEFAULT_BRANCH: trunk` on a job that calls the reusable through `uses:`. - Each step that reads layer 1 sets `RT_DEFAULT_BRANCH: ${{ vars.RT_DEFAULT_BRANCH }}` in its own `env:` (`reusable-release.yml:615`, `reusable-recover-pending-cut.yml:256`). Under Actions env precedence a step-level key replaces any inherited value, with an empty string when the variable is unset. So even if Forgejo passed the caller's `env:` into the called workflow, `trunk` would not reach `rt`. - Not measured: whether Forgejo rejects `env:` on a `uses:` job, as GitHub's workflow syntax does, or ignores it. **4. The wrapper triggers are left at `main`, and the section does not say to change them.** The wrappers the docs ask adopters to copy trigger on `branches: [main]`: - `docs/integration.md:866` (`release.yml`), `:1197` (`pr.yml`) and `:1370` (`prepared-uncut-check.yml`); - `README.md:249`; - the four example wrappers in `examples/{go,node}-project/.forgejo/workflows/{release,pr}.yml`. An adopter on `master` who copies them as they are gets no automatic cut: `release.yml` runs only through its `workflow_dispatch` trigger. The PR gates never run at all. Nothing in the "Default branch" section mentions this. **5. "Picked up automatically" holds at two of three callsites.** `:677` says the reusable picks up `vars.RT_DEFAULT_BRANCH` automatically. That is true at the act-on-decision step and at recover-pending-cut. It is not true at the cut's post-condition step: #1564 covers that in code. ## Why it matters This section is what an adopter on `master`, `trunk` or `develop` reads first. Today it tells them the toolkit mostly assumes `main`, which would put them off for no reason, and it offers two override routes that do nothing. It also misses the one edit they really need, the wrapper triggers. Without that edit, a push never starts a release, and the PR gates never run. ## Acceptance criteria - [ ] `:633` describes the current behaviour. The toolkit resolves the default branch wherever it targets it, and refuses rather than guessing. Name the one remaining guess, `rt prep`'s backstop, if it still exists when this lands. - [ ] The dispatch-input route is removed from `:580`, `:590` and the layer-1 row at `:639`. The section names the two routes that do reach the toolkit: the `vars.RT_DEFAULT_BRANCH` repo variable and `default_branch:` in `release-toolkit.yml`. - [ ] The "Environment override example" (`:666-675`) is removed, or replaced with the repo-variable route. - [ ] The section tells an adopter whose branch is not `main` to change `branches: [main]` in each wrapper they copy, and names the wrappers. - [ ] `:677` stays accurate after #1564 lands, or names the step it does not yet cover. - [ ] `rt register-check` and `scripts/anchor-check.py` pass on every changed doc.

claude added the

labels

2026-10-06 12:05:17 +02:00

claude referenced this issue

2026-10-06 12:05:27 +02:00

bug(release): the post-condition step's rt default-branch call gets neither override variable and no API token #1564