feat(specs): add integration deployment spec for automated main to hcmai-01

[squizzi]

Summary

• Adds specs/platform/integration-deployment.spec.md defining the desired state for automated continuous deployment of ACP to the integration environment (hcmai-01) via ArgoCD and Konflux-built images
• Registers the new spec in specs/index.spec.md
• Linked to ENGPROD-10253 under the Deploy epic (ENGPROD-10254)

What the spec covers

Requirement	Key decisions
Image Source	Konflux images from quay.io/redhat-user-workloads/..., digest-pinned, provider model only (no credential sidecars)
Image Update Flow	Atomic commit to agent-gitops on internal GitLab after all Konflux builds pass
ArgoCD Continuous Sync	Auto-sync with prune, self-healing, PostSync hook gating
Integration Overlay	Mirrors full production resource set (no delete-patches) for promotion fidelity
Post-Deploy Verification	PostSync Job running the unified golden test suite (consolidation of existing suites planned)
Secret Management	HashiCorp Vault via secrets operator, not stored in GitOps
Deployment Gating	All Konflux pipelines green before image update
Rollback	Git revert in agent-gitops triggers ArgoCD re-sync to previous known-good

Cluster topology

Environment	Cluster	Purpose
Integration	hcmai-01	Automated deploy of main
Stage	hcmai-02	Promotion target
Production	hcmai-03	Production

Test plan

• Spec follows RFC 2119 keyword convention with Given/When/Then scenarios
• Konflux image names verified against .tekton/ pipeline definitions
• Overlay design aligned with existing overlays/hcmais/ pattern (adapted for production parity)
• No code changes — spec only

[jsell-rh]

🤖 Amber Review — PR #468

Well-structured spec with solid rationale and good Given/When/Then coverage. The ArgoCD PostSync hook sequencing (wave 0 bootstrap → wave 1 verify) is correct, and the pull-based deployment rationale for the VPN-only ROSA cluster is clearly explained. Two issues need resolution before this ships.

Major: Credential sidecar "SHALL NOT be built" conflicts with existing Tekton pipelines

The spec states: "Credential sidecar images SHALL NOT be built or deployed."

However, .tekton/ still contains active push pipelines for all four sidecars:

• .tekton/credential-github-main-push.yaml
• .tekton/credential-google-main-push.yaml
• .tekton/credential-jira-main-push.yaml
• .tekton/credential-k8s-main-push.yaml

A spec that says SHALL NOT be built while the pipelines still exist is inaccurate and will confuse /reconcile. Either:

1. Soften to "Credential sidecar images SHALL NOT be deployed to integration — they are deprecated and their pipelines will be decommissioned separately", or
2. Link to the follow-up issue that removes the Tekton pipelines

Major: MCP server image disposition is ambiguous

The component table lists 5 images but the acp-mcp-main image exists in .tekton/acp-mcp-main-push.yaml. The spec hedges: "The MCP server image MAY be excluded if the openshell provider flow does not require it." This leaves the spec non-deterministic. Add a row for acp-mcp-main in the component table and change MAY to either MUST or SHALL NOT with a clear condition.

Minor: Spec index Components field doesn't follow existing convention

All other entries use component abbreviations (CP, BE, FE, Runner, API, SDK). The new entry uses Manifests, CI/CD, GitOps — prose rather than abbreviations. Suggest: Manifests, CP or align with the abbreviation set used in neighboring rows.

What's verified ✅

• All 5 listed Konflux image names match .tekton/ push pipeline output-image params exactly
• Spec follows RFC 2119 keyword convention throughout
• Given/When/Then scenarios are present for every requirement
• No code changes — spec only
• Overlay structure references the correct overlays/hcmais/ pattern

Confidence: High — image name verification is definitive, pipeline presence is observable in the repo.

— Amber

[YiqinZhang]

🤖 Amber Follow-Up — PR #468: feat(specs): add integration deployment spec for automated main to hcmai-01

Re-checking after the new commit (8c9d13f — "fix(specs): rewrite image update flow to use Konflux Release pipeline"). The image update flow section is improved — the 7-step Konflux Release pipeline approach with ReleasePlan/ReleasePlanAdmission is clearer than what was there before.

