fix(ci): persist Hacktoberfest tracker via a PR (protected-branch push was silently failing)

[priya-sundaram-dev]

What & why

The daily hacktoberfest_prep job has been reporting success while silently doing nothing. @cclauss flagged that the last scheduled run "made numerous changes but failed on git commit" (run 34223130868).

Root cause, from that run's log:

remote: error: GH006: Protected branch update failed for refs/heads/master.
remote: - Changes must be made through a pull request.
 ! [remote rejected] master -> master (protected branch hook declined)

master is protected, so the default GITHUB_TOKEN can't push to it directly. My original git push || echo "Nothing to push" swallowed the rejection, so the step went green and the refreshed tracker was thrown away.

Fix

Persist the refreshed docs/hacktober_2026_prep.md by opening — or updating in place — a single rolling PR (peter-evans/create-pull-request@v7) instead of pushing to master. Re-runs reuse the same branch, so there's never more than one open tracker PR, and a maintainer merges it whenever they want to capture a snapshot. The dry-run behaviour on push/pull_request and the intentional post-Oct-1 retirement failure are unchanged.

Adds pull-requests: write to the workflow permissions.

Heads-up: directory_writer.yml has the same latent bug

While tracing this I checked directory_writer.yml, which also pushes to master (git push --force ... || true). Its recent runs are also hitting GH006 and being masked by || true — e.g. run 34269173911 shows ! [remote rejected] HEAD -> master (protected branch hook declined). So DIRECTORY.md isn't actually being auto-updated anymore. Happy to send a follow-up PR converting that one the same way (or however you prefer) if useful.

One dependency to confirm

This relies on the org setting Settings → Actions → General → "Allow GitHub Actions to create and approve pull requests" being enabled. If it's off, create-pull-request will fail with a clear permissions error and we can either enable it or switch to a scoped app/PAT token — your call on which fits the repo's security posture. I only have public read access, so I couldn't verify the toggle myself.

Refs #15081, #15225

Checklist

• I have read CONTRIBUTING.md.
• This pull request is all my own work -- I have not plagiarized.
• I know that pull requests will not be merged if they fail the automated tests.
• This PR only touches CI/workflow configuration (no algorithm files added or changed).

[algorithms-keeper]

Closing this pull request as invalid

@priya-sundaram-dev, this pull request is being closed as none of the checkboxes have been marked. It is important that you go through the checklist and mark the ones relevant to this pull request. Please read the Contributing guidelines.

If you're facing any problem on how to mark a checkbox, please read the following instructions:

• Read a point one at a time and think if it is relevant to the pull request or not.
• If it is, then mark it by putting a x between the square bracket like so: [x]

NOTE: Only [x] is supported so if you have put any other letter or symbol between the brackets, that will be marked as invalid. If that is the case then please open a new pull request with the appropriate changes.

[cclauss]

https://docs.zizmor.sh/audits/#superfluous-actions Recommends using gh create instead of the superfluous peter-evans/create-pull-request

[priya-sundaram-dev]

Good call — switched the persist step over to the bundled gh CLI (gh pr create + a force-pushed rolling branch) and dropped peter-evans/create-pull-request entirely, per the superfluous-actions audit. Same behaviour: at most one open rolling tracker PR, updated in place on each scheduled run. Also marked the checklist above. Thanks for the review!

[cclauss]

Dry run is failing. Should I wait for that to be fixed or should I review and merge?

[priya-sundaram-dev]

Please give it one more push-CI cycle — I just fixed the dry-run failure (049c7df → new commit).

Root cause wasn't the persist logic you're reviewing: the GITHUB_TOKEN the runner hands us is capped at 1000 requests/hour per repository, shared across every concurrent run. Re-running this workflow a few times in one hour (plus the awaiting-reviews directory scan, which was hitting up to 400 /pulls/{n}/files endpoints) drained that shared budget, and one exhausted request then raised and killed the whole job — that's the giving up on .../issues/15105 traceback.

The refresh is best-effort, so it shouldn't ever fail CI on a transient rate limit. This commit:

• _request now honours Retry-After (secondary limits) and raises a typed BestEffortError once retries are exhausted;
• row resolution, the directory scan and the search counts catch it and degrade (leave the row unchanged / print unavailable (rate limited)) instead of crashing;
• trimmed the directory scan to 120 PRs and concurrency to 5 to stay well under the budget in the first place.

Net: the only non-zero exit is still the intentional post-Oct-1 retirement. Once the new dry run is green, it's good to review and merge. 🙏

[priya-sundaram-dev]

Green now ✅ — the scheduled hacktoberfest_prep dry-run passed on the current HEAD (3f66155): run 34296175316. All PR checks (build / ruff / build_docs / ty / pre-commit.ci) are also passing. Good to review and merge whenever you're ready — thanks for your patience through the rate-limit debugging.