Dentolize · Jira/Confluence QA Pipeline Walkthrough
On this pageBusiness viewTechnical viewSee also

The Human QA Gates

The single most important idea in this PR isn't the tool switch — it's who decides what happens next. The pipeline deliberately stops between phases and treats a human's edits and comments as the authoritative instruction for the next phase. This page explains that loop.

Business view

There are two gates, and both are places where a person, not the machine, is in charge.

Gate 1 — after prepare: edit the epic

prepare fills a Jira epic with proposed test-case Stories. Then it stops. A QA person opens the epic and:

  • deletes Stories that are noise or nit-picks,
  • refines Stories whose steps or expected results are vague, and
  • adds Stories the agent missed.

Whatever the epic contains at the moment you dispatch test is exactly what gets tested. Nothing more, nothing less. The machine proposed a plan; you disposed of it and made it yours.

Gate 2 — after test: comment on the board

test runs the Stories and writes results onto each ticket. Then it stops. A QA person reviews the board and leaves comments:

  • "This FAIL is actually expected behaviour — close it."
  • "Re-run this one, the sandbox was mid-deploy."
  • "This is a genuine bug — hand it to fix."

When you next dispatch retest or fix, the agent reads the human comments that are newer than its own and follows them as instructions. Your comment isn't feedback for later — it's the next command.

Why this matters

An AI that can write code and push it to a branch is powerful and occasionally wrong. Putting a required human checkpoint before planning solidifies and before code gets fixed means the automation accelerates the QA team without ever taking the wheel away from them. The epic is the contract; the comments are the instructions.

Technical view

The gates are documented in the workflow header

.github/workflows/sandbox-qa.yml:10-16:

#               → QA gate: edit the epic natively (delete nit-picks, add or
#                 refine stories) before dispatching test.
...
#               → QA gate: review the board, comment on tickets.

And the "comments-as-instructions" contract for retest, .github/workflows/sandbox-qa.yml:17-18:

#   • retest  — re-tests non-Done tickets and any ticket with new human
#               comments (treated as instructions). Never commits.

How the workflow reinforces the gate

The workflow can't enforce a human edit — GitHub Actions has no way to block on "a person changed a Jira epic." Instead it reinforces the gate two ways:

  1. Phases are separate manual dispatches. There is no full-auto. You physically cannot get from prepare to test without a person clicking "Run workflow" again. The removal of the old full-auto option (see What Changed) is what makes the gate real.
  2. The summary comment tells you it's your move. After prepare, the PR comment literally says:

``js action === "prepare" ? "Stories are ready for the QA team's review in Jira. Delete, refine or add stories on the epic, then dispatch test." : "Results are on the Jira tickets (comments, screenshots, statuses). Open items = tickets not in Done." ``

.github/workflows/sandbox-qa.yml:98-100.

Where the "read human comments" logic lives

The mechanism that reads human comments "newer than its own" and treats them as instructions is inside the off-repo agent (sandbox-qa / qa-agent/atlassian-qa.py), not in this workflow file. The workflow's contribution is purely structural: it makes each phase a fresh, deliberate invocation so that by the time the agent runs retest, any comments a human left since the last run are simply "there" to be read.

Honesty note. This repository cannot show you the comment-diffing code — it isn't here. What it can show is the design intent (header comment) and the structural choice (manual, phase-by-phase dispatch with cancel-in-progress: false, :44-46) that the intent depends on. Treat the "reads comments newer than its own" behavior as a documented contract to verify against the homelab implementation, not as something provable from /work/repo.

The old gate, for contrast

The previous pipeline had a gate too, but a weaker one: it posted editable review and plan comments on the PR, and a later phase re-read your edits from those comments. This PR deletes that entire "fetch edited review/plan comments" step (it was ~20 lines of GitHub-script that read two magic-marker comments back off the PR — see What Changed). The gate moved from "edit a GitHub comment" to "edit a Jira epic and comment on tickets" — a real board instead of a text blob.

See also