[ci] Updated CI failure bot caller and docs

[stktyagi]

Checklist

• I have read the OpenWISP Contributing Guidelines.
• I have manually tested the changes proposed in this pull request.
• I have written new test cases for new code and/or updated existing tests for changes to existing code.
• I have updated the documentation.

Description of Changes

Updated the CI failure bot caller YAML and docs in accordance to the recent findings we gained while testing this feature in different openwisp modules.

Related to #616 #524.

[coderabbitai]

📝 Walkthrough

Walkthrough

This pull request reduces workflow-level GitHub Actions permissions from write to read (keeping contents: read), updates the PR author extraction to use .author.login // empty and treats both empty and the literal "null" as missing when emitting a warning, and adds a job-level permissions block that restores pull-requests: write, actions: write, and contents: read for the call-ci-failure-bot job. Documentation reflecting these changes was also updated.

Sequence Diagram(s)

(omitted)

Estimated code review effort

🎯 2 (Simple) | ⏱️ ~10 minutes

Possibly related PRs

• [chores:fix] Fixed mentions of ci failure bot #524 #608: Modifies find-pr/emit_pr logic and PR author extraction/propagation to call-ci-failure-bot.
• [ci:fix] CI Failure bot refinements #624: Adjusts CI-failure bot workflows and PR-author/permissions handling.
• [fix] Fixed context scope to prevent hallucinations #607: Changes CI failure workflow and author/actor handling related to PR author extraction and permissions.

Suggested reviewers

• nemesifier

🚥 Pre-merge checks | ✅ 2 | ❌ 1

❌ Failed checks (1 warning)

Check name	Status	Explanation	Resolution
Description check	⚠️ Warning	PR description is incomplete. The checklist shows documentation was not updated, but the raw summary and PR objectives indicate docs were modified. Additionally, no test cases were written/updated despite code changes.	Clarify the documentation update status and explain why no tests were added for the CI failure bot changes. If docs were updated, check the corresponding checkbox.

✅ Passed checks (2 passed)

Check name	Status	Explanation
Bug Fixes	✅ Passed	This PR is an infrastructure/workflow enhancement, not a bug fix, so the Bug Fixes check is not applicable and passes by default.
Title check	✅ Passed	The title follows the required format [type] and clearly describes the changes: CI workflow updates and documentation revisions for the CI failure bot.

_{✏️ Tip: You can configure your own custom pre-merge checks in the settings.}

✨ Finishing Touches

🧪 Generate unit tests (beta)

• Create PR with unit tests
• Commit unit tests in branch chores/improve-ci-failure-bot

---

Thanks for using CodeRabbit! It's free for OSS, and your support helps us grow. If you like it, consider giving us a shout-out.

❤️ Share

• X
• Mastodon
• Reddit
• LinkedIn

_{Comment @coderabbitai help to get the list of available commands and usage tips.}

[coderabbitai]

Actionable comments posted: 1

🤖 Prompt for all review comments with AI agents

Verify each finding against the current code and only fix it if needed.

Inline comments:
In @.github/workflows/bot-ci-failure.yml:
- Around line 71-74: The reusable workflow's permissions block currently
restricts actions to read, preventing the caller's granted actions: write from
taking effect and breaking the auto-retry step that uses `gh api -X POST`;
update the reusable workflow's permissions declaration (the permissions block in
reusable-bot-ci-failure.yml) to include `actions: write` instead of `actions:
read` so the `gh api -X POST` auto-retry step can run; keep the permission scope
minimal and document the change near the auto-retry/gh API usage (referenced by
the auto-retry step and its warning around the `gh api -X POST` call).

🪄 Autofix (Beta)

Fix all unresolved CodeRabbit comments on this PR:

• Push a commit to this branch (recommended)
• Create a new PR with the fixes

---

ℹ️ Review info

⚙️ Run configuration

Configuration used: Organization UI

Review profile: ASSERTIVE

Plan: Pro

Run ID: efa90b7e-3b62-4c4a-89a6-ea40ab28c09f

📥 Commits

Reviewing files that changed from the base of the PR and between 3e8c51a and 4ed7ddf.

📒 Files selected for processing (2)

• .github/workflows/bot-ci-failure.yml
• docs/developer/reusable-github-utils.rst

📜 Review details

🧰 Additional context used

🧠 Learnings (3)

📓 Common learnings

Learnt from: nemesifier
Repo: openwisp/openwisp-utils PR: 584
File: .github/workflows/reusable-bot-changelog.yml:22-24
Timestamp: 2026-03-05T14:23:55.528Z
Learning: In `.github/workflows/reusable-bot-changelog.yml`, the maintainer (nemesifier) has explicitly decided that `github.event.review.author_association == 'COLLABORATOR'` should be allowed (alongside `OWNER` and `MEMBER`) to trigger the changelog bot workflow. The rationale is that the workflow is non-destructive and only posts a PR comment — it cannot make code changes. Do not flag `COLLABORATOR` as a security issue for this workflow.

📚 Learning: 2026-03-05T14:23:55.528Z

Learnt from: nemesifier
Repo: openwisp/openwisp-utils PR: 584
File: .github/workflows/reusable-bot-changelog.yml:22-24
Timestamp: 2026-03-05T14:23:55.528Z
Learning: In `.github/workflows/reusable-bot-changelog.yml`, the maintainer (nemesifier) has explicitly decided that `github.event.review.author_association == 'COLLABORATOR'` should be allowed (alongside `OWNER` and `MEMBER`) to trigger the changelog bot workflow. The rationale is that the workflow is non-destructive and only posts a PR comment — it cannot make code changes. Do not flag `COLLABORATOR` as a security issue for this workflow.

Applied to files:

• .github/workflows/bot-ci-failure.yml
• docs/developer/reusable-github-utils.rst

📚 Learning: 2026-03-05T09:38:10.320Z

Learnt from: pushpitkamboj
Repo: openwisp/openwisp-utils PR: 584
File: .github/workflows/reusable-bot-changelog.yml:49-49
Timestamp: 2026-03-05T09:38:10.320Z
Learning: In openwisp-utils, PR title prefixes are strictly limited to `[feature]`, `[fix]`, and `[change]` (exact bracketed tags, no scoping/sub-types). The regex `^\[(feature|fix|change)\]` in `.github/workflows/reusable-bot-changelog.yml` is intentional and correct — scoped variants like `[feature/bots]` are not valid and should not be matched.

Applied to files:

• .github/workflows/bot-ci-failure.yml
• docs/developer/reusable-github-utils.rst

🔇 Additional comments (4)

.github/workflows/bot-ci-failure.yml (2)

9-12: Good security improvement: reduced workflow-level permissions.

Reducing top-level permissions to read and selectively granting write only at the job level that needs it follows the principle of least privilege. The find-pr job only reads PR metadata, so read access is sufficient.

---

37-38: LGTM: Improved null handling in PR author lookup.

Using // empty ensures jq outputs nothing instead of the literal "null" when the author login is absent. The additional "null" string check provides a defensive fallback for edge cases where the API might return unexpected formats.

docs/developer/reusable-github-utils.rst (2)

385-388: Documentation accurately reflects the workflow changes.

The permission updates and jq expression changes in the documented example match the actual workflow file changes. Good practice keeping documentation synchronized.

Also applies to: 413-414

---

447-450: LGTM: Job-level permissions documented correctly.

The documented job-level permissions match the actual workflow implementation.

[coveralls]

coverage: 97.476%. remained the same
when pulling 75f0b13 on chores/improve-ci-failure-bot
into 3e8c51a on master.

[nemesifier]

Thanks for following up @stktyagi 🙏