qa-deploy-pr

name	qa-deploy-pr
description	[QA Methodology] Gather ALL fresh CI prerelease artifacts for a change (modules + platform + vc-frontend) and deploy them together to the test env (vc-deploy-dev@<TEST_ENV branch>) in ONE manifest update: resolve a tracker ticket's linked PRs across all repos (or an explicit --module/--platform/--theme/--pr set) → each PR's latest vc3prerelease build → minimal-diff repin of backend/packages.json (AzureBlob/BlobName + PlatformVersion) and theme/artifact.json → dry-run combined diff (default) or a gated deploy PR (direct same-repo when the account has write, else a fork PR) → --verify polls the env-branch pin + /api/platform/modules per target. Never merges (a human merges to deploy); writes route through gh's keyring token; prints the web-edit URL when it can't push. Unblocks /qa-test PR#N and /qa-verify-fix.
argument-hint	<ticket-key> [--pr owner/repo#N ...] [--module Id=Ver ...] [--platform Ver] [--theme <url>] [--env <name>] [--apply] [--verify]
disable-model-invocation	true

/qa-deploy-pr — deploy a change's PR artifacts to the test env

/qa-test PR #N and /qa-verify-fix <ticket-key> both need the change live on the test environment before they test/verify — today they only detect whether it is deployed and warn-and-wait. This skill closes that gap. A real change is rarely one PR: a feature/fix spans a module + its xAPI + the storefront, each with its own fresh CI prerelease artifact. This skill gathers all of them and repins them together, in one manifest update, onto the env's vc-deploy-dev branch — then a human merges to deploy.

Ask before writing. Dry-run is the default and writes nothing. Any write (--apply) is gated on an explicit confirmation, goes to a fork branch + a PR, and never merges — a human merges vc-deploy-dev to deploy. Revert the pin after verification.

Why a deterministic script (+ a thin agent layer)

Resolution + the manifest math + the fork/PR mechanics are deterministic — they live in scripts/deploy/deploy-pr-artifact.ts (npm run deploy:pr). The agent's only job is to pick the input (ticket vs explicit set), read the resolved table, and decide whether to --apply. The script reuses the repo's established building blocks: the PR→vc3prerelease artifact resolver from qa-local-env/resolve-task.mjs, the AzureBlob/BlobName merge contract from qa-local-env/gen-manifest.mjs, the module Id↔repo map (config/module-repo-map.json), and the manifest-commit + /api/platform/modules patterns from scripts/hotfix/hotfix-deliver.ts.

Usage

# DRY-RUN (default) — resolve every artifact, print the combined diff + web-edit URL. No writes.
npm run deploy:pr -- <ticket-key>                       # all of the ticket's linked PRs
npm run deploy:pr -- <ticket-key> --env=vcst            # explicit env (default = resolved TEST_ENV)
npm run deploy:pr -- --pr=VirtoCommerce/vc-module-cart#412 --pr=VirtoCommerce/vc-frontend#2280
npm run deploy:pr -- --module=VirtoCommerce.Cart=3.1007.0-pr-412-ab12 --theme=<vc3prerelease-url>

# VERIFY (read-only) — is the bundle already deployed on the env? (branch pin + live modules API)
npm run deploy:pr -- <ticket-key> --verify

# APPLY (gated write) — commit the bundle to your vc-deploy-dev fork + open ONE cross-fork PR.
npm run deploy:pr:apply -- <ticket-key> --env=vcst      # a human reviews + merges to deploy

What it does

1. Resolve the artifact set = the union of the ticket's linked PRs and any explicit --pr/--module/--platform/--theme. Each PR yields its latest vc3prerelease build ({Id}_{Version}.zip → module/platform; vc-theme-*.zip → storefront). PRs whose CI hasn't published yet are flagged and omitted.
   • Ticket → PRs is tracker-driven. The explicit --pr/--module path is fully tracker-agnostic. Ticket-key auto-resolution uses the configured tracker's dev links (Jira today, via JIRA_EMAIL/JIRA_API_TOKEN); on Azure Boards (or when the tracker has no GitHub dev-links) pass the PRs explicitly with --pr.
   • vc-platform PRs publish a CONTAINER IMAGE, not a blob zip. Their body leaves ### Artifact URL: empty and carries Image tag: ghcr.io/VirtoCommerce/platform:<tag> instead, so the resolver falls back to that line. Without it every platform PR reported "no vc3prerelease Artifact URL yet (CI still running?)" forever, no matter how long you waited.
2. Compute one combined diff against the env-branch backend/packages.json (each module → AzureBlob {Id,Version,BlobName}, dropped from GithubReleases; platform → PlatformVersion+PlatformImageTag) and theme/artifact.json (the theme URL).
3. Deliver per the gate below.
4. --verify reports, per target, whether it is pinned on the branch and its live /api/platform/modules version (platform → /health; theme → branch URL match).

Environments (branch ↔ TEST_ENV — never hardcode)

env (--env/TEST_ENV)	vc-deploy-dev branch	source
vcst (default QA)	vcst-qa	BRANCH_MAP (.env.vcst has no DEPLOY_* block)
vcptcore (second QA)	vcptcore-qa	BRANCH_MAP — the branch carries a -qa suffix the env name doesn't; there is no bare vcptcore branch
virtostart	same name	convention
vcptcore_stable / vcptcore_regression	vcptcore-stable / -regression	.env.vcptcore_<key> DEPLOY_*

Both QA envs are BRANCH_MAP entries, not convention: env name ≠ branch name for either. A new env whose branch differs from its name needs a BRANCH_MAP row or a DEPLOY_BRANCH in its .env.<env>.

--verify's live column needs the env's admin password. It is read in config.js's own promotion form first — ADMIN_PASSWORD_<ENV> (e.g. ADMIN_PASSWORD_VCPTCORE) — then the ADMIN_PASSWORD_VCPTCORE_<STABLE|REGRESSION> forms, then generic ADMIN_PASSWORD. A missing per-env password degrades --verify to branch-pin-only (live reads ?), it never fails the run.

JIRA_EMAIL belongs in .env.local, next to JIRA_API_TOKEN — they are the two halves of one Basic-auth pair. A committed .env.<env> copy pins one teammate's identity against every other teammate's token, and Jira answers 404 on a ticket that exists (not 401), which reads as "bad ticket key" rather than "bad auth". Ticket resolution is also non-fatal whenever explicit --pr/--module/--platform/--theme targets are given — the key then only labels the branch/PR.

BACK_URL (for --verify) + any DEPLOY_REPO/DEPLOY_BRANCH/DEPLOY_PACKAGES_PATH override come from .env.<env>. Adding an env is config-only.

Delivery gate (never merges; a human does)

--apply opens a PR and never merges (PR-merge is denied by the harness). It picks the delivery path from the account's actual permission on the deploy repo (repos/{owner}/{repo}/collaborators/{me}/permission):

• Write / maintain / admin → a DIRECT same-repo PR (the common case here): a branch <TICKET>-<branch>-deployment (matching the vc-ci convention, e.g. VCST-5505-vcst-qa-deployment) → the env branch. No fork.
• No write → a fork PR: fork the deploy repo to the account, push the branch, open a cross-fork PR into the env branch.
• Neither works → prepare-only: prints the minimal diff + the GitHub web-edit URL to hand to DevOps.

Token routing (important). Reads use the ambient fine-grained PAT (GIT_TOKEN), but that token lacks fork/PR rights on vc-deploy-dev. Writes go through gh with the keyring classic gho_ token (gh invoked with GITHUB_TOKEN/GH_TOKEN unset) — the credential the rest of this repo uses for VirtoCommerce writes (reference_github_token_routing). The old 403 denied to Lenajava1 in reference_deploy_module_pr_to_vcst_qa was the fine-grained PAT; the account actually has write via the classic token.

Minimal diff. The manifest edit is done as text surgery on the raw file (remove the GithubReleases {Id,Version} block, add a BlobName-only AzureBlob entry / swap the theme URL / bump PlatformVersion), so the PR is a clean few-line diff — not the whole-file JSON.stringify reformat. It verifies the result parses + carries exactly the intended change and falls back to a full reserialize (with a "hide whitespace" note) only if the manifest shape is unexpected.

Gotchas (baked into the output)

• Irregular manifest indent: the manifest may use an indent JSON.stringify can't reproduce, so the edit is done as raw-text surgery and only falls back to a full reserialize on an unexpected or ambiguous shape — then the PR body says to review with "Hide whitespace changes". Two shapes that used to trip the fallback are now handled minimally: an empty "Modules": [] AzureBlob source (a branch's first-ever prerelease pin — vcptcore-stable and -regression are both here today) and a re-pin of an already-pinned module (whose blob entry carries an Id the GithubReleases scan used to match by mistake). Note most env branches now round-trip through JSON.stringify(…, 2) exactly, where a plain reserialize is only 0–2 lines worse — the surgery layer is belt-and-braces plus "don't reformat DevOps's file", not a big win. Don't grow it further on diff-size grounds.
• A reserialize is a normal outcome, not a defect. The surgery deliberately refuses to guess: an ambiguous or unrecognised shape returns the safe reserialize instead of an edit, because a wrong-but-valid manifest deploys the wrong build. Known bail-outs: a module pinned twice, two entries sharing a line, a BlobName with no derivable version, a Version field that isn't at the entry's own indent.
• Prerelease pins are BlobName-only: AzureBlob prerelease entries are { "BlobName": "<Id>_<version>.zip" } with NO Id field — --verify recognises this shape, so a deployed prerelease reads as PINNED/LIVE (not a false MISSING). Entries written by the reserialize path instead carry Id+Version+BlobName; both work, and since pinnedModule() prefers an explicit Version over the filename-derived one, a re-pin rewrites that field too rather than leaving it stale (a stale Version would make the table and --verify report the wrong version). The end-state is asserted before anything is committed: pinnedModule() must resolve to exactly the intended {version, blobName}, from exactly one entry, or the run reserializes.
• Prerelease version not bumped: a PR artifact's module.manifest often keeps the base version (the -pr-… suffix lives only in the filename), so a live-version mismatch in --verify is an ADVISORY, not a failure — confirm by behaviour.
• PlatformVersion ≠ PlatformImageTag — they are two fields with two consumers. deploy-backend.yml reads only PlatformImageTag (→ the docker PLATFORM_TAG build-arg), so that is the field that decides which platform actually runs; nothing in the deploy repo reads PlatformVersion. A platform PR pin therefore keeps PlatformVersion at the tag's base semver (3.1053.0) and puts the full 3.1053.0-pr-3092-…-2588d613 tag in PlatformImageTag. Writing the tag into both left PlatformVersion a non-semver string; checking only PlatformVersion in --verify reported PINNED for a branch still running the old container. --platform accepts a bare version, a bare PR tag, a full ghcr.io/…:<tag> ref, or an explicit Ver=tag split.
• A platform PR pin also jumps the base version. A PR branched off dev builds at dev's version, so pinning it moves the env off its current release (e.g. 3.1051.0 → 3.1053.0) on top of the PR's own change. That is inherent to testing a platform PR build — note it, and revert the pin after verifying.
• Stale SPA bundle: after a deploy, clear the Playwright/MCP browser cache before verifying admin-SPA/storefront bundles (memory feedback_mcp_browser_cache).

STOP / rules

• Never merge. End at an open PR (or a prepared diff) for a human. Revert the pin after verify.
• One env at a time; env coords are data, never hardcoded.
• If no artifact resolves (all linked PRs still building, or none linked), STOP and report — do not guess a version.