Skip to content

ci(#11292): add AndraBot to static check external contributor PRs#11293

Open
dianabarsan wants to merge 4 commits into
masterfrom
pr-bot
Open

ci(#11292): add AndraBot to static check external contributor PRs#11293
dianabarsan wants to merge 4 commits into
masterfrom
pr-bot

Conversation

@dianabarsan

@dianabarsan dianabarsan commented Jul 23, 2026

Copy link
Copy Markdown
Member

Description

Adds AndraBot, a GitHub Action that checks pull requests opened by external contributors and guides them through our contribution requirements before review.

On opened / edited / synchronize / reopened, for PRs whose author is not an OWNER / MEMBER / COLLABORATOR (bots are also skipped), it checks that:

  • the PR description follows the PR template — required sections are read from .github/PULL_REQUEST_TEMPLATE.md at run time, so template changes work without touching the script. Sections that are empty in the template (e.g. Description) must be filled in; pre-filled sections must be present.
  • the License section is unchanged from the template (whitespace-insensitive).
  • an issue is linked via GitHub's closing-keyword/Development linkage (GraphQL closingIssuesReferences).
  • the author is assigned to at least one linked issue.

When any check fails, the bot posts a single comment listing everything that needs fixing, labels the PR Waiting for contributor and fails the check. Once everything passes, the comment is replaced with a success message and the label is swapped for Ready for review. Compliant PRs never get a comment — just the Ready for review label — so reviewers can filter external PRs that have cleared the gate.

The bot maintains a single comment: when its content changes it is deleted and re-posted (comment edits do not notify the author, new comments do), and when a re-run produces identical content the comment is left untouched, so authors get exactly one notification per state change.

All comment texts live as markdown files in scripts/ci/andra-bot-messages/ with {{placeholder}} substitution, so wording can be edited without code changes (see the README there).

Implementation notes

  • The workflow uses pull_request_target because fork PRs only get a read-only token under pull_request, so the bot couldn't comment. It never checks out or executes PR code — checkout targets the base branch (sparse: scripts/ci and .github only) and all checks operate on API data. A documented zizmor dangerous-triggers suppression covers this (ignore entries must be workflow basenames — the pre-existing path-style entries in .github/zizmor.yml may be silently inert, worth a separate look).
  • Top-level permissions are empty; the job gets only contents: read, issues: read, pull-requests: write. Everything the bot does works with the default GITHUB_TOKEN — no PAT or app required. (Draft conversion was considered and dropped: the draft-state mutations are not available to app installation tokens, so labels are used instead.)
  • The Waiting for contributor and Ready for review labels must exist in the repo; a missing label degrades to a workflow warning, never a crash.
  • Comments are authored by github-actions[bot]; the AndraBot name appears as the check name. (A GitHub App would be needed for a real bot identity.)
  • Unit tests in webapp/tests/mocha/unit/testing-tests/andra-bot.spec.js (29 cases) cover all checks, the comment lifecycle and the label swaps, asserting against the real PR template and rendered message files so future edits to either don't break tests spuriously.

AI disclosure

Heavily used Claude for development.

closes #11292

Code review checklist

  • Readable: Concise, well named, follows the style guide
  • Documented: Configuration and user documentation on cht-docs
  • Tested: Unit and/or e2e where appropriate
  • AI disclosure: Please disclose use of AI per the guidelines. Written with Claude Code (supervised: design directed, code reviewed, tests verified by the author).

Compose URLs

If Build CI hasn't passed, these may 404:

License

The software is provided under AGPL-3.0. Contributions to this project are accepted under the same license.

Signed-off-by: Diana Barsan <barsan@medic.org>
Comment thread .github/workflows/andra-bot.yml Fixed
Comment thread scripts/ci/andra-bot.js Fixed
Comment thread webapp/tests/mocha/unit/testingtests/andra-bot.spec.js Fixed
Signed-off-by: Diana Barsan <barsan@medic.org>
…timize linked issue logic

Signed-off-by: Diana Barsan <barsan@medic.org>
@dianabarsan

Copy link
Copy Markdown
Member Author

PR with no description at all:

image

…changes instead of editing

Signed-off-by: Diana Barsan <barsan@medic.org>
@dianabarsan

Copy link
Copy Markdown
Member Author

PR with linked assigned issue, but no matching description.

image

@dianabarsan

dianabarsan commented Jul 24, 2026

Copy link
Copy Markdown
Member Author

PR linked to unassigned issue:
image

@dianabarsan

Copy link
Copy Markdown
Member Author

PR matching description but not linked to issue:
image

@dianabarsan

Copy link
Copy Markdown
Member Author

Ready for review:

image

@dianabarsan

Copy link
Copy Markdown
Member Author

License mismatch:

image

@dianabarsan
dianabarsan requested a review from andrablaj July 24, 2026 13:58
@dianabarsan

Copy link
Copy Markdown
Member Author

@andrablaj mind giving the general functionality a look?

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

Develop a GH action BOT that adds automated messages to PRs

2 participants