AWS CodeDeploy
User Guide (API Version 2014-10-06)

Document History

The following table describes the major changes made to this user guide to support new and enhanced functionality since the last release of the CodeDeploy User Guide.

  • API version: 2014-10-06

  • Latest documentation update: June 5, 2019

Change Description Date

Updated topics

CodeDeploy is now available in the Asia Pacific (Hong Kong) Region (ap-east-1) region. Several topics, including those containing instructions for setting up the CodeDeploy agent, were updated to reflect the availability of this new region. You must explicitly enable access to this region. For more informaiton, see Managing AWS Regions.

April 25, 2019

Updated topics

AWS CodeDeploy now supports blue/green deployments of a containerized application in an Amazon ECS service. A CodeDeploy application that uses the new Amazon ECS compute platform deploys a containerized application to a new, replacement task set in the same Amazon ECS service. Several topics have been added and updated to reflect this change, including Overview of AWS CodeDeploy Compute Platforms, Deployments on an Amazon ECS Compute Platform, AppSpec File Structure for Amazon ECS Deployments, and Create an Application for an Amazon ECS Service Deployment (Console).

November 27, 2018

Updated CodeDeploy agent

The AWS CodeDeploy agent was updated to version 1.0.1.1597. For more information, see Version History of the CodeDeploy Agent.

November 15, 2018

Updated console

Procedures in this guide were updated to match the new design of the CodeDeploy console.

October 30, 2018

New minimum supported version of the CodeDeploy agent

The minimum supported version of the AWS CodeDeploy agent is now 1.0.1.1458. For more information, see Version History of the CodeDeploy Agent.

August 7, 2018

Earlier Updates

The following table describes important changes in each release of the AWS CodeDeploy User Guide before June 2018.

Change Description Date Changed
Topic updates CodeDeploy is now available in the EU (Paris) Region (eu-west-3) region. Several topics, including those containing instructions for setting up the CodeDeploy agent, were updated to reflect the availability of this new region. December 19, 2017
Updated topics

CodeDeploy is now available in the China (Ningxia) Region.

To use services in the China (Beijing) Region or China (Ningxia) Region, you must have an account and credentials for those regions. Accounts and credentials for other AWS regions do not work for the Beijing and Ningxia Regions, and vice versa.

Information about some resources for the China Regions, such as CodeDeploy Resource Kit bucket names and CodeDeploy agent installation procedures, are not included in this edition of the CodeDeploy User Guide.

For more information:

December 11, 2017
Updated topics CodeDeploy now supports the deployment of a Lambda function. An AWS Lambda deployment shifts incoming traffic from an existing Lambda function to an updated Lambda function version. You choose or create a deployment configuration to specify the number of traffic shifting intervals in the deployment and the percentage of traffic to shift in each interval. AWS Lambda deployments are supported by the AWS Serverless Application Model (AWS SAM) so that you can use an AWS SAM deployment preference to manage the way in which traffic is shifted durng an AWS Lambda deployment. Several topics have been added and updated to reflect this change, including Overview of CodeDeploy Compute Platforms, Deployments on an AWS Lambda Compute Platform, Create an AWS Lambda Compute Platform Deployment (Console), Create an Application for an AWS Lambda Function Deployment (Console), and Add an AppSpec File for an AWS Lambda Deployment.

November 28, 2017

New topic

CodeDeploy now supports deployments directly to a local machine or instance where the CodeDeploy Agent is installed. You can locally test a deployment and, if it has errors, use CodeDeploy Agent error logs to debug them. You can also use a local deployment to test the integrity of an application revision, the contents of an AppSpec file, and more. For more information, see Use the CodeDeploy Agent to Validate a Deployment Package on a Local Machine.

November 16, 2017

Updated topics

CodeDeploy support for Elastic Load Balancing load balancers in deployment groups has been expanded to include Network Load Balancers for both blue/green deployments and in-place deployments. You can now choose an Application Load Balancer, Classic Load Balancer, or Network Load Balancer for your deployment group. Load balancers are required for blue/green deployments and optional for in-place deployments. A number of topics have been updated to reflect this support, including Integrating CodeDeploy with Elastic Load Balancing, Create an Application for an In-Place Deployment (Console), Deployment Prerequisites, Integrating CodeDeploy with Elastic Load Balancing, and Create an Application for an In-Place Deployment (Console).

September 12, 2017

Updated topics

CodeDeploy support for Elastic Load Balancing load balancers in deployment groups has been expanded to include Application Load Balancers for both blue/green deployments and in-place deployments. You can now choose between an Application Load Balancer and a Classic Load Balancer for your deployment group. Load balancers are required for blue/green deployments, and optional for in-place deployments. Topics including Integrating CodeDeploy with Elastic Load Balancing, Create an Application with CodeDeploy, and Create a Deployment Group with CodeDeploy have been updated to reflect this additional support.

August 10, 2017

New and updated topics CodeDeploy now supports using multiple tag groups to identify unions and intersections of instances to be included in a deployment group. If you use a single tag group, any instance identified by at least one tag in the group is included in the deployment group. If you use multiple tag groups, only instances that are identified by at least one tag in each of the tag groups are included. For information about the new method for adding instances to a deployment group, see Tagging Instances for AWS CodeDeploy Deployments. Other topics updated to reflect this support include Create an Application for an In-Place Deployment (Console), Create an Application for a Blue/Green Deployment (Console), Create a Deployment Group for an In-Place Deployment (Console), Create a Deployment Group for an EC2/On-Premises Blue/Green Deployment (Console), Deployments, and Step 5: Create an Application and Deployment Group in Tutorial: Use CodeDeploy to Deploy an Application from GitHub. July 31, 2017
Updated topic Two additional methods for installing the CodeDeploy agent on Windows Server instances have been added to Install or reinstall the CodeDeploy agent for Windows Server. In addition to Windows PowerShell commands, instructions are now available for downloading the installation file by using a direct HTTPS link and by using an Amazon S3 copy command. After the file is downloaded or copied to an instance, you can run the installation manually. July 12, 2017
Updated topics

CodeDeploy has improved how it manages connections to GitHub accounts and repositories. You can now create and store up to 25 connections to GitHub accounts in order to associate CodeDeploy applications with GitHub repositories. Each connection can support multiple repositories. You can create connections to up to 25 different GitHub accounts, or create more than one connection to a single account. After you connect an application to a GitHub account, CodeDeploy manages the required access permissions without requiring any further action from you. Updates to reflect this support have been made to Specify Information About a Revision Stored in a GitHub Repository, Integrating CodeDeploy with GitHub, and Tutorial: Use CodeDeploy to Deploy an Application from GitHub.

May 30, 2017
Updated topics

In the past, if the CodeDeploy agent detected files in a target location that weren't part of the application revision from the most recent successful deployment, it would fail the current deployment by default. CodeDeploy now provides options for how the agent handles these files: fail the deployment, retain the content, or overwrite the content. Create a Deployment with CodeDeploy was updated to reflect this support, and the new section Rollback Behavior with Existing Content was added to Redeploy and Roll Back a Deployment with CodeDeploy.

May 16, 2017
Updated topics

A Classic Load Balancer in Elastic Load Balancing can now be assigned to a deployment group using the CodeDeploy console or AWS CLI. During an in-place deployment, a load balancer prevents internet traffic from being routed to an instance while it is being deployed to, and then makes the instance available for traffic again once the deployment to that instance completes. Several topics were updated to reflect this new support, including Integration with Other AWS Services, Integrating CodeDeploy with Elastic Load Balancing, Create an Application for an In-Place Deployment (Console), Create a Deployment Group for an In-Place Deployment (Console), and AppSpec 'hooks' Section. A new section was added to the troubleshooting guide, Troubleshooting failed ApplicationStop, BeforeBlockTraffic, and AfterBlockTraffic deployment lifecycle events.

April 27, 2017
Updated topics

A Classic Load Balancer in Elastic Load Balancing can now be assigned to a deployment group using the CodeDeploy console or AWS CLI. During an in-place deployment, a load balancer prevents internet traffic from being routed to an instance while it is being deployed to, and then makes the instance available for traffic again once the deployment to that instance completes. Several topics were updated to reflect this new support, including Integration with Other AWS Services, Integrating CodeDeploy with Elastic Load Balancing, Create an Application for an In-Place Deployment (Console), Create a Deployment Group for an In-Place Deployment (Console), and AppSpec 'hooks' Section. A new section was added to the troubleshooting guide, Troubleshooting failed ApplicationStop, BeforeBlockTraffic, and AfterBlockTraffic deployment lifecycle events.

May 1, 2017
Updated topics

CodeDeploy is now available in the China (Beijing) Region.

To use services in the China (Beijing) Region or China (Ningxia) Region, you must have an account and credentials for those regions. Accounts and credentials for other AWS regions do not work for the Beijing and Ningxia Regions, and vice versa.

Information about some resources for the China Regions, such as CodeDeploy Resource Kit bucket names and CodeDeploy agent installation procedures, are not included in this edition of the CodeDeploy User Guide.

For more information:

March 29, 2017
New and updated topics

Several new topics have been introduced to reflect new CodeDeploy support for blue/green deployments, a deployment method in which the instances in a deployment group (the original environment) are replaced by a different set of instances (the replacement environment). Overview of a Blue/Green Deployment provides a high-level explanation of the blue/green methodology used by CodeDeploy. Additional new topics include Create an Application for a Blue/Green Deployment (Console). Create a Deployment Group for an EC2/On-Premises Blue/Green Deployment (Console), and Set Up a Load Balancer in Elastic Load Balancing for CodeDeploy Deployments.

Numerous topics have been updated as well, including Create a Deployment with CodeDeploy, Working with Deployment Configurations in CodeDeploy, Create an Application with CodeDeploy, Working with Deployment Groups in CodeDeploy , Working with Deployments in CodeDeploy, and AppSpec 'hooks' Section.

January 25, 2017
New and updated topics A new topic, Use the register-on-premises-instance Command (IAM Session ARN) to Register an On-Premises Instance , describes how to authenticate and register on-premises instances using periodically refreshed temporary credentials generated through AWS Security Token Service. This approach provides better support for supporting large fleets of on-premises instances than using only a static IAM user's credentials on each instance. Working with On-Premises Instances has also been updated to reflect this new support. December 28, 2016
Updated topics CodeDeploy is now available in the EU (London) Region (eu-west-2). Several topics, including those containing instructions for setting up the CodeDeploy agent, were updated to reflect the availability of this new region. December 13, 2016
Updated topics CodeDeploy is now available in the Canada (Central) Region (ca-central-1). Several topics, including those containing instructions for setting up the CodeDeploy agent, were updated to reflect the availability of this new region. December 8, 2016
Updated topics CodeDeploy is now available in the US East (Ohio) Region (us-east-2). Several topics, including those containing instructions for setting up the CodeDeploy agent, were updated to reflect the availability of this new region. October 17, 2016
New topics A new section, Authentication and Access Control for AWS CodeDeploy, provides comprehensive information about using AWS Identity and Access Management (IAM) and CodeDeploy to help secure access to your resources through the use of credentials. These credentials provide the permissions required to access AWS resources, such as retrieving application revisions from Amazon S3 buckets and reading the tags on Amazon EC2 instances. October 11, 2016
Updated topic

Update the CodeDeploy Agent on Windows Server has been updated to reflect the availability of the new CodeDeploy agent updater for Windows Server. When installed on a Windows Server instance, the updater will check periodically for new versions. When a new version is detected, the updater will uninstall the current version of the agent, if one is installed, before installing the newest version.

October 4, 2016
Updated topics

CodeDeploy now integrates with Amazon CloudWatch alarms, making it possible to stop a deployment if there is a change in the state of a specified alarm for a number of consecutive periods, as specified in the alarm threshold.

CodeDeploy also now supports automatically rolling back a deployment if certain conditions are met, such as a deployment failure or an activated alarm.

A number of topics have been updated to reflect these changes, including Create an Application with CodeDeploy, Create a Deployment Group with CodeDeploy, Change Deployment Group Settings with CodeDeploy, Deployments, Redeploy and Roll Back a Deployment with CodeDeploy, and Product and Service Integrations with CodeDeploy, along with a new topic, Monitoring Deployments with CloudWatch Alarms in CodeDeploy.

September 15, 2016
New and updated topics

CodeDeploy now provides integration with Amazon CloudWatch Events. You can now use CloudWatch Events to initiate one or more actions when changes are detected in the state of a deployment or the state of an instance that belongs to a CodeDeploy deployment group. You can incorporate actions that invoke AWS Lambda functions; that publish to Kinesis streams or Amazon SNS topics; that push messages to Amazon SQS queues; or that, in turn, trigger CloudWatch alarm actions. For more information, see Monitoring Deployments with Amazon CloudWatch Events.

September 9, 2016
Topic updates The topics Integrating CodeDeploy with Elastic Load Balancing and Integration with Other AWS Services have been updated to reflect an additional load balancing option. CodeDeploy now supports the Classic Load Balancer and Application Load Balancer available in Elastic Load Balancing. August 11, 2016
Topic updates CodeDeploy is now available in the Asia Pacific (Mumbai) Region (ap-south-1). Several topics, including those containing instructions for setting up the CodeDeploy agent, were updated to reflect the availability of this new region. June 27, 2016
Topic updates

CodeDeploy is now available in the Asia Pacific (Seoul) Region (ap-northeast-2). Several topics, including those containing instructions for setting up the CodeDeploy agent, were updated to reflect the availability of this new region.

The table of contents has been reorganized to include sections for instances, deployment configurations, applications, deployment groups, revisions, and deployments. A new section has been added for CodeDeploy tutorials. For better usability, several long topics, including CodeDeploy AppSpec File Reference and Troubleshooting CodeDeploy, have been divided into shorter topics. Configuration information for the CodeDeploy agent has been moved to a new topic, CodeDeploy Agent Configuration Reference.

June 15, 2016
New and updated topics

Error Codes for AWS CodeDeploy provides information about some of the error messages that might be displayed when CodeDeploy deployments fail.

The following sections in Troubleshooting CodeDeploy were updated to better assist with resolving deployment problems:
April 20, 2016
Topic updates

CodeDeploy is now available in the South America (São Paulo) Region (sa-east-1). Several topics, including those containing instructions for setting up the CodeDeploy agent, were updated to reflect the availability of this new region.

Working with the CodeDeploy Agent was updated to reflect the new :max_revisions: configuration option, which you use to specify the number of application revisions for a deployment group that you want the CodeDeploy agent to archive.

March 10, 2016
New and updated topics

CodeDeploy now supports adding triggers to a deployment group to receive notifications about events related to deployments or instances in that deployment group. These notifications are sent to recipients who are subscribed to an Amazon Simple Notification Service topic you have made part of the trigger's action. You can also use JSON data that is created when a trigger is fired in your own customized notification workflow. For more information, see Monitoring Deployments with Amazon SNS Event Notifications.

Procedures were updated to reflect the redesign of the Application details page.

The Deployments do not fail for up to an hour when an instance is terminated during a deployment section in Troubleshooting CodeDeploy has been updated.

CodeDeploy Limits was updated to reflect revised limits for the number of deployment groups that can be associated with a single application; the allowed values for minimum healthy instances settings; and required versions of the AWS SDK for Ruby (aws-sdk-core).

February 17, 2016
New and updated topics

CodeDeploy is now available in the US West (N. California) region (us-west-1). Several topics, including those containing instructions for setting up the CodeDeploy agent, were updated to reflect the addition of this new region.

Choose a CodeDeploy Repository Type lists and describes the repository types now supported by CodeDeploy. This new topic will be updated as support for other repository types is introduced.

Managing CodeDeploy Agent Operations was updated with information about the new .version file added to instances to report the current version of the CodeDeploy agent, as well as information about supported versions of the agent.

Syntax highlighting for code samples, including JSON and YAML examples, has been added to the user guide.

Add an Application Specification File to a Revision for CodeDeploy has been reorganized as step-by-step instructions.

January 20, 2016
New topic Deploy an Application in a Different AWS Account describes the setup requirements and process for initiating deployments that belong to another of your organization’s accounts, without needing a full set of credentials for that other account. This is most useful for organizations that use multiple accounts for different purposes, such as one associated with development and test environments and another associated with the production environment. December 30, 2015
Topic update The Product and Service Integrations with CodeDeploy topic has been redesigned. It now includes a section for integration examples from the community, with lists of blog posts and video examples related to CodeDeploy integrations. December 16, 2015
Topic updates CodeDeploy is now available in the Asia Pacific (Singapore) Region (ap-southeast-1). Several topics, including those containing instructions for setting up the CodeDeploy agent, were updated to reflect the availability of this new region. December 9, 2015
Topic updates

Working with the CodeDeploy Agent was updated to reflect the new :proxy_uri: option in the CodeDeploy agent configuration file.

CodeDeploy AppSpec File Reference was updated with information about using a new environment variable, DEPLOYMENT_GROUP_ID, which hook scripts can access during a deployment lifecycle event.
December 1, 2015
Topic update Step 3: Create a Service Role for CodeDeploy was updated to reflect a new procedure for creating a service role for CodeDeploy and to incorporate other improvements. November 13, 2015
Topic updates CodeDeploy is now available in the EU (Frankfurt) Region (eu-central-1). Several topics, including those containing instructions for setting up the CodeDeploy agent, were updated to reflect the availability of this new region.

The Troubleshooting CodeDeploy topic was updated with information about ensuring that time settings on instances are accurate.

October 19, 2015
New topics AWS CloudFormation Templates for CodeDeploy Reference was published to reflect new AWS CloudFormation support for CodeDeploy actions.

Created a Primary Components topic and introduced definition of a target revision.

October 1, 2015
Topic updates Create a Deployment Group with CodeDeploy was updated to reflect the ability to locate instances for a deployment group using wildcard searches.

Instance Health was updated to clarify the concept of minimum healthy instances.

August 31, 2015
Topic updates CodeDeploy is now available in the Asia Pacific (Tokyo) Region (ap-northeast-1). Several topics, including those containing instructions for setting up the CodeDeploy agent, were updated to reflect the availability of this new region. August 19, 2015
Topic updates

CodeDeploy now supports deployments to Red Hat Enterprise Linux (RHEL) on-premises instances and Amazon EC2 instances. For more information, see the following topics:

June 23, 2015
Topic update

CodeDeploy now provides a set of environment variables your deployment scripts can use during deployments. These environment variables include information such as the name of the current CodeDeploy application, deployment group, and deployment lifecycle event, as well as the current CodeDeploy deployment identifier. For more information, see the end of the AppSpec 'hooks' Section section in the CodeDeploy AppSpec File Reference.

May 29, 2015
Topic updates

CodeDeploy now provides a set of AWS managed policies in IAM that you can use instead of manually creating the equivalent policies on your own. These include:

  • A policy for enabling an IAM user to register revisions with CodeDeploy only and then deploy them through CodeDeploy.

  • A policy for providing an IAM user with full access to CodeDeploy resources.

  • A policy for providing an IAM user with read-only access to CodeDeploy resources.

  • A policy to attach to a service role so that CodeDeploy can identify Amazon EC2 instances by their Amazon EC2 tags, on-premises instance tags, or Amazon EC2 Auto Scaling group names and deploy application revisions to them accordingly.

For more information, see the Customer Managed Policy Examples section in Authentication and Access Control for AWS CodeDeploy.

May 29, 2015
Topic updates CodeDeploy is now available in the EU (Ireland) Region (eu-west-1) and the Asia Pacific (Sydney) Region (ap-southeast-2). Several topics, including those containing instructions for setting up the CodeDeploy agent, were updated to reflect the availability of these new regions. May 7, 2015
New topics

CodeDeploy now supports deployments to on-premises instance and Amazon EC2 instances. The following topics were added to describe this new support:

April 2, 2015
New topic

CodeDeploy Resources was added.

April 2, 2015
Topic update

Troubleshooting CodeDeploy was updated:

April 2, 2015
Topic updates

The following topics were updated to reflect new recommendations for creating your own custom policies and then attaching them to users and roles in IAM:

Two sections were added to Troubleshooting CodeDeploy:

The AppSpec 'hooks' Section section in the CodeDeploy AppSpec File Reference was updated to more accurately describe the available deployment lifecycle events.

February 12, 2015
Topic updates

A new section was added to Troubleshooting CodeDeploy: Amazon EC2 instances in an Amazon EC2 Auto Scaling group fail to launch and receive the error "Heartbeat Timeout".

A CloudBees section was added to Product and Service Integrations with CodeDeploy.

January 28, 2015
Topic updates

The following sections were added to Troubleshooting CodeDeploy:

January 20, 2015
New topics

The Product and Service Integrations with CodeDeploy section was updated to include the following topics:

January 9, 2015
Topic updates
January 8, 2015
New topic Monitoring Deployments with AWS CloudTrail was added. CodeDeploy is integrated with AWS CloudTrail, a service that captures API calls made by or on behalf of CodeDeploy in your AWS account and delivers the log files to an Amazon S3 bucket that you specify. December 17, 2014

Initial public release

This is the initial public release of the CodeDeploy User Guide.

November 12, 2014

On this page: