ScreamingFace delivery: repository to cluster
ScreamingFace dev uses two deliberately separate transports. Tenant CI pushes images to the platform registry; Argo reads Helm charts from the tenant repository. Kargo joins those artifacts at one immutable tenant commit. A machine-authored pull request passes required checks before automatic merge.
flowchart LR
subgraph TENANT["OpenMined/screamingface"]
M[Merge to main]
W[Path-filtered GitHub Actions]
H[Helm chart at exact commit]
end
subgraph ARTIFACTS["Delivery transports"]
O[GitHub OIDC]
R[Azure Container Registry<br/>main-<sha40>]
G[GitHub App<br/>read-only repository access]
end
subgraph PLATFORM["OpenMined/infrastructure"]
T[Chart ticket<br/>exact chartRef]
V[Platform values<br/>exact image tag]
B[Platform boundary resources]
end
subgraph DEV["aks-dev"]
A[Argo CD multi-source app]
K[Reconciled workload<br/>and boundary]
end
M --> W --> O --> R
M --> H
G --> H --> A
T --> A
V --> A
B --> A
R --> K
A --> K
The two transports
| Payload | Transport | Credential | Why |
|---|---|---|---|
| Container images | Tenant GitHub Actions pushes to ACR | Azure workload identity through GitHub OIDC | The cluster pulls in-region; no registry password is stored |
| Helm chart source | Argo reads the private tenant repository over HTTPS | GitHub App installation credential | Argo can render the exact chart commit without a personal token |
The tenant workflows read the non-secret repository variables
AZURE_CLIENT_ID, AZURE_TENANT_ID, and AZURE_SUBSCRIPTION_ID. They are
variables, not GitHub Secrets. The workflow obtains a short-lived Azure token
and builds the affected app on a merge to main.
The dev lanes publish main-<sha40> (plus a legacy short alias) to ACR and
GHCR. PULSE deploys the ACR
copy. A successful image build does not deploy it by itself.
What a deployment pin contains
Each chart ticket in the infrastructure repository states:
- the tenant and target namespace;
- the tenant repository URL;
- an exact tenant merge commit as
chartRef; - the chart path at that commit;
- the platform values file.
The values file selects the matching main-<sha40> image. Both fields are
written by the promotion machinery from the SAME registry tag, so chart and
image cannot name different revisions — and moving them is a machine-authored
two-line PR, merged automatically behind the required checks (ADR-0008).
Change flow (automatic since 2026-08-05 — ADR-0008)
- Merge the application change to ScreamingFace
main. That is the whole human flow. - Their path-filtered CI builds and publishes the immutable
main-<sha40>ACR tag — their checks are the gate. - Kargo discovers the build (≤10 min), writes the chart ticket's
chartRefand the values file'simage.tagfrom that ONE tag, renders the tenant chart at that exact commit against the platform values (the render gate), opens a two-line PR, and merges it itself once the three required checks pass. - Argo reconciles; the pod rolls to the recorded digest. Typical merge-to-running: 15–20 minutes, no platform human involved.
- Two independent alarms watch the chain: pin-staleness ("is there tenant work not deployed?") and argo-health ("did the cluster take what was merged?").
Manual promotion survives as rollback/break-glass only — the runbook is
docs/runbooks/tenant-dev-promotion.md, the tool
scripts/ops/promote-dev.sh. Platform-owned companion changes (contract
changes, new secrets, new routes) remain reviewed platform PRs, exactly as
before.
The evidence page explains why these are separate proof classes.
Review surface by change type
| Tenant change | Infrastructure review needed |
|---|---|
| Application code only | Automatic Kargo render, pin, checks, and merge |
| Port, health path, Service name, or selector label | Values, route/probes, and NetworkPolicy selectors |
| Kubernetes API use | Platform ServiceAccount and exact Role/RoleBinding |
| Secret name or key contract | ExternalSecret target and chart existingSecret mapping |
| Database schema | Migration hook, ordering, database compatibility, rollback consequence |
| New provider or egress destination | Provider profile contract and server-only egress policy |
| Public path or identity assumption | Platform route and SecurityPolicy review |
| Storage or replica change | State model, storage class, disruption, and rollback review |
Failure signatures
| Symptom | Likely seam |
|---|---|
| Azure login reports missing identifiers | Repository variables were absent or stored as Secrets |
| ACR image tag does not exist | The path-filtered tenant workflow did not run or publish |
| Argo cannot fetch the chart | GitHub App installation, HTTPS repository URL, or exact URL matching |
| Argo rejects the source | Repository URL is outside the ScreamingFace AppProject allowlist |
| A resource is forbidden | The chart now emits a kind outside the AppProject fence |
| Deployment is healthy but unreachable | Service/selector drift or platform NetworkPolicy does not match rendered labels |
| Credentials change on every sync | A chart-generated Secret was re-enabled instead of using the platform Secret |
| Migration works locally but fails in Argo | Hook ordering, ServiceAccount, database Secret, or schema compatibility changed |
Current dev hardening debt
The target design trusts only the tenant default branch and grants image push only to that tenant's repositories. The first dev identity still has an unused pull-request federation and registry-wide push scope. Neither is used by the current workflows. The pull-request federation was destroyed on 2026-09-09 (P1-52/53); the registry-wide push scope is still open and is tracked as hardening debt, not a blocker — staging and production run behind it.