Publish builds the catalogue and drops it on the runner floor

[iderex]

The publish workflow's one real step is go run . publish, which resolves the declared plugins, builds docs/manifest.json, and reports the bytes it wrote. Then the job ends. The checkout runs with persist-credentials: false and its own comment says why - no step pushes - so nothing the run builds ever reaches main:/docs, which is what Pages serves at flowfin.dev. The run has been green on every dispatch while the freshness watch reddened twice on the exact version the run had just built and discarded: requests 0.2.0.0-stable, resolved, written, never placed. A publish that cannot place is a validator wearing publish's name, and the green run beside the red watch is precisely the quiet disagreement this hub's checks exist to refuse.

#153 places today's manifest by hand through a pull request. What lands here is the mechanism: the publish run compares what it built against what main:/docs carries, and on a difference opens or updates a pull request with the new manifest - one standing branch, force-pushed, so repeated runs converge on one open pull request instead of a pile. The ruleset stays exactly as strict as it is; the run merges nothing itself. Done-when: a dispatch of publish, on a tree whose catalogue is behind a declared release, ends with a pull request open against main carrying the difference, and a dispatch on a current tree ends with no pull request and says so.

Estimated-Cost: 120

[iderex]

I cannot land this, and the reason is a repository setting rather than anything in the tree.

What the run already does, so that the missing half is exactly named

The comparison this asks for exists. publish.Place reads the digest of the file the target currently holds before anything is produced, compares it against the sum of the bytes on their way out, and returns Changed or Unchanged; catalogue.Route.Publish prints that verdict as wrote new bytes or nothing to write.

git grep -n 'before, err := digestOf' -- internal/publish/publish.go
internal/publish/publish.go:196:	before, err := digestOf(t.Path(root))

On a run of the default branch the checkout's docs/manifest.json is main:/docs/manifest.json, so the difference is already computed and already reported. What is missing is only the placing half: a branch pushed and a pull request opened.

Why the placing half cannot be built to run here today

A run's only credential is GITHUB_TOKEN. There is no other:

gh secret list --repo Flowfin/hub
gh variable list --repo Flowfin/hub

Both print nothing, and the run's environment sets GITHUB_TOKEN from secrets.GITHUB_TOKEN.

That token may not open a pull request on this repository:

gh api repos/Flowfin/hub/actions/permissions/workflow
{"default_workflow_permissions":"read","can_approve_pull_request_reviews":false}

The GitHub documentation for that page says what the setting behind that field decides: "use the Allow GitHub Actions to create and approve pull requests setting to configure whether GITHUB_TOKEN can create and approve pull requests" (Settings, Actions, General, under Workflow permissions).

The other half of the same reading is not a blocker and is worth separating from it. default_workflow_permissions being read is only the default, and a workflow's own permissions: key raises it, so contents: write for the push is an edit to .github/workflows/publish.yml. Creating the pull request is not, because that is the second field and no workflow key reaches it.

So the mechanism would push a branch and then fail on the step that opens the pull request, which is the Done-when's first sentence. A landing that ships a workflow whose last step cannot succeed is worse than this issue staying open: it turns a state somebody can act on into a red run somebody has to diagnose.

What unblocks it

Either of two, and both are yours:

• Turn on Allow GitHub Actions to create and approve pull requests for this repository, after which GITHUB_TOKEN with pull-requests: write is enough and nothing else is needed.
• Or add a credential that may open one, which is a secret and a wider blast radius than the setting.

I have assigned this to you and labelled it blocked-on-decision so it is subtracted from what a session reads as available work rather than being re-read every round.

Two things to settle in the same breath, so the landing is one piece of work

The standing branch does not have to be force-pushed. The body asks for one, "so repeated runs converge on one open pull request instead of a pile", and the convergence is what the force-push is for rather than the force-push itself. A run that checks the standing branch out, commits the new manifest on top of it and pushes fast-forward converges on the same single branch and the same single open pull request, and it never rewrites a history somebody may already have fetched. The pull request then reads as the sequence of catalogues it carried, which is a better record than one commit that keeps changing underneath a reviewer. I would build it that way unless you want the rewrite, and the difference is one line of the run rather than a different design.

decisions/release-procedure.md changes in the same landing. It records, under what a person does by hand, "Opening the pull request that carries the placed file, and merging it", and that sentence stops being true the moment this lands. The decision of record is where that is superseded, in the style that file already uses for its two superseded entries, rather than left to drift against the workflow.

[iderex]

What this waits on