However, the three issues from the earlier CHANGES_REQUESTED review remain open:

Still unresolved:

1. Credential sidecar "SHALL NOT be built" vs live Tekton pipelines (Major): The spec contains normative language that credential sidecar images SHALL NOT be built. Four active push pipelines remain in .tekton/ that build exactly those images. This spec will be consumed by /reconcile and the contradiction will surface as a gap. Options: soften to "SHALL NOT be deployed to integration — pipelines decommissioned separately" or link a tracking issue for pipeline removal.

2. MCP server MAY ambiguity (Major): The component table still hedges with "MAY be excluded if the openshell provider flow does not require it." This makes the spec unresolvable. Replace with either MUST (it is deployed) or SHALL NOT (it is excluded), with an explicit condition if conditional.

3. Index abbreviation convention (Minor): The entry still uses prose (Manifests, CI/CD, GitOps) where neighboring entries use short abbreviations (CP, BE, FE, Runner). Align with the established style.

The amber/change-requested label remains. Happy to re-review once these three points are addressed.

---

— Amber

[jsell-rh]

🤖 Amber Follow-Up — PR #468: feat(specs): add integration deployment spec for automated main to hcmai-01

Re-checking after the new commit (8c9d13f — "fix(specs): rewrite image update flow to use Konflux Release pipeline"). The image update flow section is improved — the 7-step Konflux Release pipeline approach with ReleasePlan/ReleasePlanAdmission is clearer than what was there before.

However, the three issues from the earlier CHANGES_REQUESTED review remain open:

Still unresolved:

1. Credential sidecar "SHALL NOT be built" vs live Tekton pipelines (Major): The spec contains normative language that credential sidecar images SHALL NOT be built. Four active push pipelines remain in .tekton/ that build exactly those images. This spec will be consumed by /reconcile and the contradiction will surface as a gap. Options: soften to "SHALL NOT be deployed to integration — pipelines decommissioned separately" or link a tracking issue for pipeline removal.

2. MCP server MAY ambiguity (Major): The component table still hedges with "MAY be excluded if the openshell provider flow does not require it." This makes the spec unresolvable. Replace with either MUST (it is deployed) or SHALL NOT (it is excluded), with an explicit condition if conditional.

3. Index abbreviation convention (Minor): The entry still uses prose (Manifests, CI/CD, GitOps) where neighboring entries use short abbreviations (CP, BE, FE, Runner). Align with the established style.

The amber/change-requested label remains. Happy to re-review once these three points are addressed.

---

— Amber

[jsell-rh]

🤖 Amber Follow-Up — PR #468: feat(specs): add integration deployment spec for automated main to hcmai-01

Re-checking after the new commit (8c9d13f — "fix(specs): rewrite image update flow to use Konflux Release pipeline"). The image update flow section is improved — the 7-step Konflux Release pipeline approach with ReleasePlan/ReleasePlanAdmission is clearer than what was there before.

However, the three issues from the earlier CHANGES_REQUESTED review remain open:

Still unresolved:

1. Credential sidecar "SHALL NOT be built" vs live Tekton pipelines (Major): The spec contains normative language that credential sidecar images SHALL NOT be built. Four active push pipelines remain in .tekton/ that build exactly those images. This spec will be consumed by /reconcile and the contradiction will surface as a gap. Options: soften to "SHALL NOT be deployed to integration — pipelines decommissioned separately" or link a tracking issue for pipeline removal.

2. MCP server MAY ambiguity (Major): The component table still hedges with "MAY be excluded if the openshell provider flow does not require it." This makes the spec unresolvable. Replace with either MUST (it is deployed) or SHALL NOT (it is excluded), with an explicit condition if conditional.

3. Index abbreviation convention (Minor): The entry still uses prose (Manifests, CI/CD, GitOps) where neighboring entries use short abbreviations (CP, BE, FE, Runner). Align with the established style.

The amber/change-requested label remains. Happy to re-review once these three points are addressed.

---

— Amber

[jsell-rh]

🤖 Amber Re-Review — Updated after commit 3dc99193 (2026-07-31T21:10Z)

Previous findings resolved ✅

All three issues from the original review are addressed in the latest commits:

• ✅ Credential sidecar language removed entirely — delegated to chore(tekton): remove credential sidecar Konflux builds #469
• ✅ MCP server image disposition clarified — acp-mcp-main simply omitted from Image Updater config, no ambiguous MAY language remains
• ✅ Spec index Components column now uses abbreviations (CP, CI/CD) consistent with adjacent entries

New finding — Minor:

The Purpose section states:

"No git commits, PRs, or external CI systems are involved in the image update path."

However, the reference YAML block in §4.1.1 includes:

argocd-image-updater.argoproj.io/write-back-method: git

write-back-method: git means ArgoCD Image Updater will commit an .argocd-source-acp-integration.yaml digest file back to the gitops repo on every update cycle. The prose claim is factually incorrect as written.

Suggested fix:

"No human-authored git commits, PRs, or manual approvals are required in the image update path — image digest writes are committed automatically by ArgoCD Image Updater via the git write-back method."

This is a Minor finding in a spec-only PR. Once corrected, this is ready to merge.

Confidence: High

---

— Amber, ACP codebase intelligence

[jsell-rh]

🤖 Amber Re-Review — feat(specs): add integration deployment spec for automated main to hcmai-01

Thanks for addressing the feedback — the three original concerns are all resolved. One previously-flagged issue is still present in the current HEAD, plus two new minor observations.

Overall: changes-requested — one prose contradiction needs a one-line fix before this is ready.

Original concerns — resolution status

Concern	Severity	Status
Credential sidecar "SHALL NOT be built" conflicts with live Tekton pipelines	Major	✅ RESOLVED — sidecar language removed, delegated to #469
MCP server MAY ambiguity — non-deterministic disposition	Major	✅ RESOLVED — acp-mcp-main row removed entirely
Index entry used prose instead of abbreviations	Minor	✅ RESOLVED — now uses CP, CI/CD

Remaining / new findings (3)

---

🟡 Major (unresolved from prior follow-up) — Prose says "no git commits" but write-back-method: git contradicts it

File: specs/platform/integration-deployment.spec.md

Two locations still make this affirmative claim:

• Purpose section (~line 14): "No git commits, PRs, or external CI systems are involved in the image update path."
• Image Update Flow requirement (~line 67): "No git commits, Release pipelines, or PRs are involved in the image update path."

But the ArgoCD Application reference config (line ~138) sets:

argocd-image-updater.argoproj.io/write-back-method: git
argocd-image-updater.argoproj.io/write-back-target: kustomization
argocd-image-updater.argoproj.io/git-branch: main

And the spec itself explains a paragraph later that Image Updater commits .argocd-source-acp-integration.yaml to the GitOps repo. The prose claim is factually wrong — automated git commits are involved.

Fix (both locations): Replace the absolute claim with:

"No human-authored git commits, manual PRs, or external CI approvals are required — image digest writes are committed automatically by ArgoCD Image Updater via the git write-back method."

This was flagged in my prior follow-up comment; it wasn't addressed in the latest commits.

---

🟠 Minor — Design Decisions table: agent-gitops "only manual developer commits" claim is inconsistent

File: specs/platform/integration-deployment.spec.md — Design Decisions table (~line 34)

The table states: "agent-gitops is only changed when the shape of resources changes, via manual developer commits."

Image Updater's write-back-method: git will automatically commit .argocd-source-acp-integration.yaml to agent-gitops on every image digest update. The Design Decision row should acknowledge this automated write-back as an explicit exception, or the table will mislead readers.

---

🟠 Minor — Rollback is manual-only with no explicit v1 scope statement

File: specs/platform/integration-deployment.spec.md — Rollback requirement (~line 355–385)

The rollback section describes a manual operator action (pin image overrides via ArgoCD CLI, disable Image Updater). This is acceptable for v1, but the spec doesn't say it's a deliberate v1 non-goal — readers may assume auto-rollback is implied. A brief note in Future Work or a Design Decision entry would clarify intent: "Rollback is manual in v1 — auto-rollback is a future consideration."

---

— Amber, ACP codebase intelligence