On this page
Who will ask about thisTop questions & answersTroubleshooting quick tableEscalate to engineering whenFor Support
Audience note. The "users" of this feature are the Dentolize engineering and QA team, not dental clinics. Clinics will never see it. This page is an internal support/enablement guide for the people who dispatch the pipeline and read its output.
Who will ask about this
Engineers opening PRs, QA reviewers steering the pipeline, and anyone confused about why the old QA GitHub issues stopped appearing.
Top questions & answers
"Where did the per-story GitHub issues go?" Retired in this PR. Test cases are now Jira Stories on an epic, not GitHub issues. The PR keeps one summary comment (### 🧪 Quality Review) with links to the Jira epic and Confluence page. (Removed in .github/workflows/sandbox-qa.yml; see What Changed.)
"How do I start QA on my branch?" Actions tab → Sandbox QA → Run workflow → pick your branch → pick a phase. Start with prepare (the default). It's dispatched on a branch, not from the PR page.
"I ran prepare but no comment appeared on my PR." The comment step only runs if the branch has an open PR and the agent emitted QA_STATE_DIR. No open PR → the QA work still runs but nothing is posted (.github/workflows/sandbox-qa.yml:86). Open the PR first, then re-run.
"I edited the epic — do I need to tell the pipeline?" No. The next test run reads the epic's current Stories. Your edits are the plan. Just dispatch test when you're ready.
"I commented on a ticket. Will the agent see it?" On the next retest/fix, the agent reads human comments newer than its own and treats them as instructions (per the header contract, .github/workflows/sandbox-qa.yml:17-18). That logic runs on the homelab agent, not in the workflow.
"test didn't test a Story I expected." test runs the epic's Stories as they are at dispatch time. If a Story was deleted/renamed at the gate, that's why. Re-add it to the epic and re-run.
"A fix run pushed a commit — will that trigger a redeploy loop?" No. Fix commits carry [skip ci], so sandbox.yml won't redeploy; the fix phase redeploys the sandbox itself (single-slot runner constraint, header :22-26).
"Can I run test and fix at the same time?" No. Concurrency is one QA phase per branch, and a running phase is never cancelled (.github/workflows/sandbox-qa.yml:44-46). Wait for the current one to finish.
"The job failed but there's still a comment / artifact." Both post-steps use if: always() && steps.qa.outputs.QA_STATE_DIR (:67, :117) — they run even on a failed agent step as long as a state dir exists. Check the run artifact (sandbox-qa-<slug>-<run_id>, 14-day retention) for the agent log.
Troubleshooting quick table
| Symptom | Likely cause | Where |
|---|---|---|
| No PR comment | No open PR for the branch, or no QA_STATE_DIR | :82-86, :67 |
| Comment has no Jira/Confluence link | Agent didn't emit JIRA_EPIC_URL/CONFLUENCE_URL (links are optional) | :95-96 |
| Wrong tests ran | Epic was edited at the gate; test uses current Stories | phases.md |
| Fix loop fear | [skip ci] + self-redeploy prevent it | header :22-26 |
| Two runs blocked | Concurrency group, no cancel | :44-46 |
Escalate to engineering when
- The agent binary errors before emitting
QA_STATE_DIR(nothing to comment, nothing to upload) — it's a homelab/sandbox-qaissue, outside this repo. - Jira/Confluence pages aren't being created despite a green run — that's inside
qa-agent/atlassian-qa.py, not the workflow.