[EMB-359] zeus agent review trigger

[vinzenzLIFI]

Which Linear task is linked to this PR?

EMB-359 — feat: add "Agent review" label and Zeus QA trigger workflow

Why was it implemented this way?

This PR adds .github/workflows/qa-review-trigger.yml, which listens for the labeled event and fires a repository_dispatch to lifinance/QA when the "Agent review" label is applied to a PR. The receiving workflow (qa-review-embeddables-dispatch.yml, merged under QA-60) then runs Zeus and posts a structured review comment.

Two intentional deviations from the ticket spec:

1. Secret names: QA_APP_ID / QA_APP_PRIVATE_KEY instead of APP_ID / APP_PRIVATE_KEY
   The ticket originally proposed generic names (APP_ID, APP_PRIVATE_KEY). These were renamed with the QA_ prefix because the credentials are exclusively used by the lifi-qa-agent and the prefix makes their purpose unambiguous to anyone browsing the repo's secrets list. The org admin must provision secrets.QA_APP_ID and secrets.QA_APP_PRIVATE_KEY in lifinance/widget.

2. gh api instead of peter-evans/repository-dispatch
   Replaces a third-party action with a native gh api CLI call. This avoids an additional external action dependency while achieving the same result with the same SHA-pinned security posture.

Checklist before requesting a review

• I have performed a self-review and testing of my code.
• This pull request is focused and addresses a single problem.
• If this PR modifies the Widget API or adds new features that require documentation, I have updated the documentation in the public-docs repository.

[lifi-qa-agent]

🔍 QA Review — EMB-359 — PR #731

🔗 Linear Ticket · Pull Request #731 · 🔁 Re-review · ✅ Verdict: Pass

⚠️ New commit pushed after last QA review — re-analysing post-review changes.
Commit 3c282fd: "fix(workflow): use explicit expression syntax for if condition and narrow token scope"

---

🧠 What this PR does

Adds .github/workflows/qa-review-trigger.yml to lifinance/widget — a GitHub Actions workflow that listens for the labeled event and fires a repository_dispatch event to lifinance/QA when the "Agent review" label is applied to a PR. The receiving workflow (qa-review-embeddables-dispatch.yml, QA-60) then runs Zeus and posts a structured review comment. Uses gh api natively rather than the peter-evans/repository-dispatch third-party action (intentional deviation, documented in PR body).

---

📋 Acceptance Criteria Check

#	AC Item	Status	Notes
1	Agent review label exists in lifinance/widget	✅ Verified	This automated review being triggered is live end-to-end evidence
2	APP_PRIVATE_KEY and APP_ID are available in lifinance/widget (org admin task)	✅ Accepted deviation	Dev confirmed intentional rename to secrets.QA_APP_PRIVATE_KEY / secrets.QA_APP_ID; org admin directly informed; rationale documented in PR body
3	Trigger workflow is merged to main	⏳ Pending merge	Workflow is structurally correct — satisfied on merge
4	Applying "Agent review" label → Zeus comment within ~10 min	✅ Verified	This automated review is live evidence the full dispatch flow works

---

🔁 Resolution Status — All Previously Flagged Items

#	Item	Severity	Status	Resolution
1	Secret names diverge from AC-2 — org admin will provision wrong credentials	🟠 High	✅ Accepted	Justification in PR body + developer comment; QA_ prefix chosen intentionally; org admin informed
2	if: condition uses bare string without ${{ }} expression	🟡 Medium	✅ Fixed	Commit 3c282fd wraps the condition: if: ${{ github.event.label.name == 'Agent review' }}
3	PR body empty — intentional spec deviations undocumented	🟡 Medium	✅ Fixed	PR body now comprehensively documents both deviations (secret naming + gh api vs peter-evans)

All 3 previously flagged items are now resolved. No new issues found in the post-review commit.

---

🔍 Post-Review Commit Analysis (3c282fd)

Changed file: .github/workflows/qa-review-trigger.yml (+2/-1)

Change 1 — if: condition fix (Issue 2):

-    if: github.event.label.name == 'Agent review'
+    if: ${{ github.event.label.name == 'Agent review' }}

✅ Exactly the one-line fix requested. Explicit expression syntax per GitHub security hardening guidelines.

Change 2 — Token scope narrowing (bonus security improvement):

           owner: lifinance
+          repositories: QA

✅ Restricts the GitHub App token to only the QA repository, reducing blast radius in the event of a compromised token. Not explicitly required but a welcome hardening.

---

🔎 Final Workflow Review

name: Trigger Zeus QA Review
on:
  pull_request:
    types: [labeled]
jobs:
  trigger-zeus:
    if: ${{ github.event.label.name == 'Agent review' }}
    runs-on: ubuntu-latest
    permissions:
      contents: read
    steps:
      - name: Create GitHub App token
        uses: actions/create-github-app-token@fee1f7d63c2ff003460e3d139729b119787bc349 # v2
        with:
          app-id: ${{ secrets.QA_APP_ID }}
          private-key: ${{ secrets.QA_APP_PRIVATE_KEY }}
          owner: lifinance
          repositories: QA
      - name: Trigger Zeus QA review
        env:
          GH_TOKEN: ${{ steps.app-token.outputs.token }}
          PR_URL: ${{ github.event.pull_request.html_url }}
        run: |
          jq -n --arg url "$PR_URL" \
            '{"event_type":"qa-review-embeddables","client_payload":{"pr_url":$url}}' | \
            gh api repos/lifinance/QA/dispatches --method POST --input -

Check	Result
if: condition uses explicit ${{ }} syntax	✅
Action pinned to 40-char commit SHA	✅ fee1f7d63c2ff003460e3d139729b119787bc349
Token scoped to repositories: QA only	✅
Job permissions minimal (contents: read)	✅
event_type matches dispatch workflow (qa-review-embeddables)	✅
client_payload.pr_url field matches expected payload structure	✅
jq and gh available on ubuntu-latest	✅ Pre-installed
PR body documents intentional spec deviations	✅

---

🧪 Test Coverage

Layer	Status	Notes
Unit (Vitest)	N/A	Workflow-only PR — no TypeScript changed
E2E (Playwright)	N/A	No UI flow changed
Integration smoke	✅ Live evidence	Label trigger → dispatch → Zeus review comment confirmed end-to-end by this very review

---

🔗 Downstream Impact

Fully compatible with qa-review-embeddables-dispatch.yml in lifinance/QA (QA-60 ✅). Payload structure (event_type: qa-review-embeddables, client_payload.pr_url) matches exactly. Token scope narrows to lifinance/QA only — no impact on other repos.

---

🤖 Zeus QA Agent — 2026-05-18 | Ticket coverage: Full

[lifi-qa-agent]

Requesting changes on 3 items — each requires either a code fix or an explicit acceptance comment with justification before this review is considered complete.

#	Severity	Type	Issue / File
1	🟠 High	Config	Secret names diverge from AC-2 — org admin will provision wrong credentials
2	🟡 Medium	Code	.github/workflows/qa-review-trigger.yml — if: condition uses bare string instead of ${{ }} expression
3	🟡 Medium	Config	PR body is empty — intentional spec deviations are undocumented

1. [High] Secret names diverge from AC-2 — org admin will provision wrong credentials

The ticket's AC-2 and Prerequisites section specify secrets.APP_PRIVATE_KEY and vars.APP_ID, but the workflow reads secrets.QA_APP_PRIVATE_KEY and secrets.QA_APP_ID. An org admin following the ticket will provision the wrong names, causing the Create GitHub App token step to fail silently. Either update Linear AC-2 to match the workflow's names (secrets.QA_APP_ID + secrets.QA_APP_PRIVATE_KEY, both as secrets), or align the workflow back to the ticket spec. Add a note to the PR description stating which names the org admin must provision.

2. [Medium] if: condition — use explicit ${{ }} expression syntax

Change line 9 from:

if: github.event.label.name == 'Agent review'

to:

if: ${{ github.event.label.name == 'Agent review' }}

The bare-string form works today but is ambiguous to readers and fragile if the label name ever includes YAML-special characters.

3. [Medium] PR body is empty — document intentional spec deviations

The PR silently changes vars.APP_ID → secrets.QA_APP_ID and replaces peter-evans/repository-dispatch with gh api. Both are defensible, but with an empty body, reviewers and the provisioning admin have no way to know these are intentional. Fill in the PR description explaining the rationale for each deviation.

💡 Once you've addressed the items above, re-apply the "Agent review" label to trigger an automated re-review.

[vinzenzLIFI]

@lifi-qa-agent — addressing the open medium/high items we're intentionally not changing:

Issue 1 (High) — Secret names diverge from AC-2
This is intentional. The ticket was written before the final naming decision was made. QA_APP_ID and QA_APP_PRIVATE_KEY were chosen over the generic APP_ID / APP_PRIVATE_KEY because these credentials are exclusively used by the lifi-qa-agent — the QA_ prefix makes that unambiguous to anyone browsing the secrets list. The org admin has been informed of the correct names. No change needed.

AC-1 — Label not verifiable from code
The Agent review label exists and is working. The fact that this very QA review was triggered proves it end-to-end. No action needed.

AC-4 — End-to-end not verifiable statically
Same as above — the label trigger, dispatch, and Zeus review comment are all live evidence that the full flow works. No action needed.

Test coverage — Integration smoke test missing
This workflow is not part of the widget product — it calls out to a separate repo (lifinance/QA) where the QA agent itself is tested. A smoke test in this repo is out of scope.

[lifi-qa-agent]

Requesting changes on 1 item — it requires either a code fix or an explicit acceptance comment with justification before this review is considered complete.

#	Severity	Type	Issue / File
1	🟡 Medium	Code	.github/workflows/qa-review-trigger.yml — if: condition uses bare string without explicit ${{ }} expression

1. [Medium] if: condition — use explicit ${{ }} expression syntax

.github/workflows/qa-review-trigger.yml line 6 still reads:

if: github.event.label.name == 'Agent review'

This item was flagged in the first review and has neither been fixed in code nor addressed in the developer response (Issues 1 and 3 were addressed, but Issue 2 was not mentioned). The recommended form is:

if: ${{ github.event.label.name == 'Agent review' }}

The bare-string form works correctly in GitHub Actions today, but the explicit ${{ }} wrapper is recommended by GitHub's security hardening guidelines and aligns with the convention used in other workflow files in this repo. This is a one-line change. Alternatively, leave an explicit comment accepting the bare-string form with justification — either resolves this item.

💡 Once you've addressed the items above, re-apply the "Agent review" label to trigger an automated re-review.

[lifi-qa-agent]

All 3 previously flagged items resolved. Issue 2 (if: bare string) fixed in commit 3c282fd with explicit ${{ }} syntax; bonus token scope narrowing added. Workflow is clean, SHA-pinned, and live end-to-end. ✅ QA Pass.

[effie-ms]

Suggestion:

  concurrency:
    group: qa-review-${{ github.event.pull_request.number }}
    cancel-in-progress: true

We can add it to handle cases if someone removes and re-applies the label quickly, and two dispatch runs fire. So a concurrency group with cancel-in-progress: true would deduplicate.

[vinzenzLIFI]

good idea. addressed

[effie-ms]

timeout-minutes: 5
It will be useful if anything gets stuck, default 6 hours timeout might be long.

[vinzenzLIFI]

true, this can happen. Added the timeout! thank you