# Configuring stage rollback
You can roll back a stage to an execution that was successful in that stage. You can preconfigure a stage for rollback on failure, or you can manually roll back a stage. The rolled back operation will result in a new execution. The target pipeline execution chosen for rollback is used to retrieve source revisions and variables.
The type of execution, either standard or rollback, displays in the pipeline history, pipeline state, and pipeline execution details.
**Topics**
+ [Considerations for rollbacks](#stage-rollback-considerations)
+ [Roll back a stage manually](stage-rollback-manual.md)
+ [Configure a stage for automatic rollback](stage-rollback-auto.md)
+ [View rollback status in execution listing](stage-rollback-view-listing.md)
+ [View rollback status details](stage-rollback-view-details.md)
## Considerations for rollbacks
Considerations for stage rollback are as follows:
+ You cannot roll back a source stage.
+ The pipeline can only roll back to a previous execution if the previous execution was started in the current pipeline structure version.
+ You cannot roll back to a target execution ID that is a rollback execution type.
+ CodePipeline will use the variables and artifacts from the execution to which it is rolling back.
# Roll back a stage manually
You can manually roll back a stage using the console or CLI. The pipeline can only roll back to a previous execution if the previous execution was started in the current pipeline structure version.
You can also configure a stage to roll back automatically on failure as detailed in [Configure a stage for automatic rollback](stage-rollback-auto.md).
## Roll back a stage manually (console)
You can use the console to manually roll back a stage to a target pipeline execution. When a stage is rolled back, a **Rollback** label displays on the pipeline visualization in the console.
**Roll back a stage manually (console)**
1. Sign in to the AWS Management Console and open the CodePipeline console at [http://console.aws.amazon.com/codesuite/codepipeline/home](http://console.aws.amazon.com/codesuite/codepipeline/home).
The names and status of all pipelines associated with your AWS account are displayed.
1. In **Name**, choose the name of the pipeline with the stage to roll back.
![\[An example diagram of a pipeline with two stages in CodePipeline.\]](http://docs.aws.amazon.com/codepipeline/latest/userguide/images/rollback-stage-first.png)
1. On the stage, choose **Start rollback**. The **Roll back to** page displays.
1. Choose the target execution to which you want to roll back the stage.
**Note**
The list of target pipeline executions available will be all executions in the current pipeline version beginning on February 1, 2024.
![\[An example of choosing the target execution ID in CodePipeline.\]](http://docs.aws.amazon.com/codepipeline/latest/userguide/images/rollback-stage-dialog.png)
The following diagram shows an example of the rolled back stage with the new execution ID.
![\[An example diagram of a pipeline with a rolled back stage in CodePipeline.\]](http://docs.aws.amazon.com/codepipeline/latest/userguide/images/stage-rolled-back.png)
## Roll back a stage manually (CLI)
To use the AWS CLI to manually roll back a stage, use the `rollback-stage` command.
You can also roll back a stage manually as detailed in [Roll back a stage manually](#stage-rollback-manual).
**Note**
The list of target pipeline executions available will be all executions in the current pipeline version beginning on February 1, 2024.
**To roll back a stage manually (CLI)**
1. The CLI command for manual rollback will require the execution ID of a previously successful pipeline execution in the stage. To get the target pipeline execution ID that you will specify, use the list-pipeline-executions command with a filter that will return successful executions in the stage. Open a terminal (Linux, macOS, or Unix) or command prompt (Windows) and use the AWS CLI to run the `list-pipeline-executions` command, specifying the name of the pipeline and the filter for successful executions in the stage. In this example, the output will list pipeline executions for the pipeline named MyFirstPipeline and for successful executions in the stage named `deploys3`.
```
aws codepipeline list-pipeline-executions --pipeline-name MyFirstPipeline --filter succeededInStage={stageName=deploys3}
```
In the output, copy the execution ID of the previously successful execution that you want to specify for rollback. You will use this in the next step as the target execution ID.
1. Open a terminal (Linux, macOS, or Unix) or command prompt (Windows) and use the AWS CLI to run the `rollback-stage` command, specifying the name of the pipeline, the name of the stage, and the target execution that you want to roll back to. For example, to roll back a stage named Deploy for a pipeline named *MyFirstPipeline*:
```
aws codepipeline rollback-stage --pipeline-name MyFirstPipeline --stage-name Deploy --target-pipeline-execution-id bc022580-4193-491b-8923-9728dEXAMPLE
```
The output returns the execution ID for the new rolled-back execution. This is a separate ID that uses the source revisions and parameters of the specified target execution.
# Configure a stage for automatic rollback
You can configure stages in a pipeline to roll back automatically on failure. When the stage fails, the stage is rolled back to the most recent successful execution. The pipeline can only roll back to a previous execution if the previous execution was started in the current pipeline structure version. Since, automatic rollback configuration is part of the pipeline definition, your pipeline stage will auto-rollback only after there is a successful pipeline execution in the pipeline stage.
## Configure a stage for automatic rollback (console)
You can roll back a stage to a specified previous successful execution. For more information, see [RollbackStage](https://docs.aws.amazon.com/codepipeline/latest/APIReference/API_RollbackStage.html) in the *CodePipeline API Guide*.
**Configure a stage for automatic rollback (console)**
1. Sign in to the AWS Management Console and open the CodePipeline console at [http://console.aws.amazon.com/codesuite/codepipeline/home](http://console.aws.amazon.com/codesuite/codepipeline/home).
The names and status of all pipelines associated with your AWS account are displayed.
1. In **Name**, choose the name of the pipeline you want to edit.
1. On the pipeline details page, choose **Edit**.
1. On the **Edit** page, for the action you want to edit, choose **Edit stage**.
1. Choose **Automated stage configuration:**, and then choose **Configure automatic rollback on stage failure**. Save the changes to your pipeline.
![\[An example edit screen to configure a rolled back stage in CodePipeline.\]](http://docs.aws.amazon.com/codepipeline/latest/userguide/images/rollback-configure.png)
## Configure a stage for automatic rollback (CLI)
To use the AWS CLI to configure a failed stage to automatically roll back to the most recent successful execution, use the commands to create or update a pipeline as detailed in [Create a pipeline, stages, and actions](pipelines-create.md) and [Edit a pipeline in CodePipeline](pipelines-edit.md).
+ Open a terminal (Linux, macOS, or Unix) or command prompt (Windows) and use the AWS CLI to run the `update-pipeline` command, specifying the failure condition in the pipeline structure. The following example configures automatic rollback for a staged named `S3Deploy`:
```
{
"name": "S3Deploy",
"actions": [
{
"name": "s3deployaction",
"actionTypeId": {
"category": "Deploy",
"owner": "AWS",
"provider": "S3",
"version": "1"
},
"runOrder": 1,
"configuration": {
"BucketName": "static-website-bucket",
"Extract": "false",
"ObjectKey": "SampleApp.zip"
},
"outputArtifacts": [],
"inputArtifacts": [
{
"name": "SourceArtifact"
}
],
"region": "us-east-1"
}
],
"onFailure": {
"result": "ROLLBACK"
}
}
```
For more information about configuring failure conditions for stage rollback, see [FailureConditions](https://docs.aws.amazon.com/codepipeline/latest/APIReference/API_FailureConditions.html) in the *CodePipeline API Reference*.
## Configure a stage for automatic rollback (CloudFormation)
To use CloudFormation to configure a stage to roll back automatically on failure, use the `OnFailure` parameter. On failure, the stage will automatically roll back to the most recent successful execution.
```
OnFailure:
Result: ROLLBACK
```
+ Update the template as shown in the following snippet. The following example configures automatic rollback for a staged named `Release`:
```
AppPipeline:
Type: AWS::CodePipeline::Pipeline
Properties:
RoleArn:
Ref: CodePipelineServiceRole
Stages:
-
Name: Source
Actions:
-
Name: SourceAction
ActionTypeId:
Category: Source
Owner: AWS
Version: 1
Provider: S3
OutputArtifacts:
-
Name: SourceOutput
Configuration:
S3Bucket:
Ref: SourceS3Bucket
S3ObjectKey:
Ref: SourceS3ObjectKey
RunOrder: 1
-
Name: Release
Actions:
-
Name: ReleaseAction
InputArtifacts:
-
Name: SourceOutput
ActionTypeId:
Category: Deploy
Owner: AWS
Version: 1
Provider: CodeDeploy
Configuration:
ApplicationName:
Ref: ApplicationName
DeploymentGroupName:
Ref: DeploymentGroupName
RunOrder: 1
OnFailure:
Result: ROLLBACK
ArtifactStore:
Type: S3
Location:
Ref: ArtifactStoreS3Location
EncryptionKey:
Id: arn:aws:kms:useast-1:ACCOUNT-ID:key/KEY-ID
Type: KMS
DisableInboundStageTransitions:
-
StageName: Release
Reason: "Disabling the transition until integration tests are completed"
Tags:
- Key: Project
Value: ProjectA
- Key: IsContainerBased
Value: 'true'
```
For more information about configuring failure conditions for stage rollback, see [OnFailure](https://docs.aws.amazon.com/AWSCloudFormation/latest/UserGuide/aws-properties-codepipeline-pipeline-stagedeclaration.html#cfn-codepipeline-pipeline-stagedeclaration-onfailure) under `StageDeclaration` in the *CloudFormation User Guide*.
# View rollback status in execution listing
You can view the status and target execution ID for a rollback execution.
## View rollback status in list of executions (console)
You can use the console to view the status and target execution ID for a rollback execution in the execution listing.
**View rollback execution status in list of executions (console)**
1. Sign in to the AWS Management Console and open the CodePipeline console at [http://console.aws.amazon.com/codesuite/codepipeline/home](http://console.aws.amazon.com/codesuite/codepipeline/home).
The names and status of all pipelines associated with your AWS account are displayed.
1. In **Name**, choose the name of the pipeline you want to view.
1. Choose **History**. The list of executions shows the label **Rollback**.
![\[An example execution history page showing the Rollback label in CodePipeline.\]](http://docs.aws.amazon.com/codepipeline/latest/userguide/images/rollback-view-list-console.png)
Choose the execution ID for which you want to view details.
## View rollback status with `list-pipeline-executions` (CLI)
You can use the CLI to view the status and target execution ID for a rollback execution.
+ Open a terminal (Linux, macOS, or Unix) or command prompt (Windows) and use the AWS CLI to run the **list-pipeline-executions** command:
```
aws codepipeline list-pipeline-executions --pipeline-name MyFirstPipeline
```
This command returns a list of all of the completed executions associated with the pipeline.
The following example shows the returned data for a pipeline named *MyFirstPipeline* where a rollback execution started the pipeline.
```
{
"pipelineExecutionSummaries": [
{
"pipelineExecutionId": "eb7ebd36-353a-4551-90dc-18ca5EXAMPLE",
"status": "Succeeded",
"startTime": "2024-04-16T09:00:28.185000+00:00",
"lastUpdateTime": "2024-04-16T09:00:29.665000+00:00",
"sourceRevisions": [
{
"actionName": "Source",
"revisionId": "revision_ID",
"revisionSummary": "Added README.txt",
"revisionUrl": "console-URL"
}
],
"trigger": {
"triggerType": "ManualRollback",
"triggerDetail": "{arn:aws:sts:::assumed-role/"}"
},
"executionMode": "SUPERSEDED",
"executionType": "ROLLBACK",
"rollbackMetadata": {
"rollbackTargetPipelineExecutionId": "f15b38f7-20bf-4c9e-94ed-2535eEXAMPLE"
}
},
{
"pipelineExecutionId": "fcd61d8b-4532-4384-9da1-2aca1EXAMPLE",
"status": "Succeeded",
"startTime": "2024-04-16T08:58:56.601000+00:00",
"lastUpdateTime": "2024-04-16T08:59:04.274000+00:00",
"sourceRevisions": [
{
"actionName": "Source",
"revisionId": "revision_ID",
"revisionSummary": "Added README.txt",
"revisionUrl": "console_URL"
}
],
"trigger": {
"triggerType": "StartPipelineExecution",
"triggerDetail": "arn:aws:sts:::assumed-role/"
},
"executionMode": "SUPERSEDED"
},
{
"pipelineExecutionId": "5cd064ca-bff7-425f-8653-f41d9EXAMPLE",
"status": "Failed",
"startTime": "2024-04-24T19:19:50.781000+00:00",
"lastUpdateTime": "2024-04-24T19:19:52.119000+00:00",
"sourceRevisions": [
{
"actionName": "Source",
"revisionId": "",
"revisionSummary": "Edited README.txt",
"revisionUrl": ""
}
],
"trigger": {
"triggerType": "AutomatedRollback",
"triggerDetail": "{\"FailedPipelineExecutionId\":\"b2e77fa5-9285-4dea-ae66-4389EXAMPLE\"}"
},
"executionMode": "SUPERSEDED",
"executionType": "ROLLBACK",
"rollbackMetadata": {
"rollbackTargetPipelineExecutionId": "5efcfa68-d838-4ca7-a63b-4a743EXAMPLE"
}
},
```
# View rollback status details
You can view the status and target execution ID for a rollback execution.
## View rollback status on detail page (console)
You can use the console to view the status and target pipeline execution ID for a rollback execution.
![\[An example status page showing the target pipeline execution ID field in CodePipeline.\]](http://docs.aws.amazon.com/codepipeline/latest/userguide/images/rollback-view-status-console.png)
## View rollback details with `get-pipeline-execution` (CLI)
Pipeline executions that have been rolled back will show in the output for getting the pipeline execution.
+ To view details about a pipeline, run the **[get-pipeline-execution](http://docs.aws.amazon.com/cli/latest/reference/codepipeline/get-pipeline-execution.html)** command, specifying the unique name of the pipeline. For example, to view details about a pipeline named *MyFirstPipeline*, enter the following:
```
aws codepipeline get-pipeline-execution --pipeline-name MyFirstPipeline --pipeline-execution-id 3f658bd1-69e6-4448-ba3e-79007EXAMPLE
```
This command returns the structure of the pipeline.
The following example shows the returned data for a portion of a pipeline named *MyFirstPipeline*, where the rollback execution ID and metadata are shown.
```
{
"pipelineExecution": {
"pipelineName": "MyFirstPipeline",
"pipelineVersion": 6,
"pipelineExecutionId": "2004a94e-8b46-4c34-a695-c8d20EXAMPLE",
"status": "Succeeded",
"artifactRevisions": [
{
"name": "SourceArtifact",
"revisionId": "",
"revisionSummary": "Added README.txt",
"revisionUrl": ""
}
],
"trigger": {
"triggerType": "ManualRollback",
"triggerDetail": "arn:aws:sts:::assumed-role/"
},
"executionMode": "SUPERSEDED",
"executionType": "ROLLBACK",
"rollbackMetadata": {
"rollbackTargetPipelineExecutionId": "4f47bed9-6998-476c-a49d-e60beEXAMPLE"
}
}
}
```
## View rollback state with `get-pipeline-state` (CLI)
Pipeline executions that have been rolled back will show in the output for getting the pipeline state.
+ To view details about a pipeline, run the **get-pipeline-state** command, specifying the unique name of the pipeline. For example, to view state details about a pipeline named *MyFirstPipeline*, enter the following:
```
aws codepipeline get-pipeline-state --name MyFirstPipeline
```
The following example shows the returned data with the rollback execution type.
```
{
"pipelineName": "MyFirstPipeline",
"pipelineVersion": 7,
"stageStates": [
{
"stageName": "Source",
"inboundExecutions": [],
"inboundTransitionState": {
"enabled": true
},
"actionStates": [
{
"actionName": "Source",
"currentRevision": {
"revisionId": ""
},
"latestExecution": {
"actionExecutionId": "13bbd05d-b439-4e35-9c7e-887cb789b126",
"status": "Succeeded",
"summary": "update",
"lastStatusChange": "2024-04-24T20:13:45.799000+00:00",
"externalExecutionId": "10cbEXAMPLEID"
},
"entityUrl": "console-url",
"revisionUrl": "console-url"
}
],
"latestExecution": {
"pipelineExecutionId": "cf95a8ca-0819-4279-ae31-03978EXAMPLE",
"status": "Succeeded"
}
},
{
"stageName": "deploys3",
"inboundExecutions": [],
"inboundTransitionState": {
"enabled": true
},
"actionStates": [
{
"actionName": "s3deploy",
"latestExecution": {
"actionExecutionId": "3bc4e3eb-75eb-45b9-8574-8599aEXAMPLE",
"status": "Succeeded",
"summary": "Deployment Succeeded",
"lastStatusChange": "2024-04-24T20:14:07.577000+00:00",
"externalExecutionId": "mybucket/SampleApp.zip"
},
"entityUrl": "console-URL"
}
],
"latestExecution": {
"pipelineExecutionId": "fdf6b2ae-1472-4b00-9a83-1624eEXAMPLE",
"status": "Succeeded",
"type": "ROLLBACK"
}
}
],
"created": "2024-04-15T21:29:01.635000+00:00",
"updated": "2024-04-24T20:12:24.480000+00:00"
}
```