AIFACTORY-FEAT-045: ReleaseService: complete delivery¶
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.
A design artefact, not a tracker
This backlog is generated from model/backlog/ and validated against the architecture model. No work item exists in any tracker, and no item carries a date, an estimate or an assignee (ADR-0029).
Epic DevOps / GitOps (PF-08) · Increment I2 Deliver it · State elaborated · Route backend-developer · Build order 97 of 185 (Factory code)
ReleaseService is the service of bounded context BC-24 (Package & Release Delivery). Releases of generated products and modules — immutable version, merged commit, container image digests, packages, SBOM and provenance attestations, change-set and pipeline references — and the evidence that each package or image was published to its feed or registry (BC-24; ContainerImageService merged; package and template publishing stay in the existing CI as external canonical). Its own repository is ConnectSoft.AI.SoftwareFactory.ReleaseService.
| Delivers | ReleaseService (complete) |
| Stubs | — |
| Realizes | adrs: ADR-0014 |
| Requirements | FR-08, FUX-05, NFR-08, NFR-12, XL-04, XL-10 |
| Depends on | — |
| Sources | model/services/devops-gitops/ReleaseService.yaml |
Scenarios to trace (8, catalog): SCN-ReleaseService-001 ✓, SCN-ReleaseService-002 ✓, SCN-ReleaseService-003 ✓, SCN-ReleaseService-004 ✓, SCN-ReleaseService-005 ✓, SCN-ReleaseService-006 ✓, SCN-ReleaseService-007 ✓, SCN-ReleaseService-008 ✓
AIFACTORY-US-023: Passing results become an immutable release¶
behavior · persona operator
As an operator, I want a pipeline run that passed its gates to yield a release with its manifest, bill of materials and attestations, so that what is promoted is one immutable, verifiable version.
This is the integration PBI of ReleaseService, the service of bounded context BC-24 that holds the releases of generated products and modules and the evidence that each package or image was published. A succeeded pipeline run becomes a candidate release, either through the inbox handler AssembleFromRun when PipelineExecutionService publishes PipelineRunCompleted (AIFACTORY-US-1290) or through CreateProductRelease called by an Operator or a Workspace admin (AIFACTORY-US-1289); a run that did not succeed yields no release. A release carries its semantic version, the merged commit, its components with digests, the SBOM, the provenance attestations, the pipeline run, the merged change proposals that LinkProposal collected and the asset releases that generated it; a release without provenance is refused. It stays Candidate until the PublicationVerifier found every component in its feed or registry, then it is Released and ReleaseReady tells EnvironmentPromotionService and the release workflow that it may be promoted (AIFACTORY-US-1291). A Released release is immutable: a change is a new version, and a newer Released version supersedes it. A release is withdrawn with a reason, which blocks its promotion and revokes nothing already deployed (AIFACTORY-US-1292), and EnvironmentPromotionService resolves a release with its digests and evidence through Releases.GetRelease (AIFACTORY-US-1293). The delivery run evaluates the typed results and fails on a blocking gate in its own feature (feature wf-delivery-run). The summary of its step prepare-release says that it assembles the release manifest with SBOM and attestations through ReleaseService, but the step binds no tool that reaches CreateProductRelease, a gap the model carries (D132) that this PBI reports to the owner and neither closes nor turns into a criterion. The release events are written with the types of the pinned contracts package, which generates every integration event that model/services/devops-gitops/ReleaseService.yaml declares under the run event envelope (ADR-0014 amendment D114), so no contract is published from the service repository. The release condition of the model is a succeeded run on a release branch or tag, and PipelineRunCompleted carries neither branch, tag, product nor version, an open point reported to the owner (AIFACTORY-US-1290). Package and template publishing stay in the existing CI as the external canonical; the service records evidence and publishes nothing. Repository: ConnectSoft.AI.SoftwareFactory.ReleaseService.
Acceptance criteria
| AC1 | Given PipelineExecutionService/PipelineRunCompleted in state Succeeded for a run on a release branch or tag, when ReleaseService handles it, then one ReleaseService/ProductRelease exists in state Candidate with version, merged commit, component digests, SBOM and provenance attestations, and ReleaseService/ReleaseCreated is published once (ADR-0014). |
| AC2 | Given a pipeline run that failed a gate, when its completion is handled or ReleaseService/CreateProductRelease names it, then no release is created, the call being refused with 422, and nothing is published (FR-08). |
| AC3 | Given every component of a candidate has publication evidence, when the verifier completes, then the release is Released and ReleaseService/ReleaseReady is published after the evidence is recorded, and no component without evidence is ever part of a Released release (model/services/devops-gitops/ReleaseService.yaml). |
| AC4 | Given a release was withdrawn through ReleaseService/WithdrawProductRelease, when EnvironmentPromotionService resolves it through ReleaseService/Releases.GetRelease, then it is answered in state Withdrawn and ReleaseService/ReleaseWithdrawn was published, so the promotion is refused by EnvironmentPromotionService in its own suite. |
| Traces: services | ReleaseService, PipelineExecutionService, ArtifactService, WorkflowEngineService |
| Traces: aggregates | ReleaseService/ProductRelease |
| Traces: apis | ReleaseService/CreateProductRelease, ReleaseService/WithdrawProductRelease, ReleaseService/Releases.GetRelease |
| Traces: events | ReleaseService/ReleaseCreated, ReleaseService/ReleaseReady, ReleaseService/ReleaseWithdrawn, PipelineExecutionService/PipelineRunCompleted |
| Traces: workflows | delivery-run |
| Traces: steps | delivery-run/prepare-release |
| Traces: descriptors | release-manifest-v1 |
| Traces: adrs | ADR-0014, ADR-0027 |
| Traces: requirements | FR-08 |
| Relates: screens | product-releases, release-detail |
| Depends on | AIFACTORY-US-1288, AIFACTORY-US-1289, AIFACTORY-US-1290, AIFACTORY-US-1291, AIFACTORY-US-1292, AIFACTORY-US-1293, AIFACTORY-US-1294, AIFACTORY-US-1295, feature:pipeline-execution-service-complete, feature:wf-delivery-run, feature:contracts-package |
| Sources | model/services/devops-gitops/ReleaseService.yaml, model/workflows/delivery-run.yaml, docs/planes/execution/delivery-engine/services/release-service/index.md#purpose-and-responsibilities |
Tasks
| Task | Kind | Expected output | Repository |
|---|---|---|---|
AIFACTORY-TASK-322 Contract test of the release events against the pinned contracts package |
verification | Run dotnet test -c Release --filter "Category=Contract&Feature=ReleaseEvents"; a zero-match filter counts as a failure; the test proves that ReleaseService/ReleaseCreated, ReleaseService/ReleaseReady and ReleaseService/ReleaseWithdrawn are written with the types of the pinned contracts package under the run event envelope and match the payload of model/services/devops-gitops/ReleaseService.yaml; no contract is published from the service repository, and the evaluation of typed results and the blocking gate of the delivery run are delivered by feature wf-delivery-run. |
ConnectSoft.AI.SoftwareFactory.ReleaseService |
AIFACTORY-TASK-711 Verify release-from-results by running the declared command |
verification | Run dotnet test -c Release --filter Category=Acceptance; a zero-match filter counts as a failure; it passes and proves AC1 to AC4 of AIFACTORY-US-023 over a succeeded run on a release branch, a run with a failed gate, a fake registry that holds or lacks a component and a withdrawn release resolved through Releases.GetRelease. |
ConnectSoft.AI.SoftwareFactory.ReleaseService |
AIFACTORY-US-1288: List and read product releases with components, SBOM, attestations and provenance¶
behavior · persona operator
A caller whose scope carries factory.delivery.read (Operator, Workspace admin, Platform admin or Observer) lists releases through ReleaseService/ListProductReleases, filtered by product, version and state, each with its components and provenance, and reads one release through ReleaseService/GetProductRelease with its components and their digests, targets and publication evidence, the SBOM, the attestations, the pipeline run, the change proposals, the generating asset releases and the release notes when they exist. The tenant comes from the trusted scope and the list holds only the releases of that tenant and of the projects in scope; the index IX_Releases_State serves the state filter. Every query runs under the tenant row filter, so a release of another tenant never appears and is answered 404 when addressed, the same answer as for a releaseId that does not exist (ADR-0015). A caller without the scope is refused with 403. A candidate shows which component still lacks evidence. Nothing is written and nothing is published by these reads. The routes are reached through the DeliveryHost gateway; StudioBff renders them in its own increment.
Acceptance criteria
| AC1 | Given releases of several products, versions and states in my tenant and in another tenant, when ReleaseService/ListProductReleases is called with a filter, then the response is 200 with only the matching releases of my tenant and projects in scope, with components and provenance, and releases of the other tenant never appear (SCN-ReleaseService-001, ADR-0015). |
| AC2 | Given a ReleaseService/ProductRelease of my tenant and project, when ReleaseService/GetProductRelease is called, then the response is 200 with the components and their digests, targets and publication evidence, the SBOM, the attestations, the pipeline run, the proposals and the generating asset releases (SCN-ReleaseService-002). |
| AC3 | Given a caller without factory.delivery.read, or a releaseId that exists only in another tenant or not at all, when either route is called, then the response is 403 for the missing scope and 404 for the foreign or unknown release, each with a problem response and no state change (SCN-ReleaseService-001, SCN-ReleaseService-002, ADR-0015). |
| Traces: services | ReleaseService |
| Traces: aggregates | ReleaseService/ProductRelease |
| Traces: apis | ReleaseService/ListProductReleases, ReleaseService/GetProductRelease |
| Traces: adrs | ADR-0015 |
| Traces: requirements | FUX-05 |
| Traces: scenarios | SCN-ReleaseService-001, SCN-ReleaseService-002 |
| Relates: screens | product-releases, release-detail, release-evidence |
| Depends on | AIFACTORY-US-1294, AIFACTORY-US-1295 |
| Sources | model/services/devops-gitops/ReleaseService.yaml, docs/planes/execution/delivery-engine/services/release-service/index.md#apis |
Tasks
| Task | Kind | Expected output | Repository |
|---|---|---|---|
AIFACTORY-TASK-5121 ListProductReleases and GetProductRelease under the tenant row filter |
implementation | ListProductReleases filters by product, version and state with components and provenance; GetProductRelease returns components with digests, targets and evidence, SBOM, attestations, pipeline run, proposals and generating assets; both apply the tenant row filter so a foreign release is answered 404 like an unknown one, and a missing scope is 403. | ConnectSoft.AI.SoftwareFactory.ReleaseService |
AIFACTORY-TASK-5122 Verify read-product-releases through the acceptance suite |
verification | Run dotnet test -c Release --filter "Category=Acceptance&(Scenario=SCN-ReleaseService-001\|Scenario=SCN-ReleaseService-002)"; a zero-match filter counts as a failure; the tests prove AC1 to AC3 of AIFACTORY-US-1288 over a two-tenant fixture. |
ConnectSoft.AI.SoftwareFactory.ReleaseService |
AIFACTORY-US-1289: Create a candidate release from a succeeded pipeline run and announce it¶
behavior · persona operator
As an operator, I want to assemble a release from a succeeded pipeline run with its version, components and provenance, so that there is one immutable candidate to verify and promote, and never one without provenance.
A caller whose scope carries factory.delivery.release, an Operator or a Workspace admin, posts to ReleaseService/CreateProductRelease under an Idempotency-Key a body that names the succeeded pipeline run, the product and the semantic version. Tenant and project come from the trusted scope (ADR-0015). The service records the ProductRelease in state Assembling with the merged commit, the pipeline run, the merged proposals linked for the product and the generating asset releases, resolves one ReleaseComponent per image, package, chart, template or static site of the run results, each with its digest, its target feed or registry and publication Pending, stores the SBOM and the attestations by reference in ArtifactService, and moves the release to Candidate (trigger ComponentsResolved), writing ReleaseCreated with releaseId, tenantId, projectId, productId, version and commit in the same transaction. The answer is 201 with the release. The dispatcher publishes ReleaseCreated on releases.products.v1.release-created under the run event envelope and retries a transport outage with backoff, so it is neither lost nor duplicated (ADR-0012); StudioBff, AuditService and DashboardService consume it in their own suites, and the PublicationVerifier of this service starts from it. A repeat under the same key and body returns the same release and writes nothing; a different body under the key, or a version that already exists for the product, is refused with 409, because a release is immutable and a change is a new version. A run that did not succeed, a component without a digest, a release without provenance, or a release without attestations while Delivery:Releases:RequireAttestations is true, is refused with 422. A caller without the scope is refused with 403. When ArtifactService is unavailable the call fails fast and writes nothing. The service has no synchronous read of a pipeline run and the model does not say where it takes the results of the named run from, an open point reported to the owner; the release workflow has no tool that reaches this route (D132).
Acceptance criteria
| AC1 | Given a caller with factory.delivery.release and a body naming a succeeded pipeline run, a product and a new version, when ReleaseService/CreateProductRelease is called with an Idempotency-Key, then the response is 201, the ReleaseService/ProductRelease moved from Assembling to Candidate with its commit, pipeline run, proposals, generating assets, SBOM and attestation references and one component per result with digest, target and publication Pending, and ReleaseService/ReleaseCreated was written in the same transaction (SCN-ReleaseService-003, ADR-0014). |
| AC2 | Given the same body under the same key, a different body under that key, a version that already exists for the product, or a caller without the scope, when ReleaseService/CreateProductRelease is called, then the repeat returns the same release and writes nothing, the conflicts are refused with 409 and the missing scope with 403, each with a problem response and no state change (SCN-ReleaseService-003, ADR-0015). |
| AC3 | Given a run that did not succeed, a component without a digest, a release without provenance, or no attestations while Delivery:Releases:RequireAttestations is true, when ReleaseService/CreateProductRelease is called, then it is refused with 422 naming the reason and no release is written; given ArtifactService is unavailable, the call fails fast and writes nothing (SCN-ReleaseService-003, model/services/devops-gitops/ReleaseService.yaml). |
| AC4 | Given the outbox record, when the dispatcher publishes ReleaseService/ReleaseCreated on releases.products.v1.release-created, then the event is sent under the run event envelope with releaseId, tenantId, projectId, productId, version and commit, and a transport outage is retried with backoff so the event is neither lost nor duplicated under its event id (SCN-ReleaseService-006, ADR-0012). |
| Traces: services | ReleaseService, ArtifactService |
| Traces: aggregates | ReleaseService/ProductRelease |
| Traces: apis | ReleaseService/CreateProductRelease |
| Traces: events | ReleaseService/ReleaseCreated |
| Traces: adrs | ADR-0012, ADR-0014, ADR-0015 |
| Traces: requirements | FR-08, XL-10 |
| Traces: scenarios | SCN-ReleaseService-003, SCN-ReleaseService-006 |
| Relates: screens | product-releases |
| Depends on | AIFACTORY-US-1294, AIFACTORY-US-1295, feature:artifact-service |
| Sources | model/services/devops-gitops/ReleaseService.yaml, docs/planes/execution/delivery-engine/services/release-service/index.md#apis |
Tasks
| Task | Kind | Expected output | Repository |
|---|---|---|---|
AIFACTORY-TASK-5123 CreateProductRelease from Assembling to Candidate with ReleaseCreated |
implementation | CreateProductRelease records the release Assembling, resolves components with digests and targets, stores SBOM and attestation references in ArtifactService, applies ComponentsResolved in the transaction of the ReleaseCreated outbox record and answers 201; the idempotent repeat, the 409 for a reused key or an existing version, the 422 for a run that did not succeed, a missing digest, missing provenance or missing attestations and the 403 are covered by acceptance tests. | ConnectSoft.AI.SoftwareFactory.ReleaseService |
AIFACTORY-TASK-5124 Contract of CreateProductRelease with its problem responses |
contract | The OpenAPI document of the service exposes POST /factory/delivery/releases with the Idempotency-Key header, the 201 answer and the problem responses 403, 409 and 422 as model/services/devops-gitops/ReleaseService.yaml lists them. | ConnectSoft.AI.SoftwareFactory.ReleaseService |
AIFACTORY-TASK-320 Verify create-a-product-release through the acceptance suite |
verification | Run dotnet test -c Release --filter "Category=Acceptance&(Scenario=SCN-ReleaseService-003\|Scenario=SCN-ReleaseService-006)"; a zero-match filter counts as a failure; the tests prove AC1 to AC4 of AIFACTORY-US-1289, that a release is immutable once created, that every component carries a digest and that ReleaseCreated is published once with its payload. |
ConnectSoft.AI.SoftwareFactory.ReleaseService |
AIFACTORY-US-1290: Assemble a candidate from a succeeded run and link merged proposals to the next release¶
behavior · persona operator
ReleaseService consumes two events of PipelineExecutionService through its inbox, each idempotent on the event id. The handler AssembleFromRun takes PipelineRunCompleted: a succeeded run on a release branch or tag assembles a candidate with its images, packages, SBOM and attestations through the same path as CreateProductRelease, from Assembling to Candidate with ReleaseCreated in the transaction of the transition, under the identity of the service; a run in any other state assembles nothing. The handler LinkProposal takes ChangeProposalMerged: the proposals merged since the last release of the project become part of the next one, and the next release records them in proposalIds. A redelivered event changes nothing, and the dependency on PipelineExecutionService is an event queue, so an outage delays assembly and loses nothing. Two inputs are not given by the model and are reported to the owner rather than invented: PipelineRunCompleted carries no branch, tag, product or version, so the handler cannot read the model's condition, a succeeded run on a release branch or tag, nor the version from the event alone, and no table holds a merged proposal before the release it will join exists. The acceptance below states the model's condition as it is written and is proven over events whose run is known to be on a release branch or tag; where the handler reads branch, tag, product and version from is an owner input.
Acceptance criteria
| AC1 | Given PipelineExecutionService/PipelineRunCompleted in state Succeeded for a run on a release branch or tag, when AssembleFromRun handles it, then one ReleaseService/ProductRelease is assembled in state Candidate through the path of ReleaseService/CreateProductRelease and ReleaseService/ReleaseCreated is written in the same transaction; a redelivery of the same event id assembles nothing (ADR-0014). |
| AC2 | Given PipelineExecutionService/PipelineRunCompleted in state Failed, Cancelled or PartiallySucceeded, when AssembleFromRun handles it, then no release is assembled and nothing is published (FR-08). |
| AC3 | Given PipelineExecutionService/ChangeProposalMerged for proposals of a project since its last release, when LinkProposal handles each, then the next release of that project records those proposals in proposalIds, and a redelivery links nothing twice (model/services/devops-gitops/ReleaseService.yaml). |
| Traces: services | ReleaseService, PipelineExecutionService |
| Traces: aggregates | ReleaseService/ProductRelease |
| Traces: apis | ReleaseService/CreateProductRelease |
| Traces: events | PipelineExecutionService/PipelineRunCompleted, PipelineExecutionService/ChangeProposalMerged, ReleaseService/ReleaseCreated |
| Traces: adrs | ADR-0012, ADR-0014 |
| Traces: requirements | FR-08 |
| Depends on | AIFACTORY-US-1289, feature:pipeline-execution-service-complete |
| Sources | model/services/devops-gitops/ReleaseService.yaml, model/services/devops-gitops/PipelineExecutionService.yaml, docs/planes/execution/delivery-engine/services/release-service/index.md#messages |
Tasks
| Task | Kind | Expected output | Repository |
|---|---|---|---|
AIFACTORY-TASK-5125 AssembleFromRun inbox handler for succeeded runs |
implementation | The handler of PipelineRunCompleted assembles a candidate through the CreateProductRelease path for a succeeded run on a release branch or tag, assembles nothing for any other state and is idempotent on the event id through the inbox of the release profile. | ConnectSoft.AI.SoftwareFactory.ReleaseService |
AIFACTORY-TASK-5126 LinkProposal inbox handler for merged proposals |
implementation | The handler of ChangeProposalMerged keeps the proposals merged since the last release of a project for the next release, which records them in proposalIds, idempotently on the event id. | ConnectSoft.AI.SoftwareFactory.ReleaseService |
AIFACTORY-TASK-5127 Verify assemble-release-from-pipeline-events through the acceptance suite |
verification | Run dotnet test -c Release --filter "Category=Acceptance&Feature=AssembleFromPipelineEvents"; a zero-match filter counts as a failure; the tests prove AC1 to AC3 of AIFACTORY-US-1290 over recorded PipelineExecutionService/PipelineRunCompleted events of a succeeded run on a release branch and of runs in the other states, and PipelineExecutionService/ChangeProposalMerged events, each delivered twice. |
ConnectSoft.AI.SoftwareFactory.ReleaseService |
AIFACTORY-US-1291: Verify the publication of every component, ready the release and draft its notes¶
behavior · persona operator
As an operator, I want a release to become ready only when every image and package is found in its registry or feed, so that nothing is promoted that its target cannot serve.
The PublicationVerifier worker starts from ReleaseCreated of this service. For each component of a Candidate release it checks the feed or registry of the component for its digest, through the publishing evidence of the existing CI and the reads ConnectorRegistryService/Connectors.ReadPackageFeed for a package and ConnectorRegistryService/Connectors.ReadContainerRegistry for an image, which the I2 feature connector-registry-service-deliveries delivers for Azure DevOps under the scope factory.connections.read with a brokered short-lived credential (D135), and records the publication Published with its evidence reference, the tool-receipt-v1 of the read, or Failed. ConnectorRegistryService degrades: an unanswered read counts as a failed attempt of the verifier, and the acceptance suite proves the verifier against fakes of both reads. It is idempotent on release id plus component name, retries exponentially six times with a backoff of 60 seconds and runs at most four in parallel, partitioned by tenant. When every component is Published the release moves from Candidate to Released (trigger AllPublished) and ReleaseReady with releaseId, tenantId, projectId, productId, version and components is written in the same transaction. When the newer release is Released, NewerReleased is applied to the earlier Released release of the same product, which moves to Superseded and is announced by no event; whether that move shares the transaction of AllPublished on the other aggregate is not stated by the model and is reported to the owner. The dispatcher publishes ReleaseReady on releases.products.v1.release-ready under the run event envelope and retries a transport outage with backoff (ADR-0012); EnvironmentPromotionService enables the promotion, WorkflowEngineService correlates it for the release workflow, and FleetRolloutService, StudioBff, AuditService and StudioNotificationService consume it in their own suites. When the retries are exhausted for a component that never appears, the release stays Candidate with the failing component named and the counter connectsoft.factory.delivery.publication_failures counts it; an Operator re-runs the publication in CI. The model names no trigger that verifies a component again after that, an open point reported to the owner. The ReleaseNotesWriter starts from ReleaseReady, drafts release notes from the merged proposals and the results with the model profile of Delivery:Releases:NotesProfile through ModelRouterService, stores them as an artifact in ArtifactService and records notesRef; the notes are never published automatically. ModelRouterService is optional: when it is unavailable no notes are written and the release is unaffected. The writer retries twice with a fixed backoff of 120 seconds and is idempotent on the release id. Recording notesRef on a Released release is read as outside the immutable content of the release, a reading reported to the owner.
Acceptance criteria
| AC1 | Given a Candidate ReleaseService/ProductRelease whose components all appear with their digests in the answers of ConnectorRegistryService/Connectors.ReadPackageFeed and ConnectorRegistryService/Connectors.ReadContainerRegistry, when the PublicationVerifier runs from ReleaseService/ReleaseCreated, then every component is Published with the receipt of its read as evidence, the release moves to Released, ReleaseService/ReleaseReady is written in the same transaction, and NewerReleased is applied to an earlier Released release of the same product, which moves to Superseded (SCN-ReleaseService-007, ADR-0014). |
| AC2 | Given the outbox record, when the dispatcher publishes ReleaseService/ReleaseReady on releases.products.v1.release-ready, then the event is sent under the run event envelope with releaseId, tenantId, projectId, productId, version and components, and a transport outage is retried with backoff so the event is neither lost nor duplicated under its event id (SCN-ReleaseService-007, ADR-0012). |
| AC3 | Given one component never appears in its registry, or the read of ConnectorRegistryService does not answer, when the six attempts of the verifier are exhausted, then the release stays Candidate with that component named as Failed, connectsoft.factory.delivery.publication_failures counts it, ReleaseService/ReleaseReady is not published, and a repeated trigger for the same release and component has no second effect (SCN-ReleaseService-007, model/services/devops-gitops/ReleaseService.yaml). |
| AC4 | Given ReleaseService/ReleaseReady, when the ReleaseNotesWriter runs, then release notes drafted with the profile of Delivery:Releases:NotesProfile are stored in ArtifactService and referenced by notesRef and published nowhere; given ModelRouterService is unavailable, no notes are written and the release keeps its state (model/services/devops-gitops/ReleaseService.yaml). |
| Traces: services | ReleaseService, ConnectorRegistryService, ArtifactService, ModelRouterService |
| Traces: aggregates | ReleaseService/ProductRelease |
| Traces: apis | ConnectorRegistryService/Connectors.ReadPackageFeed, ConnectorRegistryService/Connectors.ReadContainerRegistry |
| Traces: events | ReleaseService/ReleaseCreated, ReleaseService/ReleaseReady |
| Traces: adrs | ADR-0012, ADR-0014 |
| Traces: requirements | FR-08, NFR-08 |
| Traces: scenarios | SCN-ReleaseService-007 |
| Relates: screens | release-evidence |
| Depends on | AIFACTORY-US-1289, feature:connector-registry-service-deliveries, feature:artifact-service, feature:model-router-service |
| Sources | model/services/devops-gitops/ReleaseService.yaml, docs/planes/execution/delivery-engine/services/release-service/index.md#workers-and-jobs |
Tasks
| Task | Kind | Expected output | Repository |
|---|---|---|---|
AIFACTORY-TASK-267 Hosting of the workers PublicationVerifier and ReleaseNotesWriter |
implementation | The verifier is hosted on ReleaseCreated with exponential retry of six attempts, partitioning by tenant and the idempotency key releaseId and componentName, and the notes writer on ReleaseReady with fixed retry of two attempts and the idempotency key releaseId; a duplicate trigger has no second effect. Only the trigger, retry, partitioning and idempotency key wiring is done here; the behaviour of both workers is implemented by AIFACTORY-TASK-321. | ConnectSoft.AI.SoftwareFactory.ReleaseService |
AIFACTORY-TASK-321 Publication verifier and release notes |
implementation | A release becomes Released only after every image and package is verified in its registry or feed through Connectors.ReadContainerRegistry and Connectors.ReadPackageFeed under factory.connections.read, the receipt of each read kept as evidence, with ReleaseReady in the transaction of AllPublished, and NewerReleased is applied to the earlier Released release of the product; a component never found keeps the release Candidate with the component named; notes are drafted from the merged proposals and results, stored in ArtifactService and never published. | ConnectSoft.AI.SoftwareFactory.ReleaseService |
AIFACTORY-TASK-5128 Verify verify-publication-and-ready-a-release through the acceptance suite |
verification | Run dotnet test -c Release --filter "Category=Acceptance&Scenario=SCN-ReleaseService-007"; a zero-match filter counts as a failure; the tests prove AC1 to AC4 of AIFACTORY-US-1291 with fakes of Connectors.ReadPackageFeed and Connectors.ReadContainerRegistry that hold or lack a component or stop answering, a transport that can be stopped and a fake ModelRouterService that can be unavailable. |
ConnectSoft.AI.SoftwareFactory.ReleaseService |
AIFACTORY-US-1292: Withdraw a release with a reason so that it can no longer be promoted¶
behavior · persona operator
A caller whose scope carries factory.delivery.release, an Operator or a Workspace admin, withdraws a release of the caller's tenant and project through ReleaseService/WithdrawProductRelease with a reason. A Candidate or a Released release moves to Withdrawn (trigger Withdraw) and ReleaseWithdrawn with releaseId, tenantId, productId, version and reason is written in the same transaction; the answer is 200. The withdrawal blocks every later promotion of the release and revokes nothing already deployed. The dispatcher publishes ReleaseWithdrawn on releases.products.v1.release-withdrawn under the run event envelope and retries a transport outage with backoff, so the event is neither lost nor duplicated (ADR-0012); EnvironmentPromotionService blocks the promotion, and StudioBff and AuditService consume it, each in its own suite. The idempotency of the route is natural: a repeated withdrawal of a release already Withdrawn answers 200 and writes nothing. A Superseded release, from which the model draws no withdrawal, is refused with 409. A caller without the scope is refused with 403, and a release of another tenant is answered 404, the same answer as for a release that does not exist (ADR-0015).
Acceptance criteria
| AC1 | Given a Candidate or a Released ReleaseService/ProductRelease of my tenant and project, when ReleaseService/WithdrawProductRelease is called with a reason, then the response is 200, the release is Withdrawn and ReleaseService/ReleaseWithdrawn was written in the same transaction (SCN-ReleaseService-004, ADR-0014). |
| AC2 | Given a release already Withdrawn, a Superseded release, a caller without factory.delivery.release, or a release of another tenant or unknown, when ReleaseService/WithdrawProductRelease is called, then the repeat answers 200 and writes nothing, the Superseded release is refused with 409, the missing scope with 403 and the foreign or unknown release with 404, each refusal with a problem response and no state change (SCN-ReleaseService-004, ADR-0015). |
| AC3 | Given the outbox record, when the dispatcher publishes ReleaseService/ReleaseWithdrawn on releases.products.v1.release-withdrawn, then the event is sent under the run event envelope with releaseId, tenantId, productId, version and reason, and a transport outage is retried with backoff so the event is neither lost nor duplicated under its event id (SCN-ReleaseService-008, ADR-0012). |
| Traces: services | ReleaseService |
| Traces: aggregates | ReleaseService/ProductRelease |
| Traces: apis | ReleaseService/WithdrawProductRelease |
| Traces: events | ReleaseService/ReleaseWithdrawn |
| Traces: adrs | ADR-0012, ADR-0014, ADR-0015 |
| Traces: requirements | FR-08 |
| Traces: scenarios | SCN-ReleaseService-004, SCN-ReleaseService-008 |
| Relates: screens | release-detail |
| Depends on | AIFACTORY-US-1289 |
| Sources | model/services/devops-gitops/ReleaseService.yaml, docs/planes/execution/delivery-engine/services/release-service/index.md#apis |
Tasks
| Task | Kind | Expected output | Repository |
|---|---|---|---|
AIFACTORY-TASK-5129 WithdrawProductRelease with ReleaseWithdrawn |
implementation | WithdrawProductRelease applies Withdraw from Candidate or Released in the transaction of the ReleaseWithdrawn outbox record with the reason, answers 200, answers 200 without a write for a release already Withdrawn, 409 for a Superseded release, 403 for a missing scope and 404 for a foreign or unknown release. | ConnectSoft.AI.SoftwareFactory.ReleaseService |
AIFACTORY-TASK-5130 Verify withdraw-a-product-release through the acceptance suite |
verification | Run dotnet test -c Release --filter "Category=Acceptance&(Scenario=SCN-ReleaseService-004\|Scenario=SCN-ReleaseService-008)"; a zero-match filter counts as a failure; the tests prove AC1 to AC3 of AIFACTORY-US-1292 over a two-tenant fixture and a transport that can be stopped; consumer handling is proven by the consumers' own suites. |
ConnectSoft.AI.SoftwareFactory.ReleaseService |
AIFACTORY-US-1293: Resolve a release with its digests and evidence for promotion over gRPC¶
behavior
EnvironmentPromotionService, the inbound caller the model names, and the fleet inventory in its increment call the internal gRPC method ReleaseService/Releases.GetRelease with a workload identity to resolve a release before a promotion. The reply carries the release with its state, version, commit, the components with their digests and publication evidence, the SBOM and attestation references, so that the promotion deploys exactly the digests of the release and refuses a release that is not Released; a Withdrawn release is answered in state Withdrawn. The method is of class read: it writes nothing and publishes nothing, and a repeated call returns the same answer while the release does not change. The method admits a workload token only with factory.delivery.read, the service scope of the method (D114, D135). A caller without a workload identity is refused with UNAUTHENTICATED, a token without factory.delivery.read with PERMISSION_DENIED, a request without a release id with INVALID_ARGUMENT, and an unknown release and a release of another tenant alike with NOT_FOUND, which never confirms that a foreign release exists (ADR-0015 amendment D114). The request and the reply are typed release-manifest-v1, the manifest of an asset release, which has no member for components, digests or publication evidence of a product release; which descriptor carries them is an open point reported to the owner, and this PBI does not invent members.
Acceptance criteria
| AC1 | Given EnvironmentPromotionService with a workload token that holds factory.delivery.read and a Released ReleaseService/ProductRelease of the forwarded tenant, when ReleaseService/Releases.GetRelease is called with its release id, then the reply carries the state, version, commit, components with digests and publication evidence and the SBOM and attestation references, and nothing is written (SCN-ReleaseService-005). |
| AC2 | Given a Withdrawn or a Candidate release, when ReleaseService/Releases.GetRelease is called, then the reply carries that state, so the caller can refuse the promotion of a release that is not Released (SCN-ReleaseService-005). |
| AC3 | Given a caller without a workload identity, a token without factory.delivery.read, a request without a release id, or a release that is unknown or of another tenant, when ReleaseService/Releases.GetRelease is called, then the call is refused with UNAUTHENTICATED, PERMISSION_DENIED, INVALID_ARGUMENT or NOT_FOUND respectively, the foreign release answered like the unknown one, and no state changes (SCN-ReleaseService-005, ADR-0015). |
| Traces: services | ReleaseService, EnvironmentPromotionService |
| Traces: aggregates | ReleaseService/ProductRelease |
| Traces: apis | ReleaseService/Releases.GetRelease |
| Traces: descriptors | release-manifest-v1 |
| Traces: adrs | ADR-0015 |
| Traces: requirements | FR-08 |
| Traces: scenarios | SCN-ReleaseService-005 |
| Depends on | AIFACTORY-US-1294, AIFACTORY-US-1295 |
| Sources | model/services/devops-gitops/ReleaseService.yaml, docs/reference/schemas/release-manifest.schema.json, docs/planes/execution/delivery-engine/services/release-service/index.md#apis |
Tasks
| Task | Kind | Expected output | Repository |
|---|---|---|---|
AIFACTORY-TASK-5131 Releases.GetRelease read method for promotion and fleet inventory |
implementation | The gRPC method resolves a release by id under the tenant row filter and replies with state, version, commit, components with digests and evidence and the SBOM and attestation references, writes nothing, admits a workload token only with factory.delivery.read, and refuses with UNAUTHENTICATED, PERMISSION_DENIED, INVALID_ARGUMENT or NOT_FOUND, a foreign release like an unknown one. | ConnectSoft.AI.SoftwareFactory.ReleaseService |
AIFACTORY-TASK-5132 Verify resolve-a-release-for-promotion through the acceptance suite |
verification | Run dotnet test -c Release --filter "Category=Acceptance&Scenario=SCN-ReleaseService-005"; a zero-match filter counts as a failure; the tests prove AC1 to AC3 of AIFACTORY-US-1293 over Released, Candidate and Withdrawn releases of two tenants. |
ConnectSoft.AI.SoftwareFactory.ReleaseService |
AIFACTORY-US-1294: Scaffold ReleaseService with the ProductRelease aggregate and its store¶
enabling
ReleaseService has its own repository, ConnectSoft.AI.SoftwareFactory.ReleaseService, its own deployable and its own stores (ADR-0028). The repository is created by the steps of the repository checklist of feature repository-and-pipeline-conventions and scaffolded once from the pinned base template package with UseFactoryProfile (feature component-base-template-factory-profile, consumed by its pinned version), so token validation, scope enforcement, problem responses, the tenant row filter, health, readiness and the telemetry wiring come from the profile. The domain model holds the ProductRelease aggregate with its ReleaseComponent entities, the states of ReleaseState, the five transitions the model draws (ComponentsResolved, AllPublished, NewerReleased and Withdraw from Candidate and from Released), the kinds of ComponentKind, the publication states of PublicationState and its three invariants: a Released release is immutable and a Withdrawn one cannot be promoted, every component has a digest and a component without evidence keeps the release Candidate, and a release without provenance is refused. The store release-sql holds ProductReleases and ReleaseComponents with the unique index UX_Releases_Product_Version, the index IX_Releases_State and the tenant filter; SBOMs, attestations and notes live by reference in ArtifactService. Mapping tests run against an isolated test database. When the store is lost it is restored from backup within the recovery point of 15 minutes.
Acceptance criteria
| AC1 | Given the repository created by the repository checklist, when its pipeline runs, then the first commit is the unchanged output of dotnet new connectsoft-base -n ConnectSoft.AI.SoftwareFactory.ReleaseService --UseFactoryProfile true from the pinned template package, the solution builds and the template tests pass (ADR-0028, model/services/devops-gitops/ReleaseService.yaml). |
| AC2 | Given the domain model, when its unit tests run, then the ReleaseService/ProductRelease applies each of its five drawn transitions from its source state only, refuses every other move, refuses a component without a digest and a release without provenance, and keeps a Released release unchanged (ADR-0014). |
| AC3 | Given the store release-sql, when the mapping tests run against an isolated test database, then ProductReleases and ReleaseComponents are mapped with their keys, the unique index on tenant, product and version and the tenant filter, and a row of another tenant is never read (ADR-0015). |
| Traces: services | ReleaseService |
| Traces: aggregates | ReleaseService/ProductRelease |
| Traces: adrs | ADR-0014, ADR-0015, ADR-0028 |
| Depends on | feature:repository-and-pipeline-conventions, feature:component-base-template-factory-profile |
| Sources | model/services/devops-gitops/ReleaseService.yaml, docs/planes/execution/delivery-engine/services/release-service/index.md#domain-model |
Tasks
| Task | Kind | Expected output | Repository |
|---|---|---|---|
AIFACTORY-TASK-262 Create the repository ConnectSoft.AI.SoftwareFactory.ReleaseService and scaffold it from the ConnectSoft.BaseTemplate template |
implementation | The repository exists by the steps of the repository checklist of feature repository-and-pipeline-conventions; its first commit is the unchanged output of dotnet new connectsoft-base -n ConnectSoft.AI.SoftwareFactory.ReleaseService --UseFactoryProfile true from the pinned template package, whose version the repository records, with the messaging service name release; the solution builds and the template tests pass in the repository pipeline. |
ConnectSoft.AI.SoftwareFactory.ReleaseService |
AIFACTORY-TASK-263 Domain model: ProductRelease |
implementation | Aggregates with their invariants and state transitions as modelled; unit tests cover every invariant and every transition. | ConnectSoft.AI.SoftwareFactory.ReleaseService |
AIFACTORY-TASK-264 Persistence in release-sql: ProductReleases, ReleaseComponents |
migration | Mappings and migrations for the modelled tables with tenant filters and indexes; mapping tests run against an isolated test database, never a shared one. | ConnectSoft.AI.SoftwareFactory.ReleaseService |
AIFACTORY-TASK-5133 Verify the scaffold, domain and store of ReleaseService |
verification | Run dotnet test -c Release --filter "Category=Unit\|Category=Mapping"; a zero-match filter counts as a failure; the tests prove AC1 to AC3 of AIFACTORY-US-1294 against model/services/devops-gitops/ReleaseService.yaml. |
ConnectSoft.AI.SoftwareFactory.ReleaseService |
AIFACTORY-US-1295: Host every operation, event and handler of ReleaseService with its security and telemetry¶
enabling
ReleaseService hosts its four REST routes and its gRPC method behind the scopes factory.delivery.read and factory.delivery.release, with problem responses for every modelled code, the Idempotency-Key filter of CreateProductRelease and the workload check of Releases.GetRelease; the behaviour of each operation is delivered by its own PBI. The messaging profile release publishes ReleaseCreated, ReleaseReady and ReleaseWithdrawn under the run event envelope through its outbox and registers PipelineRunCompleted and ChangeProposalMerged of PipelineExecutionService in its inbox with idempotency on the event id; the gauge connectsoft.factory.delivery.inbox_lag reports the age of the oldest unprocessed message, and the inbox and the outbox belong to this service alone (ADR-0028). Tenant isolation is a row filter on every query; the only secret, the messaging transport, comes from Key Vault by reference with a rotation of 90 days; the data classification is internal and the highest side-effect class is shared-write. A user token reaches the service with the audience of its gateway, DeliveryHost, which the service accepts (ADR-0015 amendment D117). Traces, the three metrics of the model and health checks follow the observability conventions, and readiness stays unready while the store is unavailable.
Acceptance criteria
| AC1 | Given the hosted service, when each REST route and ReleaseService/Releases.GetRelease is called without a token, with a token lacking its scope or without a workload identity, then it is refused with the modelled problem response or gRPC status before any handler runs (ADR-0015, model/services/devops-gitops/ReleaseService.yaml). |
| AC2 | Given the messaging profile release, when the contract tests run, then ReleaseService/ReleaseCreated, ReleaseService/ReleaseReady and ReleaseService/ReleaseWithdrawn carry their modelled payload under the run event envelope, and PipelineExecutionService/PipelineRunCompleted and PipelineExecutionService/ChangeProposalMerged are registered in the inbox with idempotency on the event id (ADR-0012, ADR-0014). |
| AC3 | Given a query of any route, when it runs, then it is filtered by the trusted tenant, the three metrics of the model are emitted with their dimensions, and no secret value reaches a log record, an event or a reply (ADR-0015). |
| Traces: services | ReleaseService |
| Traces: apis | ReleaseService/Releases.GetRelease |
| Traces: events | ReleaseService/ReleaseCreated, ReleaseService/ReleaseReady, ReleaseService/ReleaseWithdrawn, PipelineExecutionService/PipelineRunCompleted, PipelineExecutionService/ChangeProposalMerged |
| Traces: adrs | ADR-0012, ADR-0014, ADR-0015, ADR-0028 |
| Traces: requirements | NFR-12 |
| Depends on | AIFACTORY-US-1294, feature:delivery-host, feature:pipeline-execution-service-complete |
| Sources | model/services/devops-gitops/ReleaseService.yaml, docs/planes/execution/delivery-engine/services/release-service/index.md#security |
Tasks
| Task | Kind | Expected output | Repository |
|---|---|---|---|
AIFACTORY-TASK-265 API surface: 4 REST and 1 gRPC operations (ListProductReleases, GetProductRelease, CreateProductRelease, WithdrawProductRelease, Releases.GetRelease) |
implementation | Every modelled operation is hosted with its scope, side-effect class, idempotency rule and problem responses, and the OpenAPI and proto documents match the model; the behaviour of each operation is delivered by AIFACTORY-US-1288, AIFACTORY-US-1289, AIFACTORY-US-1292 and AIFACTORY-US-1293. | ConnectSoft.AI.SoftwareFactory.ReleaseService |
AIFACTORY-TASK-266 Messaging: publishes 3 events, handles 2 |
implementation | Events are published through the outbox of the service with the run envelope (ReleaseCreated, ReleaseReady, ReleaseWithdrawn); consumed events are handled idempotently through its inbox. | ConnectSoft.AI.SoftwareFactory.ReleaseService |
AIFACTORY-TASK-268 Security, tenancy and telemetry of ReleaseService |
implementation | Scopes and roles of the model are enforced, every query is tenant-filtered, secrets come from secret references, and traces, metrics and health checks follow the observability conventions. | ConnectSoft.AI.SoftwareFactory.ReleaseService |
AIFACTORY-TASK-5134 Verify the hosting of ReleaseService through the contract suite |
verification | Run dotnet test -c Release --filter "Category=Contract"; a zero-match filter counts as a failure; the tests prove AC1 to AC3 of AIFACTORY-US-1295 against model/services/devops-gitops/ReleaseService.yaml and model/descriptors.yaml. |
ConnectSoft.AI.SoftwareFactory.ReleaseService |