Reviewing output
Review cycle changes and feedback, then approve the exact preview commit for the final merge.
Review in hlix works on one candidate per cycle: the head of the cycle branch after the build agent’s run finished. Nothing reaches the project’s preview branch until that exact commit passed review, and nothing reaches your default branch until a person merges the project’s one pull request.
Prerequisites
Section titled “Prerequisites”- A cycle whose build agent run finished
- Agency role to merge; a portal client the project was shared with can read the Review page
What review checks
Section titled “What review checks”When a cycle’s run finishes, it moves to review. The following checks use the exact cycle branch head in isolated Cloud Machines:
| Check | What it does |
|---|---|
| Your verify command | The repository’s own build or test command, run against the cycle’s head. See Verification. |
| The review agent | A separate, read-only agent compares the change with the request and with every checklist item’s requirement, inspects the running result where it can, and returns a verdict with comments. It never edits code. |
| Configured end-to-end tests | The project’s application tests run against the candidate. Tests tagged with a task ID link results to that checklist item. |
The review assesses changes against the request and checklist requirements. Editing an item’s requirement after approval voids that approval, and the cycle is reviewed again.
Review assesses the combined cycle branch, covering all of its checklist items.
When review rejects the work
Section titled “When review rejects the work”Review feedback returns to the cycle’s checklist:
- A finding that names a checklist item (a review comment on that item, or a failed test tagged with it) reopens that item with the finding as its feedback.
- Findings that name no item (a regression in an earlier cycle’s test, an untagged failure) add one
reviewitem that carries them.
The cycle returns to executing, and the next run of the same cycle works the reopened items on the same branch. Watch them move on the Cycles board. If review keeps disagreeing, the project manager is told and decides the next move. Three runs in a row that change nothing stop the cycle; its open work is then re-planned. See Review & QA gates.
When the cycle passes
Section titled “When the cycle passes”The approved commit lands on the project’s preview branch by fast-forward, so the preview only ever holds checked commits. If the preview moved in the meantime, hlix merges it into the cycle branch first and reviews the new head. A conflict there becomes a checklist item, “Merge the preview and resolve conflicts”, for the cycle’s next run. The next run continues from the cycle branch.
Read a cycle’s change and comment on it
Section titled “Read a cycle’s change and comment on it”You can read any cycle’s change and send it back with your own comments. A portal client the project was shared with can read and comment too.
GET /v1/api/cycles/:id/review returns the cycle’s evidence: the cycle branch compared with the commit it was cut from. A cycle in flight shows its live branch head. A delivered cycle shows the commit its review approved.
curl -sS "$HLIX_BASE_URL/v1/api/cycles/$CYCLE_ID/review" \ -H "x-api-key: $HLIX_API_KEY" \ -H "X-Organization-Id: $HLIX_WORKSPACE_ID"| Field | Meaning |
|---|---|
headSha |
The commit you are reading. Every comment is anchored to it. |
baseSha, baseRef, headRef |
Where the diff starts and which branches it compares |
files[], filesChanged, additions, deletions, commits |
The change. When filesTruncated is true, the counts are lower bounds. |
evaluator |
The review agent’s verdict, or null |
Comments live on the cycle:
| Request | What it does |
|---|---|
GET /v1/api/cycles/:id/review/comments |
Lists every comment. A comment anchored to an older head is still listed, with stale: true. |
POST /v1/api/cycles/:id/review/comments |
Adds a comment. Send headSha and body. For a line comment, also send path, side (base or head), lineStart and optionally lineEnd. |
PATCH /v1/api/cycles/:id/review/comments/:commentId |
Sends {"resolution": "resolved"} or {"resolution": "open"}. |
POST /v1/api/cycles/:id/review/request-revision |
Sends {"headSha": "…"}. Folds the unresolved comments on that head into one review item on the cycle’s checklist, and runs the cycle again on the same branch. |
A comment or revision request against a head that moved answers 409 with the current headSha: read the new change and try again. A revision request needs run access, the same as running the cycle. When every build agent is busy, the request is still accepted: the cycle waits as a draft, the answer says "started": false and "reason": "waiting_for_engineer", and the run starts on its own when a build agent is free.
Approve the final merge
Section titled “Approve the final merge”Delivered cycles accumulate on the preview branch. A pull request per repository carries that work into its default branch, and a person approves the merge. This is separate from any required initial proposal approval.
GET /v1/api/projects/:id/review returns what is ready:
curl -sS "$HLIX_BASE_URL/v1/api/projects/$PROJECT_ID/review" \ -H "x-api-key: $HLIX_API_KEY" \ -H "X-Organization-Id: $HLIX_WORKSPACE_ID"| Field | Meaning |
|---|---|
canMerge |
false for a portal client |
pullRequests[] |
Per repository: repoId, repoName, url, headSha (the commit you are approving) and baseBranch |
verifiedCycles |
Delivered cycles whose e2e suite verified them |
journeys[], passedJourneys, totalJourneys |
Every e2e test of every delivered cycle and its outcome |
POST /v1/api/projects/:id/review/merge with {"repoId": "…", "headSha": "…"} merges the reviewed commit. It requires manage access. If new work changes the preview, the API returns 409; refresh Review and approve the new head.
In the dashboard
Section titled “In the dashboard”The project’s Review tab shows the pull request per repository, every e2e journey and its outcome, and the merge action. Each cycle’s change, its comments and its e2e report (GET /v1/api/cycles/:id/e2e) are on the cycle.
If review looks stuck
Section titled “If review looks stuck”- The cycle sits in
review: the checks are running in their own Cloud Machines. The cycle’s timeline shows each one. - The cycle went back to
executing: review reopened items. Their feedback says why. {"error":"The reviewed pull request changed. Refresh Review before merging."}with409: new work landed on the preview after you read it.{"error":"Archived projects cannot be merged"}with409: unarchive the project first.