Skip to content

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-&lt;sha40&gt;]
        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)

  1. Merge the application change to ScreamingFace main. That is the whole human flow.
  2. Their path-filtered CI builds and publishes the immutable main-<sha40> ACR tag — their checks are the gate.
  3. Kargo discovers the build (≤10 min), writes the chart ticket's chartRef and the values file's image.tag from 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.
  4. Argo reconciles; the pod rolls to the recorded digest. Typical merge-to-running: 15–20 minutes, no platform human involved.
  5. 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.

Source of truth