• Step 8: Clean up (p. 127)
Prerequisites
Before you start this tutorial, do the following:
• Install Git on your local machine. To install Git, see Git downloads.
• Complete the steps in Getting started with CodeDeploy (p. 31), including installing and configuring the AWS CLI. This is especially important if you want to use the AWS CLI to deploy a revision from GitHub to the instance.
Step 1: Set up a GitHub account
You will need a GitHub account to create a GitHub repository where the revision will be stored. If you already have a GitHub account, skip ahead to Step 2: Create a GitHub repository (p. 117).
1. Go to https://github.com/join.
2. Type a user name, your email address, and a password.
3. Choose Sign up for GitHub, and then follow the instructions.
Step 2: Create a GitHub repository
You will need a GitHub repository to store the revision.
If you already have a GitHub repository, be sure to substitute its name for CodeDeployGitHubDemo throughout this tutorial, and then skip ahead to Step 3: Upload a sample application to your GitHub repository (p. 119).
1. On the GitHub home page, do one of the following:
• In Your repositories, choose New repository.
• On the navigation bar, choose Create new (+), and then choose New repository.
Step 2: Create a GitHub repository
2. In the Create a new repository page, do the following:
• In the Repository name box, enter CodeDeployGitHubDemo.
• Select Public.
NoteSelecting the default Public option means that anyone can see this repository. You can select the Private option to limit who can see and commit to the repository.
• Clear the Initialize this repository with a README check box. You will create a README.md file manually in the next step instead.
• Choose Create repository.
3. Follow the instructions for your local machine type to use the command line to create the repository.
NoteIf you have enabled two-factor authentication on GitHub, make sure you enter your personal access token instead of your GitHub login password if prompted for a password.
For information, see Providing your 2FA authentication code.
On local Linux, macOS, or Unix machines:
1. From the terminal, run the following commands, one at a time, where user-name is your GitHub user name:
mkdir /tmp/CodeDeployGitHubDemo
cd /tmp/CodeDeployGitHubDemo
touch README.md
git init
git add README.md
git commit -m "My first commit"
git remote add origin https://github.com/user-name/CodeDeployGitHubDemo.git
git push -u origin master
2. Leave the terminal open in the /tmp/CodeDeployGitHubDemo location.
On local Windows machines:
1. From a command prompt running as an administrator, run the following commands, one at a time:
Step 3: Upload a sample application to your GitHub repository
notepad README.md
2. In Notepad, save the README.md file. Close Notepad. Run the following commands, one at a time, where user-name is your GitHub user name:
git init
git add README.md
git commit -m "My first commit"
git remote add origin https://github.com/user-name/CodeDeployGitHubDemo.git
git push -u origin master
3. Leave the command prompt open in the c:\temp\CodeDeployGitHubDemo location.
Step 3: Upload a sample application to your GitHub repository
In this step, you will copy a sample revision from a public Amazon S3 bucket to your GitHub repository.
(For simplicity, the sample revisions provided for this tutorial are single web pages.) NoteIf you use one of your revisions instead of our sample revision, your revision must:
• Follow the guidelines in Plan a revision for CodeDeploy (p. 283) and Add an application specification file to a revision for CodeDeploy (p. 284).
• Work with the corresponding instance type.
• Be accessible from your GitHub dashboard.
If your revision meets these requirements, skip ahead to Step 5: Create an application and deployment group (p. 122).
If you're deploying to an Ubuntu Server instance, you'll need to upload to your GitHub repository a revision compatible with an Ubuntu Server instance and CodeDeploy. For more information, see Plan a revision for CodeDeploy (p. 283) and Add an application specification file to a revision for CodeDeploy (p. 284).
Topics
• Push a sample revision from a local Linux, macOS, or Unix machine (p. 119)
• Push a sample revision from a local Windows machine (p. 121)
Push a sample revision from a local Linux, macOS, or Unix machine
With your terminal still open in, for example, the /tmp/CodeDeployGitHubDemo location, run the following commands one at a time:
Step 3: Upload a sample application to your GitHub repository
NoteIf you plan to deploy to a Windows Server instance, substitute SampleApp_Windows.zip for SampleApp_Linux.zip in the commands.
(Amazon S3 copy command)
unzip SampleApp_Linux.zip
rm SampleApp_Linux.zip
git add .
git commit -m "Added sample app"
git push
Where (Amazon S3 copy command) is one of the following:
• aws s3 cp s3://aws-codedeploy-us-east-2/samples/latest/SampleApp_Linux.zip . --region us-east-2 for the US East (Ohio) region
• aws s3 cp s3://aws-codedeploy-us-east-1/samples/latest/SampleApp_Linux.zip . --region us-east-1 for the US East (N. Virginia) region
• aws s3 cp s3://aws-codedeploy-us-west-1/samples/latest/SampleApp_Linux.zip . --region us-west-1 for the US West (N. California) Region
• aws s3 cp s3://aws-codedeploy-us-west-2/samples/latest/SampleApp_Linux.zip . --region us-west-2 for the US West (Oregon) region
• aws s3 cp s3://aws-codedeploy-ca-central-1/samples/latest/
SampleApp_Linux.zip . --region ca-central-1 for the Canada (Central) Region
• aws s3 cp s3://aws-codedeploy-eu-west-1/samples/latest/SampleApp_Linux.zip . --region eu-west-1 for the Europe (Ireland) region
• aws s3 cp s3://aws-codedeploy-eu-west-2/samples/latest/SampleApp_Linux.zip . --region eu-west-2 for the Europe (London) region
• aws s3 cp s3://aws-codedeploy-eu-west-3/samples/latest/SampleApp_Linux.zip . --region eu-west-3 for the Europe (Paris) region
• aws s3 cp s3://aws-codedeploy-eu-central-1/samples/latest/
SampleApp_Linux.zip . --region eu-central-1 for the Europe (Frankfurt) Region
• aws s3 cp s3://aws-codedeploy-ap-east-1/samples/latest/SampleApp_Linux.zip . --region ap-east-1 for the Asia Pacific (Hong Kong) region
• aws s3 cp s3://aws-codedeploy-ap-northeast-1/samples/latest/
SampleApp_Linux.zip . --region ap-northeast-1 for the Asia Pacific (Tokyo) region
• aws s3 cp s3://aws-codedeploy-ap-northeast-2/samples/latest/
SampleApp_Linux.zip . --region ap-northeast-2 for the Asia Pacific (Seoul) region
• aws s3 cp s3://aws-codedeploy-ap-southeast-1/samples/latest/
SampleApp_Linux.zip . --region ap-southeast-1 for the Asia Pacific (Singapore) Region
• aws s3 cp s3://aws-codedeploy-ap-southeast-2/samples/latest/
Step 3: Upload a sample application to your GitHub repository
• aws s3 cp s3://aws-codedeploy-sa-east-1/samples/latest/SampleApp_Linux.zip . --region sa-east-1 for the South America (São Paulo) Region
Push a sample revision from a local Windows machine
With your command prompt still open in, for example, the c:\temp\CodeDeployGitHubDemo location , run the following commands one at a time:
NoteIf you plan to deploy to an Amazon Linux or RHEL instance, substitute SampleApp_Linux.zip for SampleApp_Windows.zip in the commands.
(Amazon S3 copy command)
Unzip the contents of the the ZIP file directly into the local directory (for example c:\temp
\CodeDeployGitHubDemo), not into a new subdirectory.
git add .
git commit -m "Added sample app"
git push
Where (Amazon S3 copy command) is one of the following:
• aws s3 cp s3://aws-codedeploy-us-east-2/samples/latest/
SampleApp_Windows.zip . --region us-east-2 for the US East (Ohio) region
• aws s3 cp s3://aws-codedeploy-us-east-1/samples/latest/
SampleApp_Windows.zip . --region us-east-1 for the US East (N. Virginia) region
• aws s3 cp s3://aws-codedeploy-us-west-1/samples/latest/
SampleApp_Windows.zip . --region us-west-1 for the US West (N. California) Region
• aws s3 cp s3://aws-codedeploy-us-west-2/samples/latest/
SampleApp_Windows.zip . --region us-west-2 for the US West (Oregon) region
• aws s3 cp s3://aws-codedeploy-ca-central-1/samples/latest/
SampleApp_Windows.zip . --region ca-central-1 for the Canada (Central) Region
• aws s3 cp s3://aws-codedeploy-eu-west-1/samples/latest/
SampleApp_Windows.zip . --region eu-west-1 for the Europe (Ireland) region
• aws s3 cp s3://aws-codedeploy-eu-west-2/samples/latest/
SampleApp_Windows.zip . --region eu-west-2 for the Europe (London) region
• aws s3 cp s3://aws-codedeploy-eu-west-3/samples/latest/
SampleApp_Windows.zip . --region eu-west-3 for the Europe (Paris) region
• aws s3 cp s3://aws-codedeploy-eu-central-1/samples/latest/
SampleApp_Windows.zip . --region eu-central-1 for the Europe (Frankfurt) Region
• aws s3 cp s3://aws-codedeploy-ap-east-1/samples/latest/
SampleApp_Windows.zip . --region ap-east-1 for the Asia Pacific (Hong Kong) region
• aws s3 cp s3://aws-codedeploy-ap-northeast-1/samples/latest/
SampleApp_Windows.zip . --region ap-northeast-1 for the Asia Pacific (Tokyo) region
• aws s3 cp s3://aws-codedeploy-ap-northeast-2/samples/latest/
SampleApp_Windows.zip . --region ap-northeast-2 for the Asia Pacific (Seoul) region
• aws s3 cp s3://aws-codedeploy-ap-southeast-1/samples/latest/
SampleApp_Windows.zip . --region ap-southeast-1 for the Asia Pacific (Singapore) Region
Step 4: Provision an instance
• aws s3 cp s3://aws-codedeploy-ap-southeast-2/samples/latest/
SampleApp_Windows.zip . --region ap-southeast-2 for the Asia Pacific (Sydney) region
• aws s3 cp s3://aws-codedeploy-ap-south-1/samples/latest/
SampleApp_Windows.zip . --region ap-south-1 for the Asia Pacific (Mumbai) region
• aws s3 cp s3://aws-codedeploy-sa-east-1/samples/latest/
SampleApp_Windows.zip . --region sa-east-1 for the South America (São Paulo) Region
To push your own revision to an Ubuntu Server instance, copy your revision into your local repo, and then call the following:
git add .
git commit -m "Added Ubuntu app"
git push
Step 4: Provision an instance
In this step, you will create or configure the instance that you will deploy the sample application to. You can deploy to an Amazon EC2 instance or an on-premises instance that is running one of the operating systems supported by CodeDeploy. For information see Operating systems supported by the CodeDeploy agent (p. 161). (If you already have an instance configured for use in CodeDeploy deployments, skip to the next step.)
To provision an instance
1. Follow the instructions in Launch an Amazon EC2 instance (console) (p. 201) to provision an instance.
2. When launching the instance, remember to specify a tag on the Add tags page. For details on how to specify the tag, see Launch an Amazon EC2 instance (console) (p. 201).
To verify that the CodeDeploy agent is running on the instance
• Follow the instructions in Verify the CodeDeploy agent is running (p. 171) to verify that the agent is running.
After you have successfully provisioned the instance and verified the CodeDeploy agent is running, go to the next step.
Step 5: Create an application and deployment group
In this step, you will use the CodeDeploy console or the AWS CLI to create an application and deployment group to use to deploy the sample revision from your GitHub repository.
Create an application and deployment group (console)
1. Sign in to the AWS Management Console and open the CodeDeploy console at https://
console.aws.amazon.com/codedeploy.
NoteSign in with the same account or IAM user information that you used in Getting started with
Step 5: Create an application and deployment group
3. Choose Create application, and then select Custom application.
4. In Application name, enter CodeDeployGitHubDemo-App.
5. In Compute Platform, choose EC2/On-premises.
6. Choose Create application.
7. On the Deployment groups tab, choose Create deployment group.
8. In Deployment group name, enter CodeDeployGitHubDemo-DepGrp.
9. In Service role, choose the name of your CodeDeploy service role that you created in Create a service role for CodeDeploy (p. 31).
10. In Deployment type, choose In-place.
11. In Environment configuration, depending on the type of instance you are using, choose Amazon EC2 instances or On-premises instances. For Key and Value, enter the instance tag key and value that was applied to your instance as part of Step 4: Provision an instance (p. 122).
12. In Deployment configuration, choose CodeDeployDefault.AllatOnce.
13. In Load Balancer, clear Enable load balancing.
14. Expand Advanced.
15. In Alarms, select Ignore alarm configuration.
16. Choose Create deployment group, and continue to the next step.
Create an application and deployment group (CLI)
1. Call the create-application command to create an application in CodeDeploy named CodeDeployGitHubDemo-App:
aws deploy create-application --application-name CodeDeployGitHubDemo-App 2. Call the create-deployment-group command to create a deployment group named
CodeDeployGitHubDemo-DepGrp:
• If you're deploying to an Amazon EC2 instance, ec2-tag-key is the Amazon EC2 instance tag key that was applied to your Amazon EC2 instance as part of Step 4: Provision an instance (p. 122).
• If you're deploying to an Amazon EC2 instance, ec2-tag-value is the Amazon EC2 instance tag value that was applied to your Amazon EC2 instance as part of Step 4: Provision an instance (p. 122).
• If you're deploying to an on-premises instance, on-premises-tag-key is the on-premises instance tag key that was applied to your on-premises instance as part of Step 4: Provision an instance (p. 122).
• If you're deploying to an on-premises instance, on-premises-tag-value is the on-premises instance tag value that was applied to your on-premises instance as part of Step 4: Provision an instance (p. 122).
• service-role-arn is the service role ARN for the service role that you created in Create a service role for CodeDeploy (p. 31). (Follow the instructions in Get the service role ARN (CLI) (p. 36) to find the service role ARN.)
aws deploy create-deployment-group application-name CodeDeployGitHubDemo-App --ec2-tag-filters Key=ec2-tag-key,Type=KEY_AND_VALUE,Value=ec2-tag-value on-premises-tag-filters Key=on-premises-tag-key,Type=KEY_AND_VALUE,Value=on-premises-tag-value --deployment-group-name CodeDeployGitHubDemo-DepGrp --service-role-arn service-role-arn
Note
The create-deployment-group command provides support for creating triggers that result in the sending of Amazon SNS notifications to topic subscribers about specified events in
Step 6: Deploy the application to the instance
deployments and instances. The command also supports options for automatically rolling back deployments and setting up alarms to stop deployments when monitoring thresholds in Amazon CloudWatch alarms are met. Commands for these actions are not included in this tutorial.
Step 6: Deploy the application to the instance
In this step, you use the CodeDeploy console or the AWS CLI to deploy the sample revision from your GitHub repository to your instance.
To deploy the revision (console)
1. On the Deployment group details page, choose Create deployment.
2. In Deployment group, choose CodeDeployGitHubDemo-DepGrp.
3. In Revision type, choose GitHub.
4. In Connect to GitHub, do one of the following:
• To create a connection for CodeDeploy applications to a GitHub account, sign out of GitHub in a separate web browser tab. In GitHub account, enter a name to identify this connection, and then choose Connect to GitHub. The webpage prompts you to authorize CodeDeploy to interact with GitHub for the application named CodeDeployGitHubDemo-App. Continue to step 5.
• To use a connection you have already created, in GitHub account, select its name, and then choose Connect to GitHub. Continue to step 7.
• To create a connection to a different GitHub account, sign out of GitHub in a separate web
browser tab. Choose Connect to a different GitHub account, and then choose Connect to GitHub.
Continue to step 5.
5. Follow the instructions on the Sign in page to sign in with your GitHub account.
6. On the Authorize application page, choose Authorize application.
7. On the CodeDeploy Create deployment page, in Repository name, enter the GitHub user name you used to sign in, followed by a forward slash (/), followed by the name of the
repository where you pushed your application revision (for example, my-github-user-name/
CodeDeployGitHubDemo).
If you are unsure of the value to enter, or if you want to specify a different repository:
a. In a separate web browser tab, go to your GitHub dashboard.
b. In Your repositories, hover your mouse pointer over the target repository name. A tooltip appears, displaying the GitHub user or organization name, followed by a forward slash (/), followed by the name of the repository. Enter this value into Repository name.
NoteIf the target repository name is not displayed in Your repositories, use the Search GitHub box to find the target repository and GitHub user or organization name.
8. In the Commit ID box, enter the ID of the commit associated with the push of your application revision to GitHub.
If you are unsure of the value to enter:
Step 6: Deploy the application to the instance
and numbers. (Do not use the shorter version of the commit ID, which is typically the first 10 characters of the longer version.)
d. Paste the commit ID into the Commit ID box.
9. Choose Deploy, and continue to the next step.
To deploy the revision (CLI)
Before you can call any AWS CLI commands that interact with GitHub (such as the create-deployment command, which you will call next), you must give CodeDeploy permission to use your GitHub user account to interact with GitHub for the CodeDeployGitHubDemo-App application. Currently, you must use the CodeDeploy console to do this.
1. Sign in to the AWS Management Console and open the CodeDeploy console at https://
console.aws.amazon.com/codedeploy.
NoteSign in with the same account or IAM user information that you used in Getting started with CodeDeploy (p. 31).
2. In the navigation pane, expand Deploy, then choose Applications.
3. Choose CodeDeployGitHubDemo-App.
4. On the Deployments tab, choose Create deployment.
NoteYou will not be creating a new deployment. This is currently the only way to give CodeDeploy permission to interact with GitHub on behalf of your GitHub user account.
5. From Deployment group, choose CodeDeployGitHubDemo-DepGrp.
6. In Revision type, choose GitHub.
7. In Connect to GitHub, do one of the following:
• To create a connection for CodeDeploy applications to a GitHub account, sign out of GitHub in a separate web browser tab. In GitHub account, type a name to identify this connection, and then choose Connect to GitHub. The web page prompts you to authorize CodeDeploy to interact with GitHub for the application named CodeDeployGitHubDemo-App. Continue to step 8.
• To use a connection you have already created, in GitHub account, select its name, and then choose Connect to GitHub. Continue to step 10.
• To create a connection to a different GitHub account, sign out of GitHub in a separate web
browser tab. Choose Connect to a different GitHub account, and then choose Connect to GitHub.
Continue to step 8.
8. Follow the instructions on the Sign in page to sign in with your GitHub user name or email and password.
9. On the Authorize application page, choose Authorize application.
10. On the CodeDeploy Create deployment page, choose Cancel.
11. Call the create-deployment command to deploy the revision from your GitHub repository to the instance, where:
• repository is your GitHub account name, followed by a forward-slash (/), followed by the name of your repository (CodeDeployGitHubDemo), for example, MyGitHubUserName/
CodeDeployGitHubDemo.
If you are unsure of the value to use, or if you want to specify a different repository:
1. In a separate web browser tab, go to your GitHub dashboard.
Step 7: Monitor and verify the deployment
2. In Your repositories, hover your mouse pointer over the target repository name. A tooltip appears, displaying the GitHub user or organization name, followed by a forward slash (/), followed by the name of the repository. This is the value to use.
NoteIf the target repository name does not appear in Your repositories, use the Search GitHub box to find the target repository and corresponding GitHub user or organization name.
• commit-id is the commit associated with the version of the application revision you pushed to your repository (for example, f835159a...528eb76f).
If you are unsure of the value to use:
1. In a separate web browser tab, go to your GitHub dashboard.
2. In Your repositories, choose CodeDeployGitHubDemo.
3. In the list of commits, find the commit ID associated with the push of your application revision to GitHub. This ID is typically 40 characters in length and consists of both letters and numbers. (Do not use the shorter version of the commit ID, which is typically the first 10
3. In the list of commits, find the commit ID associated with the push of your application revision to GitHub. This ID is typically 40 characters in length and consists of both letters and numbers. (Do not use the shorter version of the commit ID, which is typically the first 10