Redeploy and roll back a deployment with CodeDeploy

CodeDeploy rolls back deployments by redeploying a previously deployed revision of an application as a new deployment. These rolled-back deployments are technically new deployments, with new deployment IDs, rather than restored versions of a previous deployment.

Deployments can be rolled back automatically or manually.

Automatic rollbacks

You can configure a deployment group or deployment to automatically roll back when a deployment fails or when a monitoring threshold you specify is met. In this case, the last known good version of an application revision is deployed. You configure automatic rollbacks when you create an application or create or update a deployment group.

When you create a new deployment, you can also choose to override the automatic rollback configuration that were specified for the deployment group.

For more information about configuring automatic rollbacks, see Configure advanced options for a deployment group.

Manual rollbacks

If you have not set up automatic rollbacks, you can manually roll back a deployment by creating a new deployment that uses any previously deployed application revision and following the steps to redeploy a revision. You might do this if an application has gotten into an unknown state. Rather than spending a lot of time troubleshooting, you can redeploy the application to a known working state. For more information, see Create a deployment with CodeDeploy.

Rollback and redeployment workflow

When automatic rollback is initiated, or when you manually initiate a redeployment or manual rollback, CodeDeploy first tries to remove from each participating instance all files that were last successfully installed. CodeDeploy does this by checking the cleanup file:

/opt/codedeploy-agent/deployment-root/deployment-instructions/deployment-group-ID-cleanup file (for Amazon Linux, Ubuntu Server, and RHEL instances)

C:\ProgramData\Amazon\CodeDeploy\deployment-instructions\deployment-group-ID-cleanup file (for Windows Server instances)

If it exists, CodeDeploy uses the cleanup file to remove from the instance all listed files before starting the new deployment.

For example, the first two text files and two script files were already deployed to an Amazon EC2 instance running Windows Server, and the scripts created two more text files during deployment lifecycle events:

c:\temp\a.txt (previously deployed by CodeDeploy)
c:\temp\b.txt (previously deployed by CodeDeploy)
c:\temp\c.bat (previously deployed by CodeDeploy)
c:\temp\d.bat (previously deployed by CodeDeploy)
c:\temp\e.txt (previously created by c.bat)
c:\temp\f.txt (previously created by d.bat)

The cleanup file will list only the first two text files and two script files:

c:\temp\a.txt
c:\temp\b.txt 
c:\temp\c.bat 
c:\temp\d.bat 

Before the new deployment, CodeDeploy will remove only the first two text files and the two script files, leaving the last two text files untouched:

c:\temp\a.txt will be removed
c:\temp\b.txt will be removed
c:\temp\c.bat will be removed
c:\temp\d.bat will be removed
c:\temp\e.txt will remain
c:\temp\f.txt will remain

As part of this process, CodeDeploy will not try to revert or otherwise reconcile any actions taken by any scripts in previous deployments during subsequent redeployments, whether manual or automatic rollbacks. For example, if the c.bat and d.bat files contain logic to not re-create the e.txt and f.txt files if they already exist, then the old versions of e.txt and f.txt will remain untouched whenever CodeDeploy runs c.bat and d.bat in subsequent deployments. You can add logic to c.bat and d.bat to always check for and delete old versions of e.txt and f.txt before creating new ones.

Rollback behavior with existing content

As part of the deployment process, the CodeDeploy agent removes from each instance all the files installed by the most recent deployment. If files that weren’t part of a previous deployment appear in target deployment locations, you can choose what CodeDeploy does with them during the next deployment:

You can choose this behavior when you create a deployment. If creating a deployment in the console, see Create an EC2/On-Premises Compute Platform deployment (console). If creating a deployment with the AWS CLI, see Create an EC2/On-Premises Compute Platform deployment (CLI).

You might choose to retain files that you want to be part of the next deployment without having to add them to the application revision package. For example, you might upload files directly to the instance that are required for the deployment but weren’t added to the application revision bundle. Or you might upload files to the instance if your applications are already in your production environment but you want to use CodeDeploy for the first time to deploy them.

In the case of rollbacks, where the most recent successfully deployed application revision is redeployed due to a deployment failure, the content-handling option for that last successful deployment is applied to the rollback deployment.

However, if the deployment that failed was configured to overwrite, instead of retain files, an unexpected result can occur during the rollback. Specifically, the files you expected to be retained might be removed by the failed deployment. The files are not on the instance when the rollback deployment runs.

In the following example, there are three deployments. Any file that is overwritten (deleted) during the failed second deployment is no longer available (cannot be retained) when application revision 1 is deployed again during deployment 3: