# Red Hat Catalog UAT Program

LLMS index: [llms.txt](https://hummingbird-project.io/llms.txt) | Full content: [llms-full.txt](https://hummingbird-project.io/llms-full.txt)

---

User Acceptance Testing (UAT) for the Red Hat Catalog SPA — human sign-off on
staging before production promotion.

**Epic:** [HUM-2179](https://redhat.atlassian.net/browse/HUM-2179) · **Story:**
[HUM-2183](https://redhat.atlassian.net/browse/HUM-2183) · **Depends on:**
[HUM-2060](https://redhat.atlassian.net/browse/HUM-2060) (staging host +
promotion gates)

## Purpose

UAT complements automated validation (smoke, E2E, visual regression, security
scans). It catches product, content, and UX issues that automation does not
cover. UAT does **not** replace automated gates.

| Layer | Owner | Blocks prod? |
| ----- | ----- | ------------ |
| Unit / lint / MR security | CI | MR merge |
| Staging smoke + visual | CI | Manual prod job availability |
| **UAT sign-off** | Product + design + eng | **Manual prod deploy** |
| Post-prod smoke | CI / on-call | Rollback decision |

## Environments (disambiguation)

| Term | Meaning | URL pattern |
| ---- | ------- | ----------- |
| **Staging** | Pre-prod validation target for UAT | `https://images.staging.hummingbird-project.io` |
| **Experimental host** | Infra sandbox for `experiment/*` branches | `https://images.experimental.hummingbird-project.io/<branch>/` |
| **Former `/experimental` route** | Removed in-app product route (HUM-2171) | Returns **404** — use `/api` instead. See [archived-surfaces.md](https://gitlab.com/redhat/hummingbird/tools/-/blob/main/redhat-catalog/docs/archived-surfaces.md) |

See [Red Hat Catalog Environment Promotion](https://hummingbird-project.io/docs/background/tools/redhat-catalog-environments/) for
full promotion paths.

## Promotion gates

### Staging → production (full UAT)

All of the following are required before clicking `deploy_redhat_catalog`:

1. `deploy_redhat_catalog_staging` succeeded on `main`
2. `redhat-catalog-e2e-smoke` passed against staging
3. `visual_redhat_catalog_staging` passed (pre/post deploy diff)
4. MR-blocking security jobs clean (or approved exceptions) — see
   [security-scanning.md](https://gitlab.com/redhat/hummingbird/tools/-/blob/main/redhat-catalog/docs/security-scanning.md)
5. **UAT sign-off** recorded (checklist + Jira comment; git record in
   `redhat-catalog/docs/uat-records/`)

The prod deploy job is manual in GitLab; the release owner must verify UAT
before triggering it.

<!-- markdownlint-disable-next-line MD033 -->
<a id="light-uat-on-experimental-host"></a>

### Light UAT on experimental host

Experimental hosts are for iteration, not customer release. When opening an MR
from `experiment/<name>` to `main`, use a **light UAT** pass on the experimental
URL — not the full checklist:

| Check | Required? |
| ----- | --------- |
| Feature under test works on experimental host | Yes |
| No console errors on primary journey | Yes |
| Masthead/footer not broken | Yes |
| Full staging UAT checklist | No — runs on staging after merge |
| Named approver sign-off | Eng owner only (no prod gate yet) |

After merge, staging receives the **full UAT** before prod.

## Named approvers (staging → prod)

Confirm names with the product owner during checklist review (HUM-2060 open
question on approval owners). Until confirmed, use these roles:

| Role | Primary | Backup | Responsibility |
| ---- | ------- | ------ | -------------- |
| **Product** | _TBD_ | — | Catalog journeys, copy, feature completeness |
| **Design** | _TBD_ | — | Visual polish, layout, theme, responsive UX |
| **Engineering release** | _TBD_ | _TBD_ | Pipeline green, staging commit matches intent, prod deploy authorization |

Any **Block** from product or design stops prod promotion until defects are
fixed on staging and UAT re-run.

## Runbook — request and run UAT

### 1. Request UAT (release owner)

When `main` pipeline completes staging deploy + automated gates:

1. Create or reuse a **Release** ticket in Jira (label `redhat-catalog`, link
   HUM-2179 epic).
2. Comment with pipeline URL, commit SHA, and summary of user-facing changes.
3. Label ticket `uat-requested`.
4. Notify approvers (#hummingbird or team channel — use team default).

### 2. Execute UAT (approvers / delegates)

1. Open [uat-checklist.md][redhat-catalog-uat-checklist] against staging.
2. File results in `redhat-catalog/docs/uat-records/YYYY-MM-DD-<topic>.md`.
3. Log defects as Jira bugs linked to the release ticket.

**Expected turnaround:** 2 business days from `uat-requested` for routine
releases; same-day for hotfixes when approvers are available.

### 3. Sign off or block

- **Pass:** All checklist items pass or have accepted exceptions; all three
  approver rows signed; Jira comment posted (template below); label
  `uat-pass`.
- **Fail:** Label `uat-fail`; do **not** trigger `deploy_redhat_catalog` until
  staging is fixed and UAT re-run.

### 4. Promote to production (engineering release)

1. Verify Jira release ticket has `uat-pass` and linked sign-off record.
2. In GitLab `main` pipeline, run manual job `deploy_redhat_catalog`.
3. Comment on release ticket with prod pipeline URL.

## What blocks release

| Blocker | Who resolves |
| ------- | ------------ |
| Staging smoke or visual CI failed | Engineering |
| Open Critical/High security finding without exception | Engineering + security |
| UAT checklist failure (product/design) | Engineering fixes → re-UAT |
| Missing approver sign-off | Approver |
| Staging commit ≠ intended release SHA | Release owner |

## Jira sign-off template

Post on the release ticket when UAT completes:

```text
h3. UAT sign-off — staging → prod

*Staging URL:* https://images.staging.hummingbird-project.io
*Commit:* {full SHA}
*Pipeline:* {GitLab pipeline URL}
*Checklist record:* redhat-catalog/docs/uat-records/{filename}.md

||Role||Name||Decision||
|Product|{name}|Approve / Block|
|Design|{name}|Approve / Block|
|Engineering release|{name}|Approve / Block|

*Result:* Approved for prod / Blocked
*Defects:* {HUM-xxx links or "none"}
*Tester:* {name}, {date}
```

### Suggested Jira labels

| Label | Meaning |
| ----- | ------- |
| `uat-requested` | Staging ready; waiting for human validation |
| `uat-pass` | Full sign-off complete |
| `uat-fail` | Blocked; defects logged |
| `uat-light` | Experimental → staging spot-check only |

Optional custom field (if added in Jira project settings): **UAT status**
(`Not started` / `In progress` / `Passed` / `Failed`).

## Release ticket template

Create a Jira **Task** or **Release** issue per prod promotion:

```markdown
## Release summary
- **Target:** staging → production
- **Commit:** 
- **User-facing changes:** 

## Automated gates
- [ ] Staging deploy green
- [ ] Smoke passed
- [ ] Visual regression passed
- [ ] Security scans clean (or exceptions documented)

## UAT
- [ ] Checklist completed ([uat-checklist.md](link))
- [ ] Sign-off record filed ([uat-records/](link))
- [ ] Product approve
- [ ] Design approve
- [ ] Engineering release approve

## Prod promote
- [ ] deploy_redhat_catalog triggered
- [ ] Post-deploy verification
```

## Related documentation

- [UAT checklist][redhat-catalog-uat-checklist]
- [UAT records][redhat-catalog-uat-records]
- [Environment promotion](https://hummingbird-project.io/docs/background/tools/redhat-catalog-environments/)
- [Testing guide — promotion gates][redhat-catalog-testing-guide-gates]

[redhat-catalog-uat-checklist]: https://gitlab.com/redhat/hummingbird/tools/-/blob/main/redhat-catalog/docs/uat-checklist.md
[redhat-catalog-uat-records]: https://gitlab.com/redhat/hummingbird/tools/-/tree/main/redhat-catalog/docs/uat-records/
[redhat-catalog-testing-guide-gates]: https://gitlab.com/redhat/hummingbird/tools/-/blob/main/redhat-catalog/docs/testing-guide.md#promotion-gates-hum-2060

## Out of scope

- Automating UAT (Playwright covers regression; UAT stays human)
- Legal/compliance sign-off (separate security program)