# CI Documentation Maintenance Guide

This file contains notes for maintaining the CI documentation subtree under `docs/ci/`.

## Scope

The canonical CI docs now live in:

- `docs/ci/README.md`
- `docs/ci/execution.md`
- `docs/ci/dev-ci-topology.md`
- `docs/ci/e2e-subscription-onboarding.md`
- `docs/ci/dev-mock-identities.md`
- `docs/ci/image-lifecycle.md`
- `docs/ci/identity-leasing.md`
- `docs/ci/ev2-integration.md`
- `docs/ci/cleanup.md`
- `docs/ci/e2e-testing.md`
- `docs/ci/operations.md`

The old top-level CI docs were intentionally removed. Do not recreate the old large `prow.md` job catalog.

## Documentation Shape

Keep the CI docs concept-first:

- `README.md`: where to start and which doc answers which question
- `execution.md`: how CI works and what each mode validates
- `dev-ci-topology.md`: what the standalone `dev-ci` rollout owns and where it still hands off to runtime CI or mixed operator paths
- `e2e-subscription-onboarding.md`: the operator procedure for onboarding E2E customer subscriptions across all environments (DEV, INT, STG, PROD)
- `dev-mock-identities.md`: what each DEV mock identity stands in for and why it needs each role it is granted
- `image-lifecycle.md`: deep mechanics for the CI image graph, promotion, and ACR push boundary
- `identity-leasing.md`: deep mechanics for managed identity and MSI mock SP leasing
- `ev2-integration.md`: deep mechanics for EV2, Gangway, and pinned gating runs
- `cleanup.md`: why cleanup paths differ
- `e2e-testing.md`: how contributors trigger or narrow tests
- `operations.md`: how maintainers trigger, inspect, troubleshoot, or change CI

The only place that should keep even a small job inventory is the tiny appendix in `docs/ci/operations.md`.

Do not reintroduce:

- large per-job tables
- schedule dumps in the main narrative
- duplicated lists of job names across multiple files

## Sources Of Truth

### Generated Job Definitions (Do Not Edit)

- https://github.com/openshift/release/blob/master/ci-operator/jobs/Azure/ARO-HCP/Azure-ARO-HCP-main-presubmits.yaml
- https://github.com/openshift/release/blob/master/ci-operator/jobs/Azure/ARO-HCP/Azure-ARO-HCP-main-postsubmits.yaml
- https://github.com/openshift/release/blob/master/ci-operator/jobs/Azure/ARO-HCP/Azure-ARO-HCP-main-periodics.yaml

### `openshift/release` Source Config (Edit These)

- https://github.com/openshift/release/blob/master/ci-operator/config/Azure/ARO-HCP/Azure-ARO-HCP-main.yaml
- https://github.com/openshift/release/blob/master/ci-operator/config/Azure/ARO-HCP/Azure-ARO-HCP-main__baseimage-generator.yaml
- https://github.com/openshift/release/blob/master/ci-operator/config/Azure/ARO-HCP/Azure-ARO-HCP-main__e2e.yaml
- https://github.com/openshift/release/blob/master/ci-operator/config/Azure/ARO-HCP/Azure-ARO-HCP-main__periodic.yaml
- https://github.com/openshift/release/blob/master/ci-operator/config/Azure/ARO-HCP/Azure-ARO-HCP-main__periodic-cleanup.yaml
- https://github.com/openshift/release/blob/master/ci-operator/config/Azure/ARO-HCP/Azure-ARO-HCP-main__image-updater.yaml

### ARO HCP Repository Wiring

- `../dev-infrastructure/openshift-ci/Dockerfile`
- `../test/Containerfile.e2e`
- `../config/config.msft.clouds-overlay.yaml`
- `../config/config-dev-ci.yaml`
- `../topology-dev-ci.yaml`
- `../test/e2e-config/e2e-slots.yaml`
- `../test/cmd/aro-hcp-tests/slot-manager/DESIGN.md`
- `../test/cmd/aro-hcp-tests/slot-manager/release_repo.go`
- `../dev-infrastructure/dev-ci/e2e-subscription-rbac/pipeline.yaml`
- `../dev-infrastructure/dev-ci/e2e-subscription-rbac-grants/pipeline.yaml`
- `../dev-infrastructure/configurations/mock-identity-apps.tmpl.bicepparam`
- `../dev-infrastructure/configurations/mock-identity-apps-int.tmpl.bicepparam`
- `../dev-infrastructure/configurations/mock-identity-rbac.tmpl.bicepparam`
- `../dev-infrastructure/configurations/mock-identity-rbac-int.tmpl.bicepparam`
- `../dev-infrastructure/configurations/dev-operator-roles.tmpl.bicepparam`
- `../dev-infrastructure/Makefile`
- `../test/e2e-pipeline.yaml`
- `../test/util/framework/per_test_framework.go`
- `../test/util/framework/identities_helper.go`
- `../dev-infrastructure/openshift-ci/msi-mock-pool.yaml`
- `../dev-infrastructure/openshift-ci/populate-msi-mock-pool.sh`

## Which File To Update

Update `docs/ci/execution.md` when:

- the CI execution modes change
- the Azure request path or tenant split changes
- EV2 commit pinning or `prowJobName` wiring changes
- the identity-leasing runtime model changes

Update `docs/ci/dev-ci-topology.md` when:

- the standalone `topology-dev-ci.yaml` service groups change
- ownership moves between the `dev-ci` topology, `openshift/release`, and imperative operator paths
- the supported local entry points for `dev-ci` rollouts change
- the long-term direction for replacing the mixed model changes materially

Update `docs/ci/e2e-subscription-onboarding.md` when:

- the slot-catalog contract or slot-manager onboarding flow changes
- the release-side Boskos sync/validation workflow changes
- the cluster-profile shard inventory contract changes
- the `dev-ci` bootstrap RBAC onboarding path or its current limitations change

Update `docs/ci/dev-mock-identities.md` when:

- a mock identity is added, removed, or repurposed
- the role definitions or role assignments granted to a mock identity change
- the mock MSI data-plane behavior (one SP backing all operator identities) changes
- a custom mock role is migrated to or from an Azure built-in role

Update `docs/ci/image-lifecycle.md` when:

- the shared CI build root or test runner image lifecycle changes
- the job-local image graph changes in `openshift/release`
- local E2E stops injecting freshly built service images into the environment, or that flow changes shape
- ci-operator promotion rules or the `images-push` boundary change
- the log-reading mental model needs to reflect a different dependency graph

Update `docs/ci/identity-leasing.md` when:

- the ci-operator lease wiring changes
- managed identity pool sizing or quota assumptions change
- MSI mock SP pool setup, lookup behavior, or mixed-management boundary changes
- Boskos resource types or counts for identity-related pools change

Update `docs/ci/ev2-integration.md` when:

- EV2 validation steps or Gangway auth change
- `prowJobName` mapping or `gatePromotion` wiring changes
- commit-pinning behavior changes
- rollout metadata or correlation annotations change

Update `docs/ci/cleanup.md` when:

- cleanup semantics change
- a cleanup path changes owner or strictness
- the location of cleanup implementation changes

Update `docs/ci/e2e-testing.md` when:

- `/test` commands change
- contributor guidance for higher-environment testing changes
- test filtering guidance changes

Update `docs/ci/operations.md` when:

- how to inspect or correlate runs changes
- CI config maintenance workflow changes
- pool-management procedures change
- the small appendix needs a new job family or a removed one

Update `docs/ci/README.md` when:

- the doc set changes shape
- the recommended reader journey changes

## Update Workflow

When CI config changes in `openshift/release`:

1. update the relevant source config there
2. follow the release repo's documented regeneration flow (`make update`)
3. update the ARO HCP docs only if the change affects behavior, navigation, or the small appendix

When the change is only a job rename or schedule tweak, prefer updating the appendix in `docs/ci/operations.md` rather than expanding the conceptual docs.

## Quick Reference

- Presubmit jobs: `pull-ci-Azure-ARO-HCP-main-<test-name>`
- EV2 gating jobs: `branch-ci-Azure-ARO-HCP-main-e2e-<test-name>`
- Periodic jobs: `periodic-ci-Azure-ARO-HCP-main-<test-name>`
- Image-updater jobs: `periodic-ci-Azure-ARO-HCP-main-image-updater-<test-name>`
- Prow dashboard pattern: `https://prow.ci.openshift.org/?job=<job-name>`
- Job run URL pattern: `https://prow.ci.openshift.org/prowjob?prowjob=<prowjob-id>`
- Step registry pattern: `https://steps.ci.openshift.org/job?org=Azure&repo=ARO-HCP&branch=main&test=<test-name>`

## Validation Checklist

Before finalizing CI doc updates:

- [ ] links point at `docs/ci/` targets, not the old top-level docs
- [ ] `execution.md` still answers "how does CI work?"
- [ ] `dev-ci-topology.md` still answers "what does standalone dev-ci own today?"
- [ ] `e2e-subscription-onboarding.md` still reflects the real onboarding path and any current fixed-width limitations
- [ ] `image-lifecycle.md` still carries the deep CI image graph instead of duplicating it across multiple docs
- [ ] `identity-leasing.md` still carries the deep lease mechanics instead of duplicating them across multiple docs
- [ ] `ev2-integration.md` still carries the deep EV2/Prow narrative instead of duplicating it across multiple docs
- [ ] `operations.md` still answers "how do I trigger, inspect, or change CI?"
- [ ] the appendix in `operations.md` is still small and source-of-truth oriented
- [ ] no large per-job tables were reintroduced
- [ ] markdown formatting is clean and headings remain unique