Turning on the repository setting 'Allow GitHub Actions to create and approve pull requests' for Flowfin/hub. gh api repos/Flowfin/hub/actions/permissions/workflow answers {"default_workflow_permissions":"read","can_approve_pull_request_reviews":false}, and gh secret list --repo Flowfin/hub prints nothing, so a run holds GITHUB_TOKEN and that token may not open the pull request this issue's Done-when asks for. Adding a credential that may open one is the alternative and is a wider blast radius than the setting.

[iderex]

Done: the repository now answers {"default_workflow_permissions":"read","can_approve_pull_request_reviews":true}, so the run's own GITHUB_TOKEN may open the pull request the Done-when asks for - no stored credential, which is the right side of that alternative: a PAT in a secret is a standing key that outlives its purpose, the run token exists for the run. Declare contents and pull-requests write in the workflow's permissions block and build. Unblocking.

[iderex]

The mechanism landed in #158, merged as 2965a7189b464df17f731feca0803a8ac515492c. One of the Done-when's two sentences I have observed live; the other I have not, and this comment says which is which.

What landed

internal/carry, and go run . publish carry as the word that reaches it. On a run of the served branch it reads what that branch carries at docs/manifest.json, and where the catalogue it built differs, it commits the bytes to one standing branch, place/docs/manifest.json, and opens or updates a single pull request against the served branch. .github/workflows/publish.yml runs the verb with that word on both its triggers, holds contents: write and pull-requests: write on that one job and nothing at the workflow level, and still checks out with persist-credentials: false because no step uses git.

decisions/release-procedure.md supersedes the hand step that said opening the request was a person's, and keeps the merge exactly where it was.

The two things this asked to be settled in the same breath

The standing branch is committed on rather than force-pushed. Convergence on one open request is what the standing branch buys and the rewrite was only one way of getting there. The branch is created where it is absent and left where it is otherwise, so a history somebody may already have fetched is never replaced.

The comparison is against the served branch and not against the checkout. This is a departure from the reading in the first comment above, and it is worth the sentence. That reading is right that a default-branch run's checkout is main:/docs. What it does not cover is a run whose checkout is stale: comparing against the checkout, such a run finds a difference against a file it never read and opens a request whose diff against main is empty. Reading the served branch through the API costs one call and removes that case.

Done-when, second sentence: observed

A dispatch on a current tree ends with no pull request and says so. Run 33265824293, on main, green:

manifest.json: nothing to write, carrying 2 plugin(s) and 3 version(s).
nothing to carry: main already carries these bytes at docs/manifest.json, and no pull request was opened.

and from the other side:

gh pr list --repo Flowfin/hub --state open --json number --jq 'length'
0

That run also read main:/docs/manifest.json through the API with its own token, so the permissions granted on the job and the read half of the client are exercised against the real service rather than against a fixture.

Done-when, first sentence: NOT observed, and this stays a negative

A dispatch on a tree whose catalogue is behind a declared release has no instance to run against tonight. Nothing declared is unpublished at this commit, which is the same run's own verdict: nothing to write is the state where the produced catalogue and the served one are the same bytes. I am not going to manufacture a difference by editing a declaration and then report the result as an observation.

So the positive path is executed end to end against a server on the loopback interface, driving the real client rather than a fake, and the three calls that have never run against this repository are: creating the standing branch, committing to it, and opening the request. The permissions each of them needs were read live and are granted; what is unverified is the calls themselves.

What discharges this is the first run that meets a real difference, which is now automatic on the daily schedule rather than something anybody has to remember. Until then I am leaving this issue open rather than closing it on a half-met condition.

Two things a reader will meet before they read the code

A request opened with a run's own token creates no workflow run, so the checks on it do not start by themselves and it sits carrying no verdict rather than a red one. Closing it and reopening it starts them. That sentence is in the body the run writes, in the workflow comment, and in the decision record.

The commit the run makes is signed, because the whole route goes through the API rather than through git. The ruleset requires a verified signature with no bypass actors, so a commit pushed from a runner with a key the runner does not hold could never be merged, and a mechanism producing one would be building an unmergeable request every night.

Every guard was proven by deleting it

Ten deletions in internal/carry, ten reds from go test ./internal/carry -count=1:

RED  | a run off the served branch carries nothing
RED  | a current catalogue opens nothing
RED  | the standing branch is not committed to twice
RED  | an existing standing branch is left where it is
RED  | an open request is not opened again
RED  | a file the endpoint returned no bytes for is refused
RED  | a non-200 read is a read that did not happen
RED  | the slashes in a path are not escaped
RED  | an absent branch is a state rather than a failure
RED  | a write that answered wrongly is refused

Two of them took a second pass before they proved anything, and #158's body says what was wrong with the first pass.