AIFACTORY-FEAT-043: EnvironmentPromotionService: 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 95 of 185 (Factory code)
EnvironmentPromotionService is the service of bounded context BC-24 (Package & Release Delivery). Promotion of a ready release into an environment class (development, test, staging, production) through gates — pipeline results, deployment-domain policy, an approval of class production for production, the environment's state — with the desired-state hand-off to provisioning (BC-25), progressive strategies, verification and rollback evidence (BC-24). Its own repository is ConnectSoft.AI.SoftwareFactory.EnvironmentPromotionService.
| Delivers | EnvironmentPromotionService (complete) |
| Stubs | — |
| Realizes | adrs: ADR-0004, ADR-0015 |
| Requirements | FR-08, FUX-02, FUX-05, NFR-08, NFR-09, XL-04, XL-10 |
| Depends on | — |
| Sources | model/services/devops-gitops/EnvironmentPromotionService.yaml |
Scenarios to trace (11, catalog): SCN-EnvironmentPromotionService-001 ✓, SCN-EnvironmentPromotionService-002 ✓, SCN-EnvironmentPromotionService-003 ✓, SCN-EnvironmentPromotionService-004 ✓, SCN-EnvironmentPromotionService-005 ✓, SCN-EnvironmentPromotionService-006 ✓, SCN-EnvironmentPromotionService-007 ✓, SCN-EnvironmentPromotionService-008 ✓, SCN-EnvironmentPromotionService-009 ✓, SCN-EnvironmentPromotionService-010 ✓, SCN-EnvironmentPromotionService-011 ✓
AIFACTORY-US-024: EnvironmentPromotionService promotes a ready release through its gates, one bound production approval, provisioning and verification¶
behavior · persona reviewer
As a reviewer, I want a promotion to production to wait for my one decision on the exact release and environment, and every promotion to pass its gates before anything is deployed, so that nothing reaches production that I did not approve, the requester never approves their own request, and every environment knows which release it runs.
This is the integration PBI of EnvironmentPromotionService, the service of bounded context BC-24 (Package and Release Delivery) that puts a ready release into an environment class of the project, development, test, staging or production, through gates: the pipeline results of the release, the deployment-domain policy, asked with the action kind promotion and the class of the target environment (D140), the prior environment of the promotion path, the state of the environment, evaluation evidence where the release carries agent-generated assets and, for production, one approval of class production. It hands the desired state to IaCProvisioningService, which deploys it (the service never touches infrastructure), verifies the result and records rollback evidence. The repository ConnectSoft.AI.SoftwareFactory.EnvironmentPromotionService is created by the first task of this feature by the steps of the repository checklist of feature repository-and-pipeline-conventions: it is scaffolded once from the pinned base template package with UseFactoryProfile (features component-base-template-factory-profile and component-base-template-findings, consumed by pin), so token validation, the role policies, the scope chain with its 401, 403 and 404 answers, the tenant row filter, the Orleans messaging profile with the service name environment-promotion, the scheduler, health, readiness and the telemetry wiring come from the profile and are not written again. Every integration event is written as the run event envelope of the pinned contracts package to the outbox in the transaction of its transition. The public REST operations are reached through DeliveryHost, which forwards the user token unchanged; the service accepts the audience of its own gateway and exchanges no token (ADR-0015 amendment D117). A promotion or an environment of another tenant is answered 404, over gRPC NOT_FOUND, the same answer as for an unknown identifier, and a missing scope or project role 403 (ADR-0015 amendment D113). The feature is delivered by seven further PBIs: requesting a promotion (AIFACTORY-US-1311), the gates and the desired-state hand-off (AIFACTORY-US-1312), the one production approval (AIFACTORY-US-1313), deployment, verification and the automatic rollback (AIFACTORY-US-1314), the rollback by an Operator (AIFACTORY-US-1315), the reads (AIFACTORY-US-1316) and, in the repository of RunControlService, the settlement of the step of a run that waits for a promotion from PromotionCompleted and PromotionFailed (AIFACTORY-US-1621, D140). A rollback opens a new promotion of the previous release whose rollbackOfPromotionId names the promotion it rolls back; the new promotion skips the approval gate, passes the other gates and hands off through PromotionApproved like any promotion, and the rolled-back promotion ends RolledBack with RollbackCompleted when the new one completes (D135). The inbox registers the eight consumed events of the model, ReleaseReady, ReleaseWithdrawn, ApprovalDecided, EnvironmentStateChanged, ProvisioningApplied, ProvisioningFailed, ProvisioningPlanned and ObservedStateChanged, each idempotent on the event id. SloService, an optional dependency that degrades, is delivered in I4, so in this increment the SLO window of a verification is recorded as not evaluated. Telemetry carries tenant and project on metrics and no release content, desired state or verification payload reaches a log record (ADR-0019).
Acceptance criteria
| AC1 | Given the repository ConnectSoft.AI.SoftwareFactory.EnvironmentPromotionService created by the steps of the repository checklist, whose first commit is the unchanged output of dotnet new connectsoft-base -n ConnectSoft.AI.SoftwareFactory.EnvironmentPromotionService --UseFactoryProfile true from the pinned template package, when its pipeline runs with the work of this feature, then no second scaffold was run, the solution builds, the unit and acceptance tests pass with complete reports and a container image is published (ADR-0028, model/services/devops-gitops/EnvironmentPromotionService.yaml). |
| AC2 | Given the service descriptor of the repository, when the contract test compares it with the hosted surface, then EnvironmentPromotionService/ListPromotions, EnvironmentPromotionService/GetPromotion, EnvironmentPromotionService/RequestPromotion, EnvironmentPromotionService/RollbackPromotion, EnvironmentPromotionService/GetCurrentRelease and EnvironmentPromotionService/Promotions.Request are hosted with the scope, side-effect class, idempotency and response codes of model/services/devops-gitops/EnvironmentPromotionService.yaml, and the test fails on an operation the file does not name. |
| AC3 | Given the EnvironmentPromotionService/Promotion aggregate, when its unit tests run, then each of the twelve transitions of PromotionState is accepted from its source state only, every other pair of states is refused, and the invariants hold: a production promotion is approved only through the approval bound to its release id and environment, a release enters production only after it completed in the prior class of Delivery:Promotions:PromotionPath, unless policy allows a hotfix path with evidence, and the service never calls infrastructure (ADR-0015, model/services/devops-gitops/EnvironmentPromotionService.yaml). |
| AC4 | Given the outbox and the inbox after the acceptance suite, when their records are read, then EnvironmentPromotionService/PromotionRequested, EnvironmentPromotionService/PromotionApproved, EnvironmentPromotionService/PromotionCompleted, EnvironmentPromotionService/PromotionFailed and EnvironmentPromotionService/RollbackCompleted are the only event types the outbox holds, each written in the transaction of its transition under the run event envelope, and the inbox registers the eight consumed events of the model with idempotency on the event id (ADR-0014). |
| AC5 | Given the service starts, when liveness and readiness are probed and the acceptance suite has run, then readiness is unready until environment-promotion-sql is migrated and while the outbox check of the messaging profile is unhealthy, the four metrics of the model are emitted with their modelled dimensions, and a scan of the captured log records, activities and metrics finds no token, desired state or verification payload (ADR-0019, model/services/devops-gitops/EnvironmentPromotionService.yaml). |
| Traces: services | EnvironmentPromotionService, DeliveryHost, ReleaseService, PolicyEngineService, RunControlService, IaCProvisioningService, EnvironmentService, RuntimeEnvironmentService |
| Traces: aggregates | EnvironmentPromotionService/Promotion |
| Traces: apis | EnvironmentPromotionService/ListPromotions, EnvironmentPromotionService/GetPromotion, EnvironmentPromotionService/RequestPromotion, EnvironmentPromotionService/RollbackPromotion, EnvironmentPromotionService/GetCurrentRelease, EnvironmentPromotionService/Promotions.Request |
| Traces: events | EnvironmentPromotionService/PromotionRequested, EnvironmentPromotionService/PromotionApproved, EnvironmentPromotionService/PromotionCompleted, EnvironmentPromotionService/PromotionFailed, EnvironmentPromotionService/RollbackCompleted |
| Traces: workflows | delivery-run |
| Traces: steps | delivery-run/request-promotion, delivery-run/approve-production |
| Traces: agents | deployment-orchestrator |
| Traces: descriptors | run-event-envelope-v1 |
| Traces: adrs | ADR-0004, ADR-0014, ADR-0015, ADR-0019, ADR-0028 |
| Traces: requirements | FR-08, FUX-02, FUX-05, NFR-08, NFR-09, XL-04, XL-10 |
| Relates: screens | promotions, environment-board |
| Depends on | AIFACTORY-US-1311, AIFACTORY-US-1312, AIFACTORY-US-1313, AIFACTORY-US-1314, AIFACTORY-US-1315, AIFACTORY-US-1316, AIFACTORY-US-1621, feature:repository-and-pipeline-conventions, feature:component-base-template-factory-profile, feature:component-base-template-findings, feature:component-extensions-ai, feature:component-observability-factory-conventions, feature:contracts-package |
| Sources | model/services/devops-gitops/EnvironmentPromotionService.yaml, docs/planes/execution/delivery-engine/services/environment-promotion-service/index.md#purpose-and-responsibilities, docs/architecture/adr/0015-factory-tenancy-under-canonical-adr-0100.md, docs/architecture/adr/0028-one-repository-and-deployable-per-service.md |
Tasks
| Task | Kind | Expected output | Repository |
|---|---|---|---|
AIFACTORY-TASK-248 Create the repository ConnectSoft.AI.SoftwareFactory.EnvironmentPromotionService and scaffold it from the ConnectSoft.BaseTemplate template with the Factory profile |
implementation | The repository exists, created 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.EnvironmentPromotionService --UseFactoryProfile true from the pinned template package, whose version the repository records, with the messaging service name environment-promotion; the solution builds and the template tests pass in the repository pipeline, which publishes the container image; a deviation is corrected in the repository before the work of this feature is added. |
ConnectSoft.AI.SoftwareFactory.EnvironmentPromotionService |
AIFACTORY-TASK-249 Domain model: Promotion with the twelve transitions of PromotionState and its invariants |
implementation | The Promotion aggregate holds the fields of the model, the gates per gate kind with outcome and evidence reference, and the twelve transitions Start, GatesPassedApprovalRequired, GatesPassedNoApproval, GateFailed, ApprovalGranted, ApprovalRejectedOrExpired, DesiredStateHandedOff, ProvisioningApplied, VerificationPassed, VerificationFailedAutoRollback, ProvisioningFailed and ManualRollback; unit tests cover every transition, every refused pair of states and every invariant of model/services/devops-gitops/EnvironmentPromotionService.yaml. | ConnectSoft.AI.SoftwareFactory.EnvironmentPromotionService |
AIFACTORY-TASK-250 Persistence in environment-promotion-sql: Promotions and PromotionGates with the tenant filter and the modelled indexes |
migration | Mappings and migrations for the tables Promotions and PromotionGates with the tenant column and row filter, the key of promotion and gate kind, the indexes IX_Promotions_Env_State and IX_Promotions_Release and a row version as optimistic concurrency token on a promotion; mapping tests run against an isolated test database, never a shared one. | ConnectSoft.AI.SoftwareFactory.EnvironmentPromotionService |
AIFACTORY-TASK-251 API hosting skeleton: service descriptor, REST and gRPC hosts, scope policies and problem responses of the 5 REST and 1 gRPC operations |
contract | The service descriptor lists ListPromotions, GetPromotion, RequestPromotion, RollbackPromotion, GetCurrentRelease and Promotions.Request with scope, side-effect class, idempotency and response codes; the routes and the gRPC method are hosted with the scope policy of each route, problem responses for every modelled refusal code, the Idempotency-Key filter of RequestPromotion and the check of the service scope of a workload token on the gRPC method; the behaviour of each operation is delivered by AIFACTORY-US-1311, AIFACTORY-US-1315 and AIFACTORY-US-1316, not here. | ConnectSoft.AI.SoftwareFactory.EnvironmentPromotionService |
AIFACTORY-TASK-252 Messaging skeleton: outbox and inbox wiring of the environment-promotion profile for 5 published and 8 consumed events |
implementation | The outbox writer enlists in the unit of work of a command, a handler and a worker step, and the dispatcher of the environment-promotion messaging profile publishes PromotionRequested, PromotionApproved, PromotionCompleted, PromotionFailed and RollbackCompleted under the run event envelope of the pinned contracts package; the inbox registers ReleaseReady, ReleaseWithdrawn, ApprovalDecided, EnvironmentStateChanged, ProvisioningApplied, ProvisioningFailed, ProvisioningPlanned and ObservedStateChanged with idempotency on the event id; what each handler does is delivered by AIFACTORY-US-1311 to AIFACTORY-US-1314. | ConnectSoft.AI.SoftwareFactory.EnvironmentPromotionService |
AIFACTORY-TASK-253 Worker hosting skeleton: triggers, partitioning and retry policies of GateEvaluator and Verifier |
implementation | GateEvaluator is hosted on PromotionRequested with fixed retry of 3 attempts and 30 seconds, idempotency key promotionId plus gateKind and partitioning by EnvironmentId with at most 4 in parallel; Verifier is hosted on ProvisioningApplied with fixed retry of 3 attempts and 60 seconds, idempotency key promotionId and the same partitioning; a duplicate trigger has no second effect; what each worker does is delivered by AIFACTORY-US-1312 and AIFACTORY-US-1314. | ConnectSoft.AI.SoftwareFactory.EnvironmentPromotionService |
AIFACTORY-TASK-254 Security, tenancy and telemetry of EnvironmentPromotionService |
implementation | The scopes factory.delivery.read, factory.delivery.promote and factory.delivery.operate and the roles Operator, Reviewer, Workspace admin, Platform admin and Observer are enforced per route; a user token forwarded by DeliveryHost is accepted with the audience of that gateway; every query is tenant-filtered so a resource of another tenant is answered 404; the messaging-transport secret comes from a secret reference of the key vault; connectsoft.factory.delivery.promotions, promotion_lead_time, rollbacks and inbox_lag are created through the instrument helper of the observability library with their modelled dimensions; a redaction test fails when a log record, an activity or a metric holds a token, a desired state or a verification payload. | ConnectSoft.AI.SoftwareFactory.EnvironmentPromotionService |
AIFACTORY-TASK-5261 Runbook of the three failure modes of EnvironmentPromotionService |
documentation | The repository documentation holds one runbook entry per failure mode of model/services/devops-gitops/EnvironmentPromotionService.yaml (approval expires, verification fails, service store lost) with its detection signal, the state the promotion takes and the recovery step: a new request binds a new approval, the automatic rollback with its evidence, and the restore from backup after which receipts are re-pulled from the system of record. | ConnectSoft.AI.SoftwareFactory.EnvironmentPromotionService |
AIFACTORY-TASK-708 Verify promotion-under-approval by running the declared command |
verification | Run dotnet build -c Release and dotnet test -c Release --no-build in the pipeline of the repository; a run that discovers no test counts as a failure; the runs pass and prove AC1 to AC5 of AIFACTORY-US-024, that is the scaffold, the hosted surface against the service descriptor, the twelve transitions and the invariants of the Promotion aggregate, the event types of the outbox and the inbox, readiness and the redaction scan. |
ConnectSoft.AI.SoftwareFactory.EnvironmentPromotionService |
AIFACTORY-US-1311: Request the promotion of a ready release into an environment through the REST route or the internal gRPC method¶
behavior · persona operator
As an operator, I want to request the promotion of a ready release into an environment of my project, or have the deploy-environment tool request it for a run, so that a promotion exists once per request, only for a release that is ready and an environment on the promotion path, and its gates start without anyone driving them.
An Operator or a Workspace admin whose scope carries factory.delivery.promote requests a promotion through the DeliveryHost route of EnvironmentPromotionService/RequestPromotion with an Idempotency-Key, naming the release, the target environment and the strategy, one of Recreate, RollingUpdate, BlueGreen or Canary. RequestPromotion requires a strategy and answers 422 without one; Strategy has no default (D135). The deploy-environment tool requests the same through the internal method EnvironmentPromotionService/Promotions.Request, and the reply is ack-v1. A workload token carries service scopes and no tenant claim, so the method admits a workload token only when it holds the service scope of the method, factory.delivery.promote (D135), and the service reads the tenant and the project that the workload forwards in its metadata only under that scope (ADR-0015 amendment D114). Beside the tenant and the project the call metadata carries the requester of the run as delegatedUserId, and the request carries the runId and the stepRunId of the requesting step; the service keeps the delegated user as requestedBy and the run and the step run on the promotion, so that the Policy gate names the requester of the run as the delegated user of the workload subject (AIFACTORY-US-1312) and PromotionCompleted and PromotionFailed echo the run correlation (D141). The service knows a release only from its inbox: EnablePromotion records each ReleaseService/ReleaseReady with its tenant and project, and BlockPromotion marks the release withdrawn on ReleaseService/ReleaseWithdrawn. It knows an environment only from the last state and class that GateEnvironment kept from EnvironmentService/EnvironmentStateChanged. A request is checked against these records and calls no other service. A release that the service has not recorded in the tenant of the caller, whether unknown, of another tenant or never announced ready, is answered 404, and so is an environment that has announced no state in that tenant; the answer is the same for all of them, so a refusal never confirms a resource of another tenant (ADR-0015 amendment D113). The model lists no 404 for RequestPromotion, which is reported as a code the model omits. A withdrawn release is refused with 412. An environment whose class is not on Delivery:Promotions:PromotionPath, a Sandbox environment among them, is refused with 422. EnvironmentStateChanged carries no project, so the service cannot check that the environment belongs to the project of the release; that check is reported as an open point and is not asserted. The promotion takes the project of the release, and the caller must hold a role in that project. On success the service writes the Promotion in state Requested with requestedBy, the optional runId and stepRunId (D141), the strategy and the class of the environment, together with the PromotionRequested outbox record in one transaction, increments connectsoft.factory.delivery.promotions and answers 202 with the location of the promotion; the gates start from that event (AIFACTORY-US-1312). A repeat under the same key and the same body returns the same promotion and changes nothing; the same key with another body is refused with 409, and a request without an Idempotency-Key with 422. A body without a release or an environment, or with an unknown strategy, is refused with 422, and a caller without the scope or without a role in the project of the release with 403. Over gRPC a caller without a workload identity is refused with UNAUTHENTICATED, a workload token without the service scope of the method with PERMISSION_DENIED, an invalid request with INVALID_ARGUMENT, a release or an environment not recorded in the forwarded tenant with NOT_FOUND and a withdrawn release with FAILED_PRECONDITION. The gRPC repeat is keyed as the workflow step delivery-run/request-promotion keys it, on the run, the release and the target environment: a repeat returns the same acknowledgement and creates no second promotion. No refusal writes a promotion or publishes anything. PromotionRequested carries promotionId, tenantId, projectId, releaseId, environmentId, environmentClass and the optional runId; StudioBff, AuditService and DashboardService handle it in their own PBIs. The request of Promotions.Request is release-manifest-v1 with the runId and the stepRunId of the requesting step beside it (D141); the manifest names neither the target environment, the strategy nor the receipt, so the members that carry them are reported as an open point. A release of the tenant of the caller that is still a candidate is answered 404 like an unknown one, because the service learns of a release only from ReleaseReady; this is reported as well.
Acceptance criteria
| AC1 | Given a release recorded ready by ReleaseService/ReleaseReady, an environment of the tenant whose class is on Delivery:Promotions:PromotionPath as EnvironmentService/EnvironmentStateChanged announced it, and a caller with factory.delivery.promote and a role in the project of the release, when EnvironmentPromotionService/RequestPromotion is called with an Idempotency-Key and a strategy, then the response is 202 with the location of the promotion, the EnvironmentPromotionService/Promotion is in state Requested with the project of the release, requestedBy, the strategy and the environment class, the EnvironmentPromotionService/PromotionRequested outbox record is written in the same transaction, and a repeat under the same key and body returns the same promotion and writes nothing (SCN-EnvironmentPromotionService-003). |
| AC2 | Given the same key with another body, a request without an Idempotency-Key, a body without a release, an environment or a strategy or with an unknown strategy, an environment whose class is not on the promotion path, a release that ReleaseService/ReleaseWithdrawn marked withdrawn, a release or an environment not recorded in the tenant of the caller whether unknown, of another tenant or never announced, or a caller without the scope or without a role in the project, when EnvironmentPromotionService/RequestPromotion is called, then the response is 409, 422, 422, 422, 412, 404 for every release and environment case alike, or 403 respectively, with a problem response, no promotion written and nothing published (SCN-EnvironmentPromotionService-003, ADR-0015). |
| AC3 | Given a workload token that holds the service scope factory.delivery.promote of the method and forwards a tenant, a project and the requester of the run as delegatedUserId, and a request for a ready release, an environment on the promotion path and its run with the runId and the stepRunId of the requesting step, when EnvironmentPromotionService/Promotions.Request is called, then the reply is ack-v1, the promotion is written in state Requested with its runId, its stepRunId and the delegated user as requestedBy (D141) and PromotionRequested, and a repeat for the same run, release and target environment returns the same acknowledgement and creates no second promotion; a caller without a workload identity, a workload token without the service scope, an invalid request, a release or an environment not recorded in the forwarded tenant, or a withdrawn release is refused with UNAUTHENTICATED, PERMISSION_DENIED, INVALID_ARGUMENT, NOT_FOUND or FAILED_PRECONDITION and nothing is written (SCN-EnvironmentPromotionService-006, ADR-0015). |
| AC4 | Given the promotion was requested, when the outbox dispatcher of the environment-promotion profile publishes EnvironmentPromotionService/PromotionRequested on releases.promotions.v1.promotion-requested, then the event is sent under the run event envelope with promotionId, tenantId, projectId, releaseId, environmentId, environmentClass and the runId when the request carried one, and a transport outage is retried with backoff so the event is neither lost nor duplicated under its event id (SCN-EnvironmentPromotionService-007, ADR-0012). |
| Traces: services | EnvironmentPromotionService, ReleaseService, EnvironmentService |
| Traces: aggregates | EnvironmentPromotionService/Promotion |
| Traces: apis | EnvironmentPromotionService/RequestPromotion, EnvironmentPromotionService/Promotions.Request |
| Traces: events | EnvironmentPromotionService/PromotionRequested, ReleaseService/ReleaseReady, ReleaseService/ReleaseWithdrawn, EnvironmentService/EnvironmentStateChanged |
| Traces: steps | delivery-run/request-promotion |
| Traces: descriptors | release-manifest-v1, ack-v1 |
| Traces: adrs | ADR-0012, ADR-0014, ADR-0015 |
| Traces: requirements | FR-08, FUX-05 |
| Traces: scenarios | SCN-EnvironmentPromotionService-003, SCN-EnvironmentPromotionService-006, SCN-EnvironmentPromotionService-007 |
| Relates: screens | promotions |
| Depends on | feature:release-service, feature:environment-service, feature:contracts-package |
| Sources | model/services/devops-gitops/EnvironmentPromotionService.yaml, model/services/devops-gitops/ReleaseService.yaml, model/workflows/delivery-run.yaml, docs/reference/schemas/release-manifest.schema.json, docs/planes/execution/delivery-engine/services/environment-promotion-service/index.md#apis |
Tasks
| Task | Kind | Expected output | Repository |
|---|---|---|---|
AIFACTORY-TASK-5262 RequestPromotion and Promotions.Request with idempotency, the release and environment records and the refusals |
implementation | RequestPromotion and Promotions.Request write the Promotion in state Requested with the project of the release, requestedBy, the optional runId and stepRunId, the strategy and the environment class, together with the PromotionRequested outbox record in one transaction, and answer 202 with the location or ack-v1; the inbox handlers EnablePromotion and BlockPromotion keep the ready and withdrawn releases by tenant and project, idempotently on the event id, and GateEnvironment keeps the last state and class of each environment by tenant; RequestPromotion answers 409 for a reused key with another body, 422 for a missing Idempotency-Key, release, environment or strategy, an unknown strategy or a class off the promotion path, 412 for a withdrawn release, 404 alike for a release or an environment not recorded in the tenant of the caller, and 403 for a missing scope or role; Promotions.Request admits a workload token only with the service scope factory.delivery.promote, reads the forwarded tenant and project and the delegatedUserId of the call metadata only under it, keeps the delegated user as requestedBy and the runId and stepRunId of the request on the promotion (D141), and answers UNAUTHENTICATED, PERMISSION_DENIED, INVALID_ARGUMENT, NOT_FOUND or FAILED_PRECONDITION; no refusal writes anything; a repeat under the same Idempotency-Key, or for the same run, release and target environment, returns the first result. | ConnectSoft.AI.SoftwareFactory.EnvironmentPromotionService |
AIFACTORY-TASK-5263 Fixture release and environment events and the token matrix of the request suite |
fixture | The acceptance suite holds fixture events ReleaseReady and ReleaseWithdrawn of two tenants and fixture events EnvironmentStateChanged announcing environments of the classes Sandbox, Development, Staging and Production in both tenants, built from the event types of the pinned contracts package under the run event envelope, user tokens with and without factory.delivery.promote and with and without a role in the project of the release, and workload tokens of the deploy-environment caller with and without factory.delivery.promote, the service scope of Promotions.Request (D135), whose calls forward the requester of the run as delegatedUserId and name the runId and stepRunId of the requesting step (D141). | ConnectSoft.AI.SoftwareFactory.EnvironmentPromotionService |
AIFACTORY-TASK-5264 Verify request-a-promotion through the acceptance suite |
verification | Run dotnet test -c Release --filter "Category=Acceptance&(Scenario=SCN-EnvironmentPromotionService-003\|Scenario=SCN-EnvironmentPromotionService-006\|Scenario=SCN-EnvironmentPromotionService-007)"; a zero-match filter counts as a failure; the tests prove AC1 to AC4 of AIFACTORY-US-1311: the accepted request and its idempotent repeat, the 409, 422, 412, 404 and 403 refusals without a write, the 404 that answers a release or an environment of another tenant like an unknown one, the gRPC acknowledgement, its repeat keyed on run, release and target environment and its statuses, and the publication and payload of PromotionRequested; consumer handling is proven by the suites of the consumers. |
ConnectSoft.AI.SoftwareFactory.EnvironmentPromotionService |
AIFACTORY-US-1312: Evaluate the gates of a promotion in order and hand the desired state to provisioning once they pass¶
behavior · persona operator
As an operator, I want every promotion to pass the release resolution, policy, the prior environment where it applies, the environment state and evaluation evidence before it is deployed, so that a release reaches an environment only on recorded evidence, and a failing gate stops it with the gate named.
The worker GateEvaluator starts on PromotionRequested, moves the promotion from Requested to GatesEvaluating (trigger Start) and evaluates the gates in order, recording each in PromotionGates with its outcome, its evidence reference and the time, once per gate kind under the idempotency key promotionId plus gateKind. Every gate evaluation first reads the withdrawn mark that BlockPromotion keeps, so a release withdrawn before or during the evaluation fails the gate being evaluated with the withdrawal as its evidence. PipelineResults resolves the release through ReleaseService/Releases.GetRelease under the tenant of the promotion and records the reply as its evidence; it fails when the release is not found. The reply is release-manifest-v1, the manifest of an asset release, which carries no pipeline-run outcome, and ReleaseService assembles a product release only from a succeeded pipeline run, so this PBI asserts no failing branch on the outcome of a pipeline run; the member that names the pipeline run of a product release is reported as an open point. Policy asks PolicyEngineService/Policy.Decide with a policy-decision-request-v1 of the action kind promotion, which pairs with the domain Deployment, with the release as action.target, the class of the target environment that GateEnvironment kept as action.environment, the environment as environmentId, the project of the release, the run when the promotion names one, and the requester of the promotion as the subject (D140). For a promotion that an Operator or a Workspace admin requested through RequestPromotion the subject is that user; for one that the deploy-environment tool requested through Promotions.Request it is the workload with the requester of the run as delegatedUserId, forwarded in the call metadata beside the tenant and the project (AIFACTORY-US-1311). The platform rule for the action kind promotion then checks the role of the delegated user, the decision records the workload as the actor, and a workload subject without a delegated user is denied (D127, D141). The platform bundle allows a promotion for a subject who is Operator or Workspace admin of the project, and the seeded tenant bundle answers allow-with-approval with obligations.approvalClass production for the class production; that answer is met by the one production approval of the approval gate (AIFACTORY-US-1313), which carries the policy revision and the approver rule of the decision, and never by a second approval (D133, D140). The gate records the decision id as its evidence, passes on allow and, for production, on allow-with-approval, and fails on deny and prohibited; a subject who is neither Operator nor Workspace admin of the project matches no rule and is denied, because an action no rule matches is denied (D127). PriorEnvironment applies to a production promotion, as the invariant of the model states it: it passes when a promotion of the same release completed in the prior class of Delivery:Promotions:PromotionPath for the project, or when the policy decision allows a hotfix path with evidence, and fails otherwise. For a promotion of any other class, the first class of the path, development, among them, the gate is not evaluated and no row is written for it, the reading of D135 that the prior-environment gate applies to production only. EnvironmentReady reads the last state and class that the inbox handler GateEnvironment kept from EnvironmentService/EnvironmentStateChanged, and passes when the environment is Active. EvaluationEvidence applies where the release carries agent-generated assets and passes on the evaluation verdict of the release manifest when it is passed or waived; for any other release it is not evaluated. The first failing gate ends the evaluation: the promotion moves to Rejected (trigger GateFailed) with the gate named, and no later gate runs. ReleaseService and PolicyEngineService are required and fail fast; the worker attempts a gate 3 times, 30 seconds apart, and when the attempts are exhausted the gate is recorded failed with the unreachable dependency named and the promotion is Rejected. When every gate passes and the class is production, the approval is requested as part of the gate evaluation (AIFACTORY-US-1313), except for a rollback promotion, whose rollbackOfPromotionId names the promotion it rolls back: it evaluates the same gates, skips the approval gate and hands off like any promotion (D135, AIFACTORY-US-1315). For any other class, and for a rollback promotion, the promotion moves to Approved (trigger GatesPassedNoApproval); the service then builds the desired-state specification from the release and the environment, records desiredStateRef and moves to Deploying (trigger DesiredStateHandedOff), writing PromotionApproved with strategy and desiredStateRef in the same transaction: that event is the hand-off to IaCProvisioningService, which deploys from it in its own PBI. The moves to Approved and to Deploying are committed in one transaction, so no promotion rests in Approved when ReleaseService/ReleaseWithdrawn arrives, and a promotion that is Deploying or later keeps going, because a withdrawal revokes nothing already deployed. A withdrawal that arrives while the promotion is AwaitingApproval is handled with the approval (AIFACTORY-US-1313). The service never touches infrastructure. The Policy gate is proven against the published container image of PolicyEngineService of feature policy-engine-service with the seeded platform and tenant bundles, so the decisions it records are those of the bundles in force; a fake of the decision is kept only for a dependency that stops answering and for the hotfix allowance, for which no seeded rule exists. The class of the target environment travels in action.environment, the environment id in environmentId and the release in action.target, and the delegated user of a tool request in subject.delegatedUserId, as docs/reference/schemas/policy-decision-request.schema.json states (D141). A Rejected promotion publishes none of the five events of the model, which is reported as a correction.
Acceptance criteria
| AC1 | Given a Requested promotion into a staging or a development environment, requested by an Operator or a Workspace admin of the project, whose release resolves through ReleaseService/Releases.GetRelease and that targets an environment announced Active by EnvironmentService/EnvironmentStateChanged, when GateEvaluator handles EnvironmentPromotionService/PromotionRequested, then PolicyEngineService/Policy.Decide of the deployed PolicyEngineService with its seeded bundles is asked once with the action kind promotion, the release in action.target, the class of the target environment in action.environment, the environment id in environmentId and the requester as subject, or, for a promotion requested through EnvironmentPromotionService/Promotions.Request, the workload with the requester of the run as delegatedUserId (D141), and answers allow in the domain Deployment, the EnvironmentPromotionService/Promotion moves through GatesEvaluating to Approved and Deploying, each evaluated gate is recorded passed with its evidence reference, the Policy gate with the decision id, PriorEnvironment is not evaluated and has no row, desiredStateRef is recorded, and EnvironmentPromotionService/PromotionApproved is written in the transaction of the move to Deploying (SCN-EnvironmentPromotionService-008, D140). |
| AC2 | Given a production promotion whose other gates pass, when the Policy gate and PriorEnvironment are evaluated, then PolicyEngineService/Policy.Decide answers allow-with-approval with obligations.approvalClass production under the seeded tenant bundle, the Policy gate is recorded passed with that decision id, PriorEnvironment passes when a promotion of the same release completed in staging, the prior class of Delivery:Promotions:PromotionPath, for the project, or when a decision allows a hotfix path with evidence, and the one approval of AIFACTORY-US-1313 is then requested with the policy revision and the approver rule of that decision and no second approval; given neither for PriorEnvironment, then the gate is recorded failed and the promotion moves to Rejected (model/services/devops-gitops/EnvironmentPromotionService.yaml, model/services/governance/PolicyEngineService.yaml, D133, D140). |
| AC3 | Given a release that ReleaseService/Releases.GetRelease does not find, a requester who is neither Operator nor Workspace admin of the project, or a workload request whose delegated user holds neither role, whose promotion PolicyEngineService/Policy.Decide denies because no rule matches (D141), an environment announced Frozen or Retired, a release with agent-generated assets whose evaluation verdict is missing or failed, or a release that ReleaseService/ReleaseWithdrawn marked withdrawn before or during the evaluation, when the gates are evaluated, then the promotion moves to Rejected with the first failing gate named, no later gate is evaluated and no EnvironmentPromotionService/PromotionApproved is written; given the withdrawal arrives for a Deploying promotion, then its state is unchanged (model/services/devops-gitops/EnvironmentPromotionService.yaml). |
| AC4 | Given ReleaseService/Releases.GetRelease or PolicyEngineService/Policy.Decide does not answer, when a gate is evaluated, then it is attempted 3 times, 30 seconds apart; when the attempts are exhausted the gate is recorded failed with the unreachable dependency named and the promotion is Rejected; a duplicate trigger for the same promotion and gate kind records no second outcome (model/services/devops-gitops/EnvironmentPromotionService.yaml). |
| AC5 | Given the desired state was handed off, when the outbox dispatcher publishes EnvironmentPromotionService/PromotionApproved on releases.promotions.v1.promotion-approved, then the event is sent under the run event envelope with promotionId, tenantId, releaseId, environmentId, strategy, desiredStateRef and, for a production promotion only, approvalId, and a transport outage is retried with backoff so the event is neither lost nor duplicated under its event id (SCN-EnvironmentPromotionService-008, ADR-0012). |
| Traces: services | EnvironmentPromotionService, ReleaseService, PolicyEngineService, EnvironmentService, IaCProvisioningService |
| Traces: aggregates | EnvironmentPromotionService/Promotion |
| Traces: apis | ReleaseService/Releases.GetRelease, PolicyEngineService/Policy.Decide, EnvironmentPromotionService/Promotions.Request |
| Traces: events | EnvironmentPromotionService/PromotionRequested, EnvironmentPromotionService/PromotionApproved, EnvironmentService/EnvironmentStateChanged, ReleaseService/ReleaseWithdrawn |
| Traces: descriptors | policy-decision-request-v1, policy-decision-v1, release-manifest-v1 |
| Traces: adrs | ADR-0004, ADR-0012, ADR-0014 |
| Traces: requirements | FR-08, XL-04 |
| Traces: scenarios | SCN-EnvironmentPromotionService-008 |
| Relates: screens | promotions |
| Depends on | AIFACTORY-US-1311, feature:release-service, feature:policy-engine-service, feature:environment-service, feature:ia-cprovisioning-service |
| Sources | model/services/devops-gitops/EnvironmentPromotionService.yaml, docs/planes/execution/delivery-engine/services/environment-promotion-service/index.md#workers-and-jobs, docs/planes/execution/delivery-engine/services/environment-promotion-service/index.md#sagas-and-long-running-flows, model/services/governance/PolicyEngineService.yaml, docs/reference/schemas/policy-decision-request.schema.json, docs/reference/schemas/policy-decision.schema.json, docs/reference/schemas/release-manifest.schema.json |
Tasks
| Task | Kind | Expected output | Repository |
|---|---|---|---|
AIFACTORY-TASK-323 GateEvaluator with the gates per environment class in order and the evidence of each gate |
implementation | GateEvaluator moves a Requested promotion to GatesEvaluating, reads the withdrawn mark before each gate, evaluates PipelineResults by resolving the release through Releases.GetRelease, Policy through Policy.Decide with a policy-decision-request-v1 of the action kind promotion, the release as action.target, the class of the target environment as action.environment, the environment id as environmentId, the project, the run and the requester as subject, a workload request carrying the requester of the run as delegatedUserId, whose role the platform rule checks while the workload is recorded as the actor (D141), passing on allow and for production on allow-with-approval, whose decision id, policy revision and approver rule it keeps for the approval of AIFACTORY-TASK-324, and failing on deny or prohibited (D140), PriorEnvironment for a production promotion only against the promotion path or a hotfix allowance of the policy decision, EnvironmentReady from the state kept by GateEnvironment and EvaluationEvidence on the evaluation verdict of the release manifest where the release carries agent-generated assets, records each evaluated outcome in PromotionGates once per gate kind, rejects on the first failing gate with the gate named, attempts a gate 3 times 30 seconds apart and after the last attempt records the gate failed with the unreachable dependency named; GateEnvironment keeps the last announced state and class of each environment and BlockPromotion the withdrawn mark of each release, idempotently on the event id. | ConnectSoft.AI.SoftwareFactory.EnvironmentPromotionService |
AIFACTORY-TASK-5265 Desired-state specification and the hand-off through PromotionApproved |
implementation | For a promotion that passed its gates without an approval, or whose approval was granted, the service builds the desired-state specification from the release and the environment, records desiredStateRef, moves the promotion through Approved to Deploying in one transaction and writes PromotionApproved with strategy, desiredStateRef and, for production, approvalId in that transaction; no call reaches infrastructure. | ConnectSoft.AI.SoftwareFactory.EnvironmentPromotionService |
AIFACTORY-TASK-5266 PolicyEngineService with its seeded bundles, fakes of Releases.GetRelease and Policy.Decide and fixture EnvironmentStateChanged and ReleaseWithdrawn events |
fixture | The acceptance suite runs the pinned container image of PolicyEngineService with its seeded platform and tenant bundles for the decisions of the Policy gate, with requesters who are Operator, Workspace admin and neither of the project and workload requests that name as delegatedUserId a requester of the run who is Operator, Workspace admin or neither (D141), and holds a fake Releases.GetRelease that answers a release-manifest-v1 with or without agent-generated assets and with a passed, failed or missing evaluation verdict, answers NOT_FOUND and can stop answering, a fake Policy.Decide used only for a hotfix allowance and for a dependency that stops answering, fixture EnvironmentStateChanged events announcing an environment Active, Frozen and Retired with its class, and fixture ReleaseWithdrawn events delivered before the evaluation, between two gates and after the hand-off; no fake carries a pipeline-run member the contract lacks. | ConnectSoft.AI.SoftwareFactory.EnvironmentPromotionService |
AIFACTORY-TASK-5267 Verify the gates and the hand-off through the acceptance suite |
verification | Run dotnet test -c Release --filter "Category=Acceptance&Scenario=SCN-EnvironmentPromotionService-008"; a zero-match filter counts as a failure; the tests prove AC1 to AC5 of AIFACTORY-US-1312, and the tests of AIFACTORY-US-1313 that the filter also selects are claimed by AIFACTORY-TASK-5268: the gates in order with their evidence for staging and development, the Policy gate asked with the action kind promotion and the class of the target environment and answered by the seeded bundles allow for an Operator or a Workspace admin, directly or as the delegated user of a workload request, allow-with-approval for production and deny for any other requester (D141), PriorEnvironment for production with the completed prior class and with the hotfix path, each failing gate and the withdrawn release, the exhausted attempts with the dependency named, the duplicate trigger, and the publication and payload of PromotionApproved; the deploy that IaCProvisioningService runs from it is proven by its own suite. |
ConnectSoft.AI.SoftwareFactory.EnvironmentPromotionService |
AIFACTORY-US-1313: A production promotion waits for the one approval bound to its release id and environment¶
behavior · persona reviewer
As a reviewer of the project, I want to decide once on a production promotion, bound to the exact release and the environment, and never on a run I requested, so that production changes only on a decision someone other than the requester of the run took, and no second approval of the same deployment is asked.
A person gives one production approval, and it is the gate of this service, bound to the release id and the environment (D133). The approval is requested as part of the gate evaluation: when every other gate of a production promotion passed, GateEvaluator, still in GatesEvaluating, calls RunControlService/RunControl.RequestApproval under the service identity of the service with an approval-request-v1 of action class production and proposal kind release whose subject is the kind promotion with the promotion id, whose requestingService is EnvironmentPromotionService and whose runId names the run that requested the promotion when there is one (D135). The request carries as policyRevision and approverRule the revision and the obligations.approverRule of the allow-with-approval decision that the Policy gate recorded for the class production (AIFACTORY-US-1312), so this approval is the approval that decision asks for and no second one is opened (D133, D140). The schema has no member for the environment, so the proposal hash is computed over the hash of the release manifest and the environment id, and the proposal reference names the release id and the environment id; the decision then authorizes exactly that release in that environment, and a member that names the environment on its own is reported as an open point. requestedBy is, as the schema defines it, the requester of the run when the promotion names one, which RunControlService knows from the run and against which it checks separation of duties, and the Operator who requested the promotion when it names no run (ADR-0015, D135); the service keeps the requester of the promotion, a workload identity for a request of the deploy-environment tool, in its own requestedBy and never puts a workload identity in the approval request. Only when the approvalId is returned does the promotion move to AwaitingApproval (trigger GatesPassedApprovalRequired) with that approvalId recorded. RunControlService resolves the approver rule, refuses a decision by the requester of the run and expires the request in its own PBIs. The workflow steps delivery-run/approve-production and release/approve-production wait on this approval and the deploy-environment tool presents its id (D133, D135); no other production approval is asked for the same deployment, and IaCProvisioningService applies the desired state of an approved promotion without a second one. RunControlService is required and fails fast: the worker attempts the request 3 times, 30 seconds apart, and when the attempts are exhausted the Approval gate is recorded failed with RunControlService named and the promotion moves to Rejected (trigger GateFailed) without an approval id. The inbox handler ApplyApproval takes RunControlService/ApprovalDecided, idempotently on the event id, and applies a decision only when its subjectKind is promotion and its subjectId, approvalId and tenantId are those the promotion keeps; any other decision changes nothing. A rollback promotion requests no approval (D135). Approved records the Approval gate passed and moves the promotion to Approved (trigger ApprovalGranted), after which the hand-off of AIFACTORY-US-1312 writes PromotionApproved with that approvalId. Rejected and Expired record the Approval gate failed and move it to Rejected (trigger ApprovalRejectedOrExpired), and a new request binds a new approval (failure mode Approval expires). When the approval rule of the run says re-request on expiry, RunControlService opens a new request with a new approvalId that the Rejected promotion does not keep, so a decision on it changes nothing; whether a re-requested approval should keep the promotion waiting is reported as an open point. ChangesRequested and Stale keep the promotion AwaitingApproval with the decision recorded, because the proposal hash of a promotion does not change and a new request is the act of the run. Cancelled, which RunControlService publishes when the run is cancelled or fails, has no modelled transition out of AwaitingApproval: the promotion stays AwaitingApproval with the cancellation recorded, and the missing transition is reported as an open point. A release that ReleaseService/ReleaseWithdrawn withdraws while its promotion is AwaitingApproval has no modelled transition either: the withdrawal is recorded, an Approved decision that arrives afterwards records the Approval gate passed and hands nothing off, the promotion stays AwaitingApproval, and the missing transition is reported. A Reviewer lists the waiting promotions with the promotions waiting command of the command-line client, which reads EnvironmentPromotionService/ListPromotions through the typed client of DeliveryHost that feature delivery-host publishes with the conventions of feature typed-gateway-clients (D140), with its own token whose audience is that gateway (ADR-0015 amendment D114), and decides through the existing approve and reject commands of feature command-line-client-commands, which call RunControlService/DecideApproval. A production promotion that an Operator requests without a run is approved the same way, its subject being the promotion and its request carrying no runId (D135).
Acceptance criteria
| AC1 | Given a production promotion requested for a run whose other gates all passed, when the gate evaluation reaches the approval, then RunControlService/RunControl.RequestApproval is called once from GatesEvaluating under the service identity of the service with action class production, proposal kind release, the subject kind promotion with the promotion id, requestingService EnvironmentPromotionService, a proposal hash over the hash of the release manifest and the environment id, a reference naming the release id and the environment id, the policyRevision and approverRule of the allow-with-approval decision of the Policy gate, the run as runId and no workload identity in requestedBy; given an Operator requested the promotion without a run, then the request carries no runId and names the Operator in requestedBy; and only when the approvalId is returned does the EnvironmentPromotionService/Promotion move to AwaitingApproval with that approvalId recorded (SCN-EnvironmentPromotionService-008, ADR-0015). |
| AC2 | Given an AwaitingApproval promotion, when RunControlService/ApprovalDecided arrives Approved with the subject kind promotion and the subjectId, approvalId and tenantId the promotion keeps, then the Approval gate is recorded passed and the promotion moves to Approved and on to Deploying with EnvironmentPromotionService/PromotionApproved carrying that approvalId; given it arrives Rejected or Expired, then the Approval gate is recorded failed, the promotion moves to Rejected and nothing is handed off; given it names another subject kind, promotion, approval or tenant, or is redelivered, then nothing changes (SCN-EnvironmentPromotionService-008). |
| AC3 | Given an AwaitingApproval promotion, when RunControlService/ApprovalDecided arrives ChangesRequested, Stale or Cancelled, then the promotion stays AwaitingApproval with the decision recorded and nothing is handed off; given ReleaseService/ReleaseWithdrawn withdrew its release while it waited, when an Approved decision arrives, then the Approval gate is recorded passed, the promotion stays AwaitingApproval with the withdrawal recorded and no EnvironmentPromotionService/PromotionApproved is written (model/services/devops-gitops/EnvironmentPromotionService.yaml). |
| AC4 | Given RunControlService/RunControl.RequestApproval does not answer, when the approval is requested, then it is attempted 3 times, 30 seconds apart, and when the attempts are exhausted the Approval gate is recorded failed with RunControlService named, the promotion moves from GatesEvaluating to Rejected through GateFailed and no approval id is recorded; given a non-production promotion or a rollback promotion, then no approval is requested (SCN-EnvironmentPromotionService-008, D135). |
| AC5 | Given a Reviewer with a role in the project and promotions waiting for approval, when the promotions waiting command of the command-line client runs, then it reads EnvironmentPromotionService/ListPromotions filtered by state AwaitingApproval through the typed client of DeliveryHost of feature delivery-host with a token whose audience is that gateway and lists each promotion with its release, environment and approvalId, and the decision is taken by the existing approve and reject commands through RunControlService/DecideApproval naming that approvalId, so the steps delivery-run/approve-production and release/approve-production and the promotion settle on the same approval (ADR-0015, D133). |
| Traces: services | EnvironmentPromotionService, RunControlService, ReleaseService |
| Traces: aggregates | EnvironmentPromotionService/Promotion |
| Traces: apis | RunControlService/RunControl.RequestApproval, RunControlService/DecideApproval, EnvironmentPromotionService/ListPromotions |
| Traces: events | RunControlService/ApprovalDecided, EnvironmentPromotionService/PromotionApproved, ReleaseService/ReleaseWithdrawn |
| Traces: steps | delivery-run/approve-production, release/approve-production |
| Traces: descriptors | approval-request-v1, approval-ref-v1 |
| Traces: adrs | ADR-0014, ADR-0015 |
| Traces: requirements | FUX-05, XL-04 |
| Traces: scenarios | SCN-EnvironmentPromotionService-008 |
| Relates: screens | promotions, approvals-list |
| Depends on | AIFACTORY-US-1312, feature:run-control-service, feature:release-service, feature:command-line-client-commands, feature:typed-gateway-clients, feature:delivery-host |
| Sources | model/services/devops-gitops/EnvironmentPromotionService.yaml, model/services/control-plane/RunControlService.yaml, model/workflows/delivery-run.yaml, docs/reference/schemas/approval.schema.json |
Tasks
| Task | Kind | Expected output | Repository |
|---|---|---|---|
AIFACTORY-TASK-324 Production approval requested during the gate evaluation, bound to the release id and the environment, and the ApplyApproval handler |
implementation | For a production promotion other than a rollback promotion whose other gates passed, GateEvaluator calls RunControl.RequestApproval once from GatesEvaluating under the service identity with approval-request-v1 of action class production and proposal kind release, the subject kind promotion with the promotion id, requestingService EnvironmentPromotionService, a proposal hash over the hash of the release manifest and the environment id, a reference naming both, the policyRevision and approverRule of the allow-with-approval decision of the Policy gate, the run as runId when the promotion names one and no workload identity in requestedBy, and moves the promotion to AwaitingApproval only when the approvalId is returned; after 3 attempts 30 seconds apart without an answer it records the Approval gate failed with RunControlService named and rejects through GateFailed; ApplyApproval applies ApprovalDecided only for the subject kind promotion and the subjectId, approvalId and tenantId the promotion keeps, records the Approval gate passed on Approved and failed on Rejected or Expired, moves the promotion to Approved or Rejected, keeps it AwaitingApproval with the decision recorded on ChangesRequested, Stale and Cancelled, and hands nothing off for a release withdrawn while it waited, idempotently on the event id. | ConnectSoft.AI.SoftwareFactory.EnvironmentPromotionService |
AIFACTORY-TASK-326 The promotions waiting command of the command-line client |
implementation | The client lists the promotions waiting for approval with release, environment and approvalId through EnvironmentPromotionService/ListPromotions filtered by state AwaitingApproval, called through the pinned typed client of DeliveryHost that feature delivery-host publishes (D140) with a token whose audience is that gateway; the decision is left to the existing approve and reject commands of feature command-line-client-commands, and no second decision command is written. | ConnectSoft.AI.SoftwareFactory.Cli |
AIFACTORY-TASK-5268 Verify the production approval through the acceptance suite |
verification | Run dotnet test -c Release --filter "Category=Acceptance&(Feature=ProductionApproval\|Scenario=SCN-EnvironmentPromotionService-008)"; a zero-match filter counts as a failure; with a fake RunControl.RequestApproval that records the request and can stop answering and fixture ApprovalDecided events Approved, Rejected, Expired, ChangesRequested, Stale and Cancelled, and for another subject kind, another promotion, another approval and another tenant, and promotions with and without a run and a rollback promotion, the tests prove AC1 to AC4 of AIFACTORY-US-1313; the refusal of a decision by the requester of the run is proven by the suite of RunControlService and AC5 by AIFACTORY-TASK-5289. |
ConnectSoft.AI.SoftwareFactory.EnvironmentPromotionService |
AIFACTORY-TASK-5289 Verify the promotions waiting command through the client acceptance suite |
verification | Run dotnet test -c Release --no-build on the client solution against a fake of the DeliveryHost route of EnvironmentPromotionService/ListPromotions; a run that discovers no test counts as a failure; the tests prove AC5 of AIFACTORY-US-1313: the command sends the state filter AwaitingApproval with a token whose audience is DeliveryHost, lists release, environment and approvalId of each promotion, exits with a non-zero code on 401, 403 and 503, and the decision runs through the existing approve and reject commands. |
ConnectSoft.AI.SoftwareFactory.Cli |
AIFACTORY-US-1314: Follow the deployment, verify the release in the environment and record the automatic rollback when verification fails¶
behavior · persona operator
As an operator, I want a deployed release verified in its environment before it counts as current, and its promotion rolled back with evidence when verification fails, so that the current release of an environment is always one that passed verification, and a failed verification never leaves a promotion waiting.
IaCProvisioningService deploys the desired state that PromotionApproved handed over and reports through events that name the promotion. The inbox handler AttachProvisioningPlan attaches the plan of IaCProvisioningService/ProvisioningPlanned to the promotion as evidence the approval covers, without a state change. IaCProvisioningService/ProvisioningFailed is taken by FailPromotion: the promotion moves from Deploying to Failed (trigger ProvisioningFailed) with the reason of provisioning, the environment is unchanged, and PromotionFailed is written with rolledBack false. IaCProvisioningService/ProvisioningApplied is taken by StartVerification: the promotion moves from Deploying to Verifying (trigger ProvisioningApplied), and the worker Verifier, triggered by the same event under the idempotency key promotionId and attempted 3 times, 60 seconds apart, runs the health checks and the smoke suite of the pipeline and observes the environment for Delivery:Promotions:VerificationWindowMinutes. The inbox handler CompleteVerification reads RuntimeEnvironmentService/ObservedStateChanged for the environment: the verification passes when the observed current release is the release of the promotion, the observation is not stale and the checks passed. The SLO window is checked through SloService, an optional dependency that degrades and is delivered in I4, so in this increment it is recorded as not evaluated and does not fail the verification. A passed verification moves the promotion to Completed (trigger VerificationPassed) with completedAt and the release that was current before as previousReleaseId, writes PromotionCompleted in the same transaction and records connectsoft.factory.delivery.promotion_lead_time; the release is then the current release of the environment. A verification fails when a check fails within the window, when the attempts of the Verifier are exhausted because the health checks or the smoke suite cannot be reached, or when the window expires without a fresh observation of the release, a stale observation included, and the reason is recorded. With Delivery:Promotions:AutoRollbackOnVerificationFailure at its default true and a previous release, a failed verification records the rollback evidence with the reason and the previous release as its target and opens a rollback promotion: a new promotion of the previous release into the same environment whose rollbackOfPromotionId names the failed promotion, written with PromotionRequested in the same transaction, and connectsoft.factory.delivery.rollbacks counts it as automatic (failure mode Verification fails, D135). The rollback promotion evaluates the gates of AIFACTORY-US-1312, skips the approval gate and hands its desired state to IaCProvisioningService through PromotionApproved like any promotion, so the previous release is deployed and verified by the same path. When the rollback promotion completes, the failed promotion moves from Verifying to RolledBack (trigger VerificationFailedAutoRollback) and PromotionFailed with rolledBack true and RollbackCompleted with the previous release as restoredReleaseId and the rollback promotion as rollbackPromotionId are written in the transaction of that completion (D135). Until then the failed promotion stays Verifying with the failure recorded; a rollback promotion that is Rejected or Failed has no modelled transition for the promotion it rolls back, which then stays Verifying with that outcome recorded, and the missing transition is reported as an open point. The model has no transition out of Verifying when the option is false or when there is no previous release, the first promotion into an environment; the promotion then stays Verifying with the failure and its reason recorded, nothing is published, and both cases are reported as open points. An event for a promotion in another state changes nothing. Both events carry the optional runId and stepRunId the promotion keeps from the requesting step, and neither carries them for a promotion no run requested, a rollback promotion among them (D141). RunControlService settles the step of a run that waits for the promotion from PromotionCompleted and PromotionFailed through its handler SettleWaitingStep, which AIFACTORY-US-1621 delivers (D140).
Acceptance criteria
| AC1 | Given a Deploying promotion, when IaCProvisioningService/ProvisioningApplied names it and the Verifier health and smoke checks pass and RuntimeEnvironmentService/ObservedStateChanged shows its release current and not stale within the window, then the EnvironmentPromotionService/Promotion moves through Verifying to Completed with previousReleaseId and completedAt, EnvironmentPromotionService/PromotionCompleted is written in the same transaction, the SLO window is recorded as not evaluated, and connectsoft.factory.delivery.promotion_lead_time is recorded (SCN-EnvironmentPromotionService-009). |
| AC2 | Given a Deploying promotion, when IaCProvisioningService/ProvisioningFailed names it, then it moves to Failed with the reason of provisioning and EnvironmentPromotionService/PromotionFailed is written with rolledBack false; given IaCProvisioningService/ProvisioningPlanned names it, then the plan is attached as evidence and the state is unchanged; a redelivered event changes nothing (SCN-EnvironmentPromotionService-010). |
| AC3 | Given a Verifying promotion with a previous release and Delivery:Promotions:AutoRollbackOnVerificationFailure true, when a check fails within the window, the 3 attempts of the Verifier are exhausted without reaching the checks, or the window expires without a fresh observation of the release, then its rollback evidence names the reason and the previous release, a rollback promotion of the previous release whose rollbackOfPromotionId names it is opened with EnvironmentPromotionService/PromotionRequested, requests no approval and hands off through EnvironmentPromotionService/PromotionApproved, and connectsoft.factory.delivery.rollbacks counts an automatic rollback; when the rollback promotion completes, the failed promotion moves from Verifying to RolledBack and EnvironmentPromotionService/PromotionFailed with rolledBack true and EnvironmentPromotionService/RollbackCompleted with restoredReleaseId and rollbackPromotionId are written in that transaction; before it completes, or when it ends Rejected or Failed, the failed promotion stays Verifying (SCN-EnvironmentPromotionService-010, D135). |
| AC4 | Given a Verifying promotion whose verification fails while Delivery:Promotions:AutoRollbackOnVerificationFailure is false, or the first promotion into its environment without a previous release, when the failure is recorded, then the promotion stays Verifying with the failure and its reason recorded and nothing is published, the missing transition being an open point of model/services/devops-gitops/EnvironmentPromotionService.yaml. |
| AC5 | Given the promotion completed or failed, when the outbox dispatcher publishes EnvironmentPromotionService/PromotionCompleted on releases.promotions.v1.promotion-completed and EnvironmentPromotionService/PromotionFailed on releases.promotions.v1.promotion-failed, then each is sent under the run event envelope, the first with promotionId, tenantId, projectId, releaseId, environmentId, environmentClass and previousReleaseId, the second with promotionId, tenantId, releaseId, environmentId, reason and rolledBack, both with the runId and the stepRunId of the requesting step when a run requested the promotion and without them otherwise (D141), and a transport outage is retried with backoff so neither is lost nor duplicated under its event id (SCN-EnvironmentPromotionService-009, SCN-EnvironmentPromotionService-010, ADR-0012). |
| Traces: services | EnvironmentPromotionService, IaCProvisioningService, RuntimeEnvironmentService |
| Traces: aggregates | EnvironmentPromotionService/Promotion |
| Traces: events | EnvironmentPromotionService/PromotionCompleted, EnvironmentPromotionService/PromotionFailed, EnvironmentPromotionService/RollbackCompleted, EnvironmentPromotionService/PromotionRequested, EnvironmentPromotionService/PromotionApproved, IaCProvisioningService/ProvisioningPlanned, IaCProvisioningService/ProvisioningApplied, IaCProvisioningService/ProvisioningFailed, RuntimeEnvironmentService/ObservedStateChanged |
| Traces: adrs | ADR-0004, ADR-0012, ADR-0014 |
| Traces: requirements | FR-08, NFR-08, NFR-09 |
| Traces: scenarios | SCN-EnvironmentPromotionService-009, SCN-EnvironmentPromotionService-010 |
| Relates: screens | promotions, environment-board |
| Depends on | AIFACTORY-US-1312, feature:ia-cprovisioning-service, feature:runtime-environment-service |
| Sources | model/services/devops-gitops/EnvironmentPromotionService.yaml, model/services/runtime-cloud/IaCProvisioningService.yaml, model/services/runtime-cloud/RuntimeEnvironmentService.yaml, docs/planes/execution/delivery-engine/services/environment-promotion-service/index.md#failure-and-recovery |
Tasks
| Task | Kind | Expected output | Repository |
|---|---|---|---|
AIFACTORY-TASK-325 Deployment reports, the Verifier, its failure branches and the automatic rollback record |
implementation | AttachProvisioningPlan, FailPromotion, StartVerification and CompleteVerification handle their events for the promotion they name, idempotently on the event id; the Verifier runs the health checks and the smoke suite within VerificationWindowMinutes, attempted 3 times 60 seconds apart, and records the SLO window as not evaluated; a passed verification completes the promotion with previousReleaseId and PromotionCompleted, a provisioning failure fails it with PromotionFailed, both echoing the runId and stepRunId the promotion keeps and carrying none when no run requested it (D141), and a failed check, exhausted attempts or a window that expires without a fresh observation count as a failed verification with the reason recorded, which with AutoRollbackOnVerificationFailure true and a previous release records the rollback evidence and opens a rollback promotion of the previous release with rollbackOfPromotionId and PromotionRequested in one transaction; completing a rollback promotion moves the promotion it rolls back from Verifying to RolledBack and writes PromotionFailed with rolledBack true and RollbackCompleted with restoredReleaseId and rollbackPromotionId in the transaction of the completion; otherwise the promotion stays Verifying with the failure recorded and nothing published. | ConnectSoft.AI.SoftwareFactory.EnvironmentPromotionService |
AIFACTORY-TASK-5269 Fixture provisioning and observed-state events, fakes of the health and smoke checks and a controllable clock |
fixture | The acceptance suite holds fixture events ProvisioningPlanned, ProvisioningApplied and ProvisioningFailed naming a promotion and ObservedStateChanged with the release of the promotion, with another release and stale, built from the event types of the pinned contracts package, fakes of the health checks and the smoke suite that pass, fail or stop answering on demand, and a clock the suite advances past VerificationWindowMinutes. | ConnectSoft.AI.SoftwareFactory.EnvironmentPromotionService |
AIFACTORY-TASK-5270 Verify deployment, verification and the automatic rollback through the acceptance suite |
verification | Run dotnet test -c Release --filter "Category=Acceptance&(Scenario=SCN-EnvironmentPromotionService-009\|Scenario=SCN-EnvironmentPromotionService-010)"; a zero-match filter counts as a failure; the tests prove AC1 to AC5 of AIFACTORY-US-1314, including a failed check, exhausted Verifier attempts and an expired window each opening a rollback promotion, VerificationFailedAutoRollback with RollbackCompleted only once the rollback promotion completes, the failed promotion left Verifying while the rollback promotion runs or after it is Rejected or Failed, the promotion left Verifying with the option false and without a previous release, and the publication and payload of PromotionCompleted and PromotionFailed with and without the runId and stepRunId of a requesting step (D141); consumer handling is proven by the suites of the consumers. |
ConnectSoft.AI.SoftwareFactory.EnvironmentPromotionService |
AIFACTORY-US-1315: An Operator rolls back the current completed promotion of an environment with evidence¶
behavior · persona operator
As an operator, I want to roll an environment back to its previous release when the completed release it runs misbehaves, so that the rollback is recorded with its actor, reason and target release and cannot skip over a newer release.
An Operator whose scope carries factory.delivery.operate and who holds the role Operator in the project of the promotion calls EnvironmentPromotionService/RollbackPromotion for a promotion through DeliveryHost. The Operator holds the approval of a rollback by role, so no approval is asked. Only the Completed promotion whose release is the current release of its environment, with no later Completed promotion in that environment, and that has a previousReleaseId can be rolled back. The rollback is a new promotion (D135): the service records the rollback evidence with the actor, the reason and the previous release as the target, opens a promotion of the previous release into the same environment whose rollbackOfPromotionId names the rolled-back promotion and whose requester is the Operator, writes PromotionRequested in the same transaction, counts connectsoft.factory.delivery.rollbacks as not automatic and answers 202. The rollback promotion evaluates the gates of AIFACTORY-US-1312, skips the approval gate and hands off through PromotionApproved like any promotion, and is deployed and verified by AIFACTORY-US-1314. When it completes, the rolled-back promotion moves from Completed to RolledBack (trigger ManualRollback) and RollbackCompleted is written in the transaction of that completion with the previous release as restoredReleaseId and the rollback promotion as rollbackPromotionId; until then the rolled-back promotion stays Completed with the rollback open, and a rollback promotion that is Rejected or Failed leaves it Completed with that outcome recorded. The operation is naturally idempotent: a repeat on a promotion whose rollback this operation opened, or that it moved to RolledBack, returns 202 and opens nothing, while a promotion that VerificationFailedAutoRollback moved to RolledBack is answered 409. A promotion in any other state, a Completed one without a previous release, and a Completed one whose release is no longer the current release of its environment are refused with 409; a promotion of another tenant is answered 404, the same answer as for an unknown promotion (ADR-0015); a caller without the scope or without the role Operator in the project is refused with 403. No refusal changes a state or publishes anything. RollbackCompleted carries promotionId, tenantId, environmentId, releaseId, restoredReleaseId and rollbackPromotionId, and it is published for an automatic rollback of AIFACTORY-US-1314 the same way; EnvironmentService, StudioBff, FleetInventoryService and AuditService handle it in their own PBIs.
Acceptance criteria
| AC1 | Given a Completed promotion whose release is the current release of its environment and that has a previous release, and an Operator with factory.delivery.operate and the role Operator in its project, when EnvironmentPromotionService/RollbackPromotion is called with a reason, then the response is 202, the actor, the reason and the previous release are recorded as the rollback evidence, a rollback promotion of the previous release whose rollbackOfPromotionId names the EnvironmentPromotionService/Promotion is opened with EnvironmentPromotionService/PromotionRequested and requests no approval, connectsoft.factory.delivery.rollbacks counts a manual rollback, the rolled-back promotion stays Completed until the rollback promotion completes and then moves to RolledBack through ManualRollback with EnvironmentPromotionService/RollbackCompleted written in that transaction, and a repeat returns 202 and opens nothing (SCN-EnvironmentPromotionService-004, D135). |
| AC2 | Given a promotion that is not Completed, a Completed one without a previous release, a Completed one followed by a later Completed promotion in the same environment, a promotion rolled back by VerificationFailedAutoRollback, a promotion of another tenant, or a caller without the scope or the role Operator, when EnvironmentPromotionService/RollbackPromotion is called, then the response is 409, 409, 409, 409, 404 the same as for an unknown promotion, or 403 respectively, with a problem response, no state change and nothing published (SCN-EnvironmentPromotionService-004, ADR-0015). |
| AC3 | Given a rollback promotion that completed, when the outbox dispatcher publishes the EnvironmentPromotionService/RollbackCompleted written for the promotion it rolled back on releases.promotions.v1.rollback-completed, then the event is sent under the run event envelope with promotionId, tenantId, environmentId, releaseId, the previous release as restoredReleaseId and the rollback promotion as rollbackPromotionId, and a transport outage is retried with backoff so the event is neither lost nor duplicated under its event id (SCN-EnvironmentPromotionService-011, ADR-0012). |
| Traces: services | EnvironmentPromotionService |
| Traces: aggregates | EnvironmentPromotionService/Promotion |
| Traces: apis | EnvironmentPromotionService/RollbackPromotion |
| Traces: events | EnvironmentPromotionService/RollbackCompleted, EnvironmentPromotionService/PromotionRequested |
| Traces: adrs | ADR-0012, ADR-0014, ADR-0015 |
| Traces: requirements | FR-08, NFR-09 |
| Traces: scenarios | SCN-EnvironmentPromotionService-004, SCN-EnvironmentPromotionService-011 |
| Relates: screens | promotions |
| Depends on | AIFACTORY-US-1314 |
| Sources | model/services/devops-gitops/EnvironmentPromotionService.yaml, docs/planes/execution/delivery-engine/services/environment-promotion-service/index.md#apis |
Tasks
| Task | Kind | Expected output | Repository |
|---|---|---|---|
AIFACTORY-TASK-5271 RollbackPromotion with the ManualRollback transition, the rollback evidence and the refusals |
implementation | RollbackPromotion, for the Completed promotion whose release is current in its environment and that has a previousReleaseId, records the actor, the reason and the previous release as target, opens a rollback promotion of the previous release with rollbackOfPromotionId and the Operator as requester and writes PromotionRequested in one transaction, counts a manual rollback and answers 202; completing the rollback promotion moves the rolled-back promotion to RolledBack through ManualRollback and writes RollbackCompleted with restoredReleaseId and rollbackPromotionId in that transaction; a repeat on a promotion whose rollback this operation opened answers 202 and opens nothing; a promotion in another state, without a previous release, no longer current in its environment or rolled back automatically is answered 409, one of another tenant or unknown 404 and a missing scope or role 403, and no refusal changes anything. | ConnectSoft.AI.SoftwareFactory.EnvironmentPromotionService |
AIFACTORY-TASK-5272 Verify roll-back-a-completed-promotion through the acceptance suite |
verification | Run dotnet test -c Release --filter "Category=Acceptance&(Scenario=SCN-EnvironmentPromotionService-004\|Scenario=SCN-EnvironmentPromotionService-011)"; a zero-match filter counts as a failure; the tests prove AC1 to AC3 of AIFACTORY-US-1315, including the rollback promotion opened without an approval, the idempotent repeat, the 409 for an older promotion of the environment and for an automatic rollback, the refusals without a state change, RollbackCompleted written only when the rollback promotion completes, and its publication and payload with rollbackPromotionId; consumer handling is proven by the suites of the consumers. |
ConnectSoft.AI.SoftwareFactory.EnvironmentPromotionService |
AIFACTORY-US-1316: Read promotions with their gates and evidence and the current release of an environment¶
behavior · persona observer
As an observer of the project, I want to see the promotions of my projects with their gates, approval and evidence, and which release each environment runs, so that the promotion state and the current release I see in the Studio and the fleet views are the truth the service holds.
A caller whose scope carries factory.delivery.read, an Operator, a Reviewer, a Workspace admin, a Platform admin or an Observer, reads promotions through DeliveryHost; fleet inventory and the Studio read the current release. EnvironmentPromotionService/ListPromotions returns the promotions of the projects in which the caller holds a role, every project of the tenant for a Platform admin, filtered by environment, release and state, each with its gates. EnvironmentPromotionService/GetPromotion returns one promotion with its gates and their evidence, the approval id, the desired-state reference, the verification results and the rollback evidence. EnvironmentPromotionService/GetCurrentRelease returns, for an environment, the release currently completed there: the release of its latest Completed promotion; a rollback is a new promotion of the previous release (D135), so once it completes, that rollback promotion is the latest Completed one and its release, the previous release, is current. Every query runs under the tenant row filter of the service. A promotion of another tenant, or an environment of another tenant, is answered 404, the same answer as for an unknown identifier, and never confirms that it exists (ADR-0015); an environment in which no release has completed is answered 404 as well. A caller without the scope is refused with 403, and so is a caller without a role in the project of the addressed promotion. Nothing is written by any of these reads, and a list never holds a promotion of another tenant.
Acceptance criteria
| AC1 | Given promotions of two projects and two tenants and a caller with factory.delivery.read and a role in one project, when EnvironmentPromotionService/ListPromotions is called with a filter by environment, release or state, then the response is 200 with only the promotions of that project that match, each with its gates, and no promotion of another tenant or project appears; given a caller without the scope, then 403 (SCN-EnvironmentPromotionService-001, ADR-0015). |
| AC2 | Given a promotion that completed after a production approval, when EnvironmentPromotionService/GetPromotion is called, then the response is 200 with its gates and evidence, the approval id, the desired-state reference and the verification results, and for a rolled back promotion its rollback evidence; given a promotion of another tenant or an unknown id, then 404 with the same problem response; given no scope, then 403; nothing is written (SCN-EnvironmentPromotionService-002, ADR-0015). |
| AC3 | Given an environment with a completed promotion that was later rolled back by a completed rollback promotion, when EnvironmentPromotionService/GetCurrentRelease is called, then the response is 200 with the previous release that the rollback promotion completed (D135); given an environment with a completed promotion only, then that release; given an environment of another tenant, an unknown environment or one in which no release completed, then 404; given no scope, then 403 (SCN-EnvironmentPromotionService-005, ADR-0015). |
| Traces: services | EnvironmentPromotionService |
| Traces: aggregates | EnvironmentPromotionService/Promotion |
| Traces: apis | EnvironmentPromotionService/ListPromotions, EnvironmentPromotionService/GetPromotion, EnvironmentPromotionService/GetCurrentRelease |
| Traces: adrs | ADR-0015 |
| Traces: requirements | FUX-02, FUX-05 |
| Traces: scenarios | SCN-EnvironmentPromotionService-001, SCN-EnvironmentPromotionService-002, SCN-EnvironmentPromotionService-005 |
| Relates: screens | promotions, environment-board |
| Depends on | AIFACTORY-US-1311 |
| Sources | model/services/devops-gitops/EnvironmentPromotionService.yaml, docs/planes/execution/delivery-engine/services/environment-promotion-service/index.md#apis |
Tasks
| Task | Kind | Expected output | Repository |
|---|---|---|---|
AIFACTORY-TASK-5273 ListPromotions, GetPromotion and GetCurrentRelease under the tenant row filter and the project roles of the caller |
implementation | ListPromotions returns the promotions of the projects in which the caller holds a role with their gates, filtered by environment, release and state; GetPromotion returns one promotion with gates, approval id, desired-state reference, verification and rollback evidence; GetCurrentRelease returns the release of the latest Completed promotion of the environment, a completed rollback promotion included; a resource of another tenant, an unknown one and an environment without a completed release are answered 404, a missing scope or role 403, and nothing is written. | ConnectSoft.AI.SoftwareFactory.EnvironmentPromotionService |
AIFACTORY-TASK-5274 Verify read-promotions-and-current-release through the acceptance suite |
verification | Run dotnet test -c Release --filter "Category=Acceptance&(Scenario=SCN-EnvironmentPromotionService-001\|Scenario=SCN-EnvironmentPromotionService-002\|Scenario=SCN-EnvironmentPromotionService-005)"; a zero-match filter counts as a failure; the tests prove AC1 to AC3 of AIFACTORY-US-1316 over two tenants and two projects, including the 404 that does not confirm a promotion or an environment of another tenant. |
ConnectSoft.AI.SoftwareFactory.EnvironmentPromotionService |
AIFACTORY-US-1621: RunControlService settles the step of a run that waits for a promotion when the promotion completes or fails¶
behavior · persona operator
As an operator, I want the step of a run that waits for a promotion settled with the outcome the promotion service recorded, so that a delivery or a release run never waits on a promotion that has already ended, and it goes on or fails on the recorded result.
The inbox handler SettleWaitingStep of RunControlService takes EnvironmentPromotionService/PromotionCompleted and EnvironmentPromotionService/PromotionFailed. RunControlService itself is delivered in I1 by feature run-control-service, but the producer of these two events arrives in I2, so the handler for them is delivered by this feature and its tasks are written in the repository ConnectSoft.AI.SoftwareFactory.RunControlService (D140). The handler registers both events in the inbox of the messaging profile of RunControlService, idempotent on the event id. The requesting step passes its runId and its stepRunId to Promotions.Request, the promotion keeps them, and both events echo them as optional members, absent when no run requested the promotion (D141, AIFACTORY-US-1311, AIFACTORY-US-1314). The handler looks up the waiting step directly by them: under the tenant of the event it takes the Step whose step run id is the stepRunId of the event in the Run that runId names, and it ignores an event without them, such as one for a promotion an Operator requested without a run or for a rollback promotion. On PromotionCompleted it moves that step to Succeeded with the promotion as its result reference. On PromotionFailed it moves the step to Failed with the failure class permanent and records the reason and rolledBack of the event; a failed promotion is read as permanent because a retry of the step would request a new promotion, and this reading of a class the model leaves unnamed is reported. In both cases RunControlService/StepSettled is written in the transaction that moves the step to its final state, with the step run id of the engine, the stepId, the final state, the number of attempts and, for a failed step, the failure class (D119, D121); WorkflowEngineService applies the failure policy of the step and continues or fails the run in its own PBIs. An event without runId and stepRunId, an event whose runId names no run of the tenant of the event, a run of another tenant among them, an event whose stepRunId names no step of that run, an event for a step that is already in a final state, Cancelled by a cancellation among them, and a redelivered event change nothing and publish nothing. A Rejected promotion publishes none of the events of EnvironmentPromotionService (AIFACTORY-US-1312), so a step that waits for it is not settled by this handler and ends by the timeout of the step. When the store of RunControlService does not answer, the inbox keeps the event and retries it, and the event is applied once.
Acceptance criteria
| AC1 | Given a run of the tenant with a step that waits for a promotion it requested, when EnvironmentPromotionService/PromotionCompleted names that promotion with the runId of the run and the stepRunId of the step (D141), then the RunControlService/Step moves to Succeeded with the promotion as its result reference and RunControlService/StepSettled is written in the same transaction with the step run id of the engine, the stepId, the final state Succeeded and the number of attempts; a redelivery under the same event id changes nothing (model/services/control-plane/RunControlService.yaml, ADR-0014). |
| AC2 | Given the same waiting step, when EnvironmentPromotionService/PromotionFailed names the promotion with the same runId and stepRunId and with rolledBack false after a provisioning failure or true after the automatic rollback, then the RunControlService/Step moves to Failed with the failure class permanent, the reason and rolledBack are recorded, and RunControlService/StepSettled carries the final state Failed and the failure class in the transaction of the move (model/services/control-plane/RunControlService.yaml). |
| AC3 | Given an event without runId and stepRunId, as for a promotion an Operator requested without a run, an event whose runId names a run of another tenant or no run, an event whose stepRunId names no step of the run, a waiting step that is already Cancelled (D141), or the store of RunControlService stopped while the event arrives, when EnvironmentPromotionService/PromotionCompleted or EnvironmentPromotionService/PromotionFailed is handled, then the first four change no step and write no RunControlService/StepSettled, and the last is retried by the inbox until the store answers and is applied once under its event id (ADR-0012, ADR-0014). |
| Traces: services | RunControlService, EnvironmentPromotionService, WorkflowEngineService |
| Traces: aggregates | RunControlService/Step |
| Traces: events | EnvironmentPromotionService/PromotionCompleted, EnvironmentPromotionService/PromotionFailed, RunControlService/StepSettled |
| Traces: workflows | delivery-run, release |
| Traces: adrs | ADR-0012, ADR-0014 |
| Traces: requirements | FR-08 |
| Depends on | AIFACTORY-US-1314, feature:run-control-service, feature:contracts-package |
| Sources | model/services/control-plane/RunControlService.yaml, model/services/devops-gitops/EnvironmentPromotionService.yaml, model/workflows/delivery-run.yaml, model/workflows/release.yaml |
Tasks
| Task | Kind | Expected output | Repository |
|---|---|---|---|
AIFACTORY-TASK-6561 SettleWaitingStep of RunControlService for PromotionCompleted and PromotionFailed |
implementation | The inbox of the RunControlService messaging profile registers PromotionCompleted and PromotionFailed with idempotency on the event id, and SettleWaitingStep looks up the waiting step directly by the runId and stepRunId the event echoes, under the tenant of the event, and ignores an event without them (D141), moves it to Succeeded with the promotion as result reference or to Failed with the failure class permanent and the reason and rolledBack recorded, and writes StepSettled with step run id, stepId, final state, attempts and failure class in the same transaction; an event without runId and stepRunId, of a run of another tenant or of no run, of a step run the run does not hold or for a step in a final state changes nothing. | ConnectSoft.AI.SoftwareFactory.RunControlService |
AIFACTORY-TASK-6562 Fixture promotion events and waiting steps of the settlement suite |
fixture | The acceptance suite of RunControlService holds fixture events PromotionCompleted and PromotionFailed with rolledBack false and true for two tenants, with the runId and stepRunId of a waiting step, with an unknown stepRunId and without both (D141), built from the event types of the pinned contracts package under the run event envelope, runs with a step that waits for a promotion, with a step already Cancelled and with no waiting step, and a switch that stops the store of the service while an event arrives. | ConnectSoft.AI.SoftwareFactory.RunControlService |
AIFACTORY-TASK-6563 Verify settle-the-step-waiting-for-a-promotion through the acceptance suite |
verification | Run dotnet test -c Release --filter "Category=Acceptance&Feature=SettleWaitingStepOnPromotion" in the repository of RunControlService; a zero-match filter counts as a failure; the tests prove AC1 to AC3 of AIFACTORY-US-1621: the step settled Succeeded on PromotionCompleted and Failed with the failure class permanent on PromotionFailed, RunControlService/StepSettled in the transaction of the move, the events that change nothing, the event without runId and stepRunId among them (D141), and the retry while the store is stopped with one application under the event id. |
ConnectSoft.AI.SoftwareFactory.RunControlService |