[multivac61]

Adds hercules-ci-effects' flakeUpdate to effects-lib. It takes the same arguments and behaves the same way, so a flake that keeps its lock current from a scheduled effect can drop hercules-ci-effects as an input. It's based on main, independent of #232/#233.

 herculesCI/
 ├── effects-lib.nix      # + flakeUpdate
+├── flake-update.nix     # the effect: same arguments as upstream's
+├── nixbot-open-pr.py    # open a PR (GitHub, Gitea, GitLab), GitHub auto-merge
 checks/
+└── effects-lib-flake-update.nix
 docs/EFFECTS.md          # flakeUpdate, and when the forge token cannot push

Same behaviour as upstream

I checked against effects/flake-update/effect-fun.nix and effects/modules/git-update.nix at hercules-ci-effects 6c58de7:

upstream	here
nix flake update --commit-lock-file per entry of flakes, with inputs and commitSummary; answers "n" to nixConfig	same
a new update branch starts from baseMergeBranch, or the default branch	same
an existing branch is merged, rebased, fast-forwarded or reset onto baseMergeBranch only when one is given (baseMerge.enable); otherwise it's updated as it stands	same
conflicts list the files; a failed fast-forward explains how to recover	same
uncommitted changes fail the effect; "No updates to push." otherwise	same
--force for reset, --force-with-lease for rebase	same
PR to the default branch, title pullRequestTitle (default `flake.lock`: Update), body pullRequestBody or the commit's; an existing PR or "No commits between" isn't an error	same; PRs also work on Gitea and GitLab (upstream: GitHub only)
autoMergeMethod on GitHub: enable auto-merge, or merge at once if the PR is in clean status	same, through GraphQL enablePullRequestAutoMerge
git, gh and nix (access-tokens) authenticate with tokenSecret (default GitToken) as user	git and nix with tokenSecret (default GitToken, so the forge token); user defaults to the forge's token user instead of git

Upstream also has a module argument for extending its modular effect, and support for nix older than 2.19. Neither applies here.

Why tokenSecret matters with nixbot's checkout

The checkout carries the forge token twice: in origin, and in url."https://x-access-token:<token>@host/".insteadOf "https://host/", which rewrites every URL on the forge. When the App installation can't write contents, that token can't push. A repository in exactly that situation had its nightly update fail with a 403. Pushing with a PAT to the plain URL didn't help either, because the insteadOf rewrote it back to the forge token. So the effect drops those rewrites and authenticates through a credential store holding tokenSecret, as upstream's git-auth does, which keeps the token out of URLs and error messages. With the default GitToken this changes nothing.

Tested

• The check runs the generated userSetupScript and effectScript twice per case, against a checkout set up as nixbot sets one up: forge token in origin and in an insteadOf. Behind it are local bare repositories at an http URL and a fake API for all three forges. The cases cover GitHub, Gitea and GitLab, reset vs. no base merge, auto-merge enabled, and auto-merge on a clean PR. It asserts the exact API requests, the pushed history, and the credentials git and nix got.
• With the insteadOf cleanup removed, the check fails with the 403 case's symptom: unable to access 'http://127.0.0.1:…/acme/widget.git/': … 501, because the push went to the fake API with the checkout's token.
• effects-lib-flake-update, effects-lib and treefmt build on aarch64-darwin. effects-lib-flake-update evaluates on x86_64-linux and aarch64-linux.

🤖 Generated with Claude Code

[multivac61]

Can I assist further with this PR. Is it too much cruft to bring into the repo maybe?