# 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                         |
| **UAT sign-off**          | Product + design + eng | Human review before prod is live |
| 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/l/catalog-environment-promotion) for
full promotion paths.

## Promotion gates

### Staging → production (full UAT)

Both `deploy_redhat_catalog_staging` and `deploy_redhat_catalog` trigger
automatically on merge to `main` (when catalog files change). UAT is a
human review layer that runs concurrently with the automated deploys —
if UAT reveals issues, the release owner must roll back production.

Required before a release is considered complete:

1. `deploy_redhat_catalog_staging` succeeded on `main`
2. 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)
3. **UAT sign-off** recorded (checklist + Jira comment; git record in
   `redhat-catalog/docs/uat-records/`)

<!-- 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`; roll back production if already deployed, fix
  defects on staging, and re-run UAT.

### 4. Record production promotion (engineering release)

1. Verify Jira release ticket has `uat-pass` and linked sign-off record.
2. Production deploys automatically on merge to `main` — confirm
   `deploy_redhat_catalog` succeeded in the GitLab `main` pipeline.
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
- [ ] Production deploy green (auto-triggered on merge)
- [ ] 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 verify

- [ ] deploy_redhat_catalog succeeded in main pipeline
- [ ] Post-deploy verification
```

## Related documentation

- [UAT checklist][redhat-catalog-uat-checklist]
- [UAT records][redhat-catalog-uat-records]
- [Environment promotion](https://hummingbird-project.io/l/catalog-environment-promotion)
- [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)
