Promote reviewed prompts with a return path

Learning objective

Promote and roll back approved Prompt Management variants across environments using review gates.

Core idea

Prompt promotion changes which reviewed configuration an environment invokes. It should not mean editing a production draft until its behavior resembles the candidate. Create a numbered Prompt management version, bind review evidence to that snapshot, and update the application’s reference only after the required gate passes.

The prompt service supplies versions; your release workflow supplies approval and environment routing. Do not mistake a successful CreatePromptVersion call for an approval decision. A rollback restores the application’s reference to a compatible, known-good version. It does not rewrite the failed version or undo actions that its responses already caused.

How it works

Bind the gate to the candidate identity

A prompt variant describes a configuration, while a version snapshots the selected configuration at a point in time. See 1.6.2 for creation and the persisted API’s one-variant limit. In this objective, promoting a variant means promoting a version that contains the reviewed configuration, not choosing an arbitrary variant name in a runtime request.

Whether you create the snapshot with CreatePromptVersion (see 1.6.2) or as a CloudFormation AWS::Bedrock::PromptVersion resource, record its ARN and version number before review; in a template, Fn::GetAtt returns them as Arn and Version. Retrieve a numbered version with GetPrompt using promptIdentifier and promptVersion; omitting promptVersion returns the working draft. A release verifier that omits this parameter can compare the wrong artifact even when the prompt identifier is correct.

Define a release record containing the version-qualified ARN, selected model configuration, variable contract, application response-contract revision, guardrail identity, evaluation evidence, and previous accepted release. The contract and evidence identifiers are application-owned metadata. Their purpose is to make the approval about a specific candidate rather than an author’s statement that “the prompt looks good.”

Review representative outcomes, including missing variables, clarification, attempted instruction override, and domain-invalid responses. Record acceptance criteria before evaluating. A change that improves answer style but weakens escalation behavior must not pass merely because average quality improved. Reuse the evaluation discipline from 1.1.4 instead of inventing a different meaning of “approved” for prompts.

Place an approval action before deployment

AWS CodePipeline manual approval actions stop an execution at a chosen stage. A principal with the required permissions approves or rejects it. Approval resumes the execution; rejection prevents continuation. If nobody approves or rejects within seven days, the action fails. That timeout is a release-control limit, not a prompt expiration date.

Put the review artifact’s link in the action’s URL for Review and explain the candidate in Comments for Approvers. The artifact should identify the exact prompt snapshot and the deployment target. The reviewer needs enough evidence to compare the candidate with the previous release, including changes to the model, variable names, or safety configuration.

Keep the candidate fixed after approval. If its configuration changes, create a new version and obtain approval for that identity. Restrict production deployment to the pipeline’s release path so a manual draft edit cannot bypass the decision. This is an application governance design built around AWS controls, not a claim that Prompt management has a native approval-status field.

Resolve the artifact in each environment

An ARN includes the prompt’s account and Region. Do not assume that a development prompt ARN becomes a production artifact merely by relabeling it. If environments deliberately share the same permitted resource, their configuration can reference the same version. If they use separate resources, rebuild the reviewed configuration in the target environment from the same reviewed CloudFormation template. The template declares the prompt, and an AWS::Bedrock::PromptVersion resource whose required PromptArn property names that prompt creates the numbered snapshot that AWS describes as deployable to production. Verify equivalence before routing traffic to the target version.

For separate resources, keep a mapping from the source release to each target version ARN. Compare the target GetPrompt response with the approved configuration, including template, variables, model selection, and inference settings. Environment-specific substitutions must be declared in the release record. A different model reference is a behavioral change to evaluate, not a harmless consequence of copying the text.

The application invokes its environment’s approved version ARN as modelId. Resolve that reference before building each request, and log the selected release identity. This makes it possible to distinguish a deployment that completed from workers that still use a previous configuration. See 1.6.4 for usage audit evidence.

Roll back the reference and its compatible contract

Keep the previous accepted prompt version available and test that the application can still invoke it. A rollback that restores an ARN but leaves incompatible variable names or response handling in place is not recovery. Restore the compatible release configuration as a unit: prompt reference, caller contract, and any intentionally coupled policy identities.

AWS AppConfig can carry the application’s environment-to-prompt reference. Its configured deployment strategies and CloudWatch alarm monitors can automatically roll configuration back if an alarm enters ALARM during deployment. AppConfig is rolling back configuration data; it is not deleting or editing the Bedrock prompt version. See 1.2.8 for broader configuration-release mechanics.

For manual control, StopDeployment can roll back an AppConfig deployment while it is in progress. After successful completion, StopDeployment with AllowRevert can revert a deployment only if it succeeded within the last 72 hours; beyond that window, create a new deployment. Record this distinction in the recovery procedure rather than assuming one stop operation works forever.

Choose alarms that reflect the prompt change. Application-defined metrics can capture response-contract rejection, failed clarification, or an unsafe outcome reported by the enforcement layer. These are custom workload signals, not built-in Bedrock “prompt quality” metrics. An alarm must measure something the candidate can damage; an availability-only signal can miss a prompt that responds quickly but incorrectly.

Only an approved version moves the application reference, and an alarm during deployment restores the previous one.

Key distinctions and trade-offs

Snapshot versus approval: A numbered version identifies content. A review gate decides whether that content is acceptable for a target environment. Neither substitutes for the other.

Promotion versus reconstruction: Shared-resource environments can change a reference. Separate-resource environments need a target artifact and an equivalence check. Copying prompt text alone loses the model and inference configuration.

Rollback versus repair: Rollback restores an accepted release while you investigate. Repair produces another candidate that must pass the gate. Neither operation reverses completed business effects; those need their own reconciliation.

Keep gates proportionate to risk, but keep their scope explicit. A low-risk wording adjustment can use a smaller review dataset than a tool-using workflow change. Both still require a fixed candidate identity and a usable return path. See 2.3.9 for the broader CI/CD pipeline around these gates.

Architecture / decision scenario

A service assistant has separate staging and production prompt resources. The author snapshots a clarification-focused candidate, runs the regression dataset, and records its template, model settings, variable contract, and guardrail version. Release automation deploys the same reviewed template to the production account, which creates the prompt and its AWS::Bedrock::PromptVersion snapshot there, and records the target version ARN without routing traffic to it.

A CodePipeline manual approval action links to the evidence and target-configuration comparison. After approval, the application reference moves through AppConfig deployment. A custom response-contract-rejection alarm enters ALARM during rollout, so AppConfig restores the previous reference. The failed candidate remains identifiable for analysis.

The team confirms that the previous prompt and caller contract still work together. It then fixes the candidate under a new version and repeats the gate. Renaming the existing draft to “approved” would neither restore production nor preserve the review decision.

Common exam traps

• Treating a numbered prompt version as automatically approved.
• Reviewing the draft by omitting GetPrompt.promptVersion.
• Assuming variant names are runtime deployment aliases.
• Reusing a source ARN without resolving the target environment’s resource identity.
• Rolling back the prompt reference while retaining an incompatible variable contract.
• Applying AppConfig’s 72-hour completed-deployment revert window to Bedrock version retention.

What to remember

• Approve a fixed snapshot and a declared target mapping.
• Put a concrete release gate before changing the application reference.
• Preserve the previous compatible release before promotion.
• Configuration rollback restores routing; it does not rewrite prompt history or business effects.

Knowledge check

References

• AWS, Deploy a prompt to your application using versions in Prompt management
• AWS, AWS::Bedrock::PromptVersion
• AWS, GetPrompt
• AWS, Add a manual approval action to a stage
• AWS, Reverting a configuration