DevOps / GitOps — aggregate roots

Generated from the architecture model

This page is rendered from model/**/*.yaml by tools/docs_model during mkdocs build. Edit the YAML, not this page; hand-written design lives on the linked service, platform and plane pages.

Aggregate	Service	Root entity	Events	Tables
Promotion	EnvironmentPromotionService	Promotion	PromotionRequested, PromotionApproved, PromotionCompleted, PromotionFailed, RollbackCompleted	Promotions, PromotionGates
ChangeProposal	PipelineExecutionService	ChangeProposal	ChangeProposalOpened, ChangeProposalStateChanged, ChangeProposalMerged	ChangeProposals, ProposalCommits
PipelineRun	PipelineExecutionService	PipelineRun	PipelineRunStarted, PipelineRunCompleted	PipelineRuns, PipelineResults
ProductRelease	ReleaseService	ProductRelease	ReleaseCreated, ReleaseReady, ReleaseWithdrawn	ProductReleases, ReleaseComponents

Promotion (EnvironmentPromotionService)

One request to put a release into an environment: gates with their outcomes, the approval (production class) when the environment is production, the strategy, the desired-state hand-off to provisioning, verification results and, if needed, the rollback with its evidence.

Field	Type	Required	Description
promotionId	guid	yes
tenantId	string	yes
projectId	string	yes
releaseId	guid	yes
environmentId	string	yes
environmentClass	string	yes	development
strategy	enum:Strategy	yes
gates	json	yes	Per gate kind outcome and evidence reference.
approvalId	guid	no
requestedBy	string	yes
runId	guid	no	The Factory run that requested it (deploy-environment tool).
desiredStateRef	string	no	Deployment specification handed to BC-25.
verification	json	no	Health, smoke and SLO checks after deploy.
previousReleaseId	guid	no
state	enum:PromotionState	yes
requestedAt	datetime	yes
completedAt	datetime	no

Invariants

• A production promotion needs an approval of class production bound to the exact release id and environment, decided by someone other than the requester (D21, ADR-0015); lower classes need policy allow and passing gates.
• A release may only enter production after it completed in the prior environment class of the project's promotion path, unless policy allows a hotfix path with evidence.
• Deployment itself is done by provisioning (BC-25) from the desired state; this service never touches infrastructure directly.
• A rollback is a promotion of the previous release with the same gates except approval, which the Operator holds by role for rollbacks.

States (PromotionState)

stateDiagram-v2
    Requested --> GatesEvaluating : Start
    GatesEvaluating --> AwaitingApproval : GatesPassedApprovalRequired
    GatesEvaluating --> Approved : GatesPassedNoApproval
    GatesEvaluating --> Rejected : GateFailed
    AwaitingApproval --> Approved : ApprovalGranted
    AwaitingApproval --> Rejected : ApprovalRejectedOrExpired
    Approved --> Deploying : DesiredStateHandedOff
    Deploying --> Verifying : ProvisioningApplied
    Verifying --> Completed : VerificationPassed
    Verifying --> RolledBack : VerificationFailedAutoRollback
    Deploying --> Failed : ProvisioningFailed
    Completed --> RolledBack : ManualRollback

Hold "Alt" / "Option" to enable pan & zoom

ChangeProposal (PipelineExecutionService)

A change set the Factory proposed (through the propose-change-set tool, shared-write class) and its life in the system of record: repository, branch, commits, pull request, reviews and merge — with provenance to the run, attempt, agent release and change-set artifact.

Field	Type	Required	Description
proposalId	guid	yes
tenantId	string	yes
projectId	string	yes
runId	guid	yes
attemptId	guid	yes
agentReleaseId	string	yes
changeSetRef	string	yes	Artifact reference (change-set-v1)
system	enum:SystemOfRecord	yes
repository	string	yes
branch	string	yes
pullRequestRef	string	no
commits	list:string	yes
state	enum:ProposalState	yes
reviewers	json	no
mergedCommit	string	no
updatedAt	datetime	yes

Invariants

• The system of record is the truth of branches, commits and pull requests; the proposal mirrors it from verified deliveries and connector reads, never the other way round.
• Every commit the Factory authors carries the run id and change-set hash in its trailer; a proposal without provenance is not Factory-authored.
• A merge is a human or policy decision in the system of record; the Factory never auto-merges to a protected branch without an approval of class shared-write recorded here.

States (ProposalState)

stateDiagram-v2
    Proposed --> BranchCreated : BranchPushed
    BranchCreated --> PullRequestOpen : PullRequestOpened
    PullRequestOpen --> ChangesRequested : ReviewRequestedChanges
    ChangesRequested --> PullRequestOpen : NewCommits
    PullRequestOpen --> Approved : ReviewApproved
    Approved --> Merged : Merged
    PullRequestOpen --> Abandoned : Closed

Hold "Alt" / "Option" to enable pan & zoom

PipelineRun (PipelineExecutionService)

A mirrored pipeline run with its stages and typed results (build, tests, coverage, static analysis, security scan, SBOM, packages, images, attestations) and the proposal or release that triggered it.

Field	Type	Required	Description
pipelineRunId	guid	yes
tenantId	string	yes
projectId	string	yes
system	enum:SystemOfRecord	yes
externalRunRef	string	yes
definitionRef	string	yes	Pipeline definition in the repository (generated by the Factory from the pipeline blueprint).
proposalId	guid	no
commit	string	yes
state	enum:PipelineRunState	yes
stages	json	yes
startedAt	datetime	yes
completedAt	datetime	no

Invariants

• Results are receipts with artifact references; logs and reports live in the artifact store, not here.
• A run's state comes from verified deliveries (webhooks) or a connector read; a missing final delivery is reconciled by polling, never assumed.

Entities: PipelineResult · Value objects: —

ProductRelease (ReleaseService)

An immutable release of a generated product or module: semantic version, merged commit, components with digests, SBOM and attestations, the pipeline run and change proposals that produced it, and the asset releases (agents, templates, blueprints) that generated it.

Field	Type	Required	Description
releaseId	guid	yes
tenantId	string	yes
projectId	string	yes
productId	string	yes	Generated product or module id.
version	string	yes
commit	string	yes
pipelineRunId	guid	yes
proposalIds	list:guid	yes
generatedBy	json	yes	agent, template and blueprint release ids (provenance)
sbomRef	string	yes
attestationRefs	list:string	yes	Build provenance attestations (in-toto / SLSA style)
state	enum:ReleaseState	yes
notesRef	string	no	Generated release notes artifact.
createdAt	datetime	yes

Invariants

• A release is immutable once Released; a change is a new version; Withdrawn releases cannot be promoted.
• Every component has a digest; a component without publication evidence keeps the release Candidate.
• Provenance (commit trailers, pipeline run, generating asset releases) is required; a release without provenance is refused.

States (ReleaseState)

stateDiagram-v2
    Assembling --> Candidate : ComponentsResolved
    Candidate --> Released : AllPublished
    Released --> Superseded : NewerReleased
    Candidate --> Withdrawn : Withdraw
    Released --> Withdrawn : Withdraw

Hold "Alt" / "Option" to enable pan & zoom

Entities: ReleaseComponent · Value objects: —