Delivery Ownership

Status

This is the approved target architecture. Central onboarding is available for new applications; existing source-owned registrations remain migration work.

Trust Boundary

Application repositories are build inputs, not GitOps inputs. A developer can change application code on main, but cannot change an active Pipeline, Task, runtime secret reference, Helm chart, environment value, or promotion policy.

Concern	Owner	Location
Application code, tests, Dockerfile	Developers	`Maidn/<app>` `main`
Approved charts and environment values	Platform	`Maidn/<app>` `maidn/platform-<app>`
Pipeline, Tasks, triggers, runtime access	Platform	Cluster repository
Image tags, preview ownership, promotion PRs	Platform	Deployment manifests repository
Secret values and policies	Platform	Private config, SOPS operational state, OpenBao

The protected platform branch may be readable by developers, but only platform operators and approved automation may push or merge into it. Flux must track only that branch for chart content. Flux must never track an application main branch or maidn/delivery-* branch.

Onboarding requires an existing maidn/platform-<app> branch and verifies its no-direct-push protection before it opens the central registration PR. It never seeds a platform branch from developer-controlled main.

Resource Flow

flowchart LR
  App[Application main branch\ncode only]
  Platform[Protected platform branch\nchart and values]
  Cluster[Cluster repository\nPipeline, Tasks, secret access]
  Manifests[Manifests repository\nimage tags and promotion]
  Flux[Flux]
  Workload[Preview, staging, production]

  App -->|exact source SHA| Cluster
  Cluster --> Manifests
  Platform --> Flux
  Manifests --> Flux
  Flux --> Workload

The central Pipeline clones the application repository at the event SHA only to build an image. It obtains chart content from the protected platform branch and writes only image-tag and promotion state to the manifests repository.

Prohibited Application Content

Application repositories must not contain active delivery control-plane resources:

.tekton/ Pipeline or Task resources
.maidn/ Flux, RBAC, SecretStore, or ExternalSecret resources
Flux Kustomizations or GitRepositories
Kubernetes Secret values, SOPS identities, OpenBao tokens, or kubeconfigs

An application main branch may retain a chart as a developer proposal, but it has no delivery effect. A platform operator explicitly reviews and copies an approved chart and environment values to maidn/platform-<app>.

Approval Sequence

A platform operator creates or updates the protected platform branch through a reviewed platform PR.
A platform operator reviews and merges the central cluster registration that renders the Pipeline, Tasks, protected chart source, and runtime references.
Flux applies only the central cluster resources and protected chart branch.
Developers use Forgejo pull requests and pushes to trigger builds; they do not edit deployment control-plane resources.
Production promotion remains a reviewed PR in the manifests repository.

Migration Rules

Existing source-owned registrations are migrated one application at a time. First establish the protected platform package, then merge the central cluster registration, then verify Flux and delivery. Remove the legacy source GitRepository, Kustomizations, and delivery branch only after the replacement is Ready.

The canonical fixtures are migration pilots. Maidn/maidn-e2e-secret remains disabled until its central replacement is reviewed. Angular and web legacy registrations must follow the same migration path.

Command Status

cicd-tool bootstrap, cicd-tool app, and cicd-tool e2e are the current Forgejo and GitOps command families. cicd-tool repo init and cicd-tool vault create-* are legacy GitHub/direct-apply paths and are not part of new platform onboarding. They will be deprecated or removed after the central delivery migration.

Acceptance

The architecture is accepted only after a canonical fixture proves all of the following with a real Forgejo event:

pull request preview build, route, and delivery feedback
main-to-staging deployment at an immutable image SHA
reviewed production promotion PR
runtime secret and shared database projection without preview credentials
closed-preview cleanup and orphan-cleaner recovery

4.4 KiB Raw Permalink Blame History