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

Tutorial: Deploy an Application from GitHub Using AWS CodeDeploy

In this tutorial, you'll use AWS CodeDeploy to deploy a sample application revision from GitHub to a single Amazon EC2 instance running Amazon Linux, a single Red Hat Enterprise Linux (RHEL) instance, or a single Windows Server instance. For information about GitHub integration with AWS CodeDeploy, see GitHub.

Note

You can also use AWS CodeDeploy to deploy an application revision from GitHub to an Ubuntu Server instance. You can use the sample revision described in Step 2: Create a Sample Application Revision in Tutorial: Deploy an Application to an On-Premises Instance, or you can create a revision compatible with an Ubuntu Server instance and AWS CodeDeploy. To create your own revision, see Plan a Revision and Add an AppSpec File.

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, 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.

  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.

  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.

  2. In the Create a new repository page, do the following:

    • In the Repository name box, type CodeDeployGitHubDemo.

    • Select Public.

      Note

      Selecting the default Public option means that anyone can see this repository. Although you can select the Private option to limit who can see and commit to the repository, this option may result in additional charges from GitHub.

    • 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 to use the command line to create the repository.

    Tip

    If 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.

    For Linux, OS X, or Unix:

    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 command prompt open in the /tmp/CodeDeployGitHubDemo location.

    For Windows:

    1. From a command prompt running as an administrator, run the following commands, one at a time:

      mkdir c:\temp\CodeDeployGitHubDemo
      cd c:\temp\CodeDeployGitHubDemo
      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.

Note

If you use one of your revisions instead of our sample revision, your revision must:

If your revision meets these requirements, skip ahead to Step 5: Deploy the Application to the Instance.

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 AWS CodeDeploy. For more information, see Plan a Revision and Add an AppSpec File.

With your terminal or administrative command prompt still open in, for example, the /tmp/CodeDeployGitHubDemo location (for Linux, OS X, or Unix) or c:\temp\CodeDeployGitHubDemo (for Windows), run the following commands, one at a time:

To push our sample revision to an Amazon EC2 instance running Amazon Linux or RHEL:

(Amazon S3 copy command)
git add SampleApp_Linux.zip
git commit -m "Added Linux sample app"
git push

Where (Amazon S3 copy command) is one of the following:

  • 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-east-2/samples/latest/SampleApp_Linux.zip . --region us-east-2 for the US East (Ohio) 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 EU (Ireland) region

  • aws s3 cp s3://aws-codedeploy-eu-central-1/samples/latest/SampleApp_Linux.zip . --region eu-central-1 for the EU (Frankfurt) 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/SampleApp_Linux.zip . --region ap-southeast-2 for the Asia Pacific (Sydney) region

  • aws s3 cp s3://aws-codedeploy-ap-south-1/samples/latest/SampleApp_Linux.zip . --region ap-south-1 for the Asia Pacific (Mumbai) region

  • 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

To push our sample revision to a Windows Server instance:

(Amazon S3 copy command)
git add SampleApp_Windows.zip
git commit -m "Added Windows sample app"
git push

Where (Amazon S3 copy command) is one of the following:

  • 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-east-2/samples/latest/SampleApp_Windows.zip . --region us-east-2 for the US East (Ohio) 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-central-1/samples/latest/SampleApp_Windows.zip . --region eu-central-1 for the EU (Frankfurt) Region

  • aws s3 cp s3://aws-codedeploy-eu-west-1/samples/latest/SampleApp_Windows.zip . --region eu-west-1 for the EU (Ireland) 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

  • 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 your-revision-file-name
git commit -m "Added Ubuntu app"
git push

Step 4: Provision an Instance

In this step, you will create an Amazon EC2 instance running Amazon Linux or a Windows Server, Ubuntu Server, or RHEL instance configured for use in AWS CodeDeploy deployments. Follow the instructions in Working with Instances, and then return to this page. If you already have an instance configured for use in AWS CodeDeploy deployments, go to the next step.

After you have successfully launched the instance and verified the AWS CodeDeploy agent is running, go to the next step.

Step 5: Deploy the Application to the Instance

In this step, you will use the AWS CodeDeploy console or the AWS CLI to deploy the sample revision from your GitHub repository to your instance. If you're using one of our sample revisions to deploy to an Amazon EC2 instance running Amazon Linux, RHEL, or Windows Server, our sample revision is a single web page deployed to the instance.

To deploy the revision (console)

  1. Sign in to the AWS Management Console and open the AWS CodeDeploy console at https://console.aws.amazon.com/codedeploy.

    Note

    Sign in with the same account or IAM user information you used in Getting Started.

  2. If the Applications page is not displayed, on the AWS CodeDeploy menu, choose Applications.

  3. Choose Create New Application.

  4. In the Application Name box, type CodeDeployGitHubDemo-App.

  5. In the Deployment Group Name box, type CodeDeployGitHubDemo-DepGrp.

  6. Choose a tag type for your instance.

    If you're deploying to an Amazon EC2 instance, choose Amazon EC2 from the Tag Type drop-down list. In the Key and Value boxes, type the Amazon EC2 instance tag key and value that was applied to your Amazon EC2 instance as part of Step 4: Provision an Instance.

    If you're deploying to an on-premises instance, choose On-Premises Instance from the Tag Type drop-down list. In the Key and Value boxes, type the on-premises instance tag key and value that was applied to your on-premises instance as part of Step 4: Provision an Instance.

  7. In the Deployment Config drop-down list, leave the default of CodeDeployDefault.OneAtATime.

  8. In the Service Role ARN drop-down list, choose the service role ARN. (Follow the instructions in Get the Service Role ARN (Console) to find the service role ARN.)

  9. Choose Create Application.

  10. On the Application details page, in Deployment groups, choose the button next to CodeDeployGitHubDemo-DepGrp.

  11. In the Actions menu, choose Deploy new revision.

  12. On the Create New Deployment page, in the Revision Type area, choose My application is stored in GitHub.

  13. Choose Connect with GitHub. The web page that appears will prompt you to authorize AWS CodeDeploy to interact with GitHub for the application named CodeDeployGitHubDemo-App.

    Note

    If you see a Reconnect with GitHub link instead of a Connect with GitHub button, this is expected behavior. Do not choose the link. Continue to the next step. For information about why this happens, see GitHub Authentication with Applications in AWS CodeDeploy.

    If you see a blank web page that briefly appears and then disappears, and you do not see a Reconnect with GitHub link or a Connect with GitHub button, this is also expected behavior. Continue to the next step. For information about why this happens, see GitHub Authentication with Applications in AWS CodeDeploy.

  14. Follow the instructions on the Sign in page to sign in with your GitHub account.

  15. On the Authorize application page, choose Authorize application.

  16. On the AWS CodeDeploy Create New Deployment page, in the Repository Name box, type 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 type, or if you want to specify a different repository:

    1. In a separate web browser tab, go to your GitHub dashboard.

    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 character (/), followed by the name of the repository. Type this displayed value into the Repository Name box.

      Tip

      If the target repository name is not displayed in Your repositories, use the Search GitHub box to find the target repository and corresponding GitHub user or organization name.

  17. In the Commit ID box, type the ID of the commit associated with the push of your application revision to GitHub.

    If you are unsure of the value to type:

    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 and copy 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 characters of the longer version.)

    4. Paste the commit ID into the Commit ID box.

  18. Leave the Deployment Description box blank.

  19. Leave the Deployment Config drop-down list at the default of CodeDeployDefault.OneAtATime, and choose Deploy Now.

Now that you've used the AWS CodeDeploy console to deploy the revision to the instance, you can skip ahead to Step 6: Monitor and Verify the Deployment.

To deploy the revision (CLI)

  1. Call the create-application command to create an application in AWS 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.

    • 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.

    • If you're deploying to an on-premises instance, on-premise-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.

    • If you're deploying to an on-premises instance, on-premise-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.

    • service-role-ARN is a service role ARN. (Follow the instructions in Get the Service Role ARN (CLI) 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 deployments and instances. The command also supports options for automatically rolling back deployments and setting up alarms to stop deployments when certain monitoring thresholds are met in Amazon CloudWatch Alarms. Commands for these actions are excluded from the sample in this tutorial.

  3. 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 AWS CodeDeploy permission to use your GitHub user account to interact with GitHub for the CodeDeployGitHubDemo-App application. Currently, you must use the AWS CodeDeploy console to do this.

    Sign in to the AWS Management Console and open the AWS CodeDeploy console at https://console.aws.amazon.com/codedeploy.

    Note

    Sign in with the same account or IAM user information you used in Getting Started.

  4. On the AWS CodeDeploy menu, choose Deployments.

  5. Choose Create New Deployment.

    Note

    You will not be creating a new deployment. This is currently the only way to give AWS CodeDeploy permission to interact with GitHub on behalf of your GitHub user account.

  6. From the Application drop-down list, choose CodeDeployGitHubDemo-App.

  7. From the Deployment Group drop-down list, choose CodeDeployGitHubDemo-DepGrp.

  8. In the Revision Type area, choose My application is stored in GitHub.

  9. Choose Connect With GitHub.

    Note

    If you see a Reconnect with GitHub link instead of a Connect with GitHub button, this is expected behavior. Do not choose the link. Continue to the next step. For information about why this happens, see GitHub Authentication with Applications in AWS CodeDeploy.

    If you see a blank web page that briefly appears and then disappears, and you don't see a Reconnect with GitHub link or a Connect with GitHub button, this also expected behavior. Continue to the next step. For information about why this happens, see GitHub Authentication with Applications in AWS CodeDeploy.

  10. Follow the instructions on the Sign in page to sign in with your GitHub user name or email and password.

  11. On the Authorize application page, choose Authorize application.

  12. On the AWS CodeDeploy Create New Deployment page, choose Cancel.

  13. 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.

      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.

        Tip

        If 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.

    • commitId 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 characters of the longer version.) Use this value.

    For Linux, OS X, or Unix:

    aws deploy create-deployment \
      --application-name CodeDeployGitHubDemo-App \
      --deployment-config-name CodeDeployDefault.OneAtATime \
      --deployment-group-name CodeDeployGitHubDemo-DepGrp \
      --description "My GitHub deployment demo" \
      --github-location repository=repository,commitId=commitId

    For Windows:

    aws deploy create-deployment --application-name CodeDeployGitHubDemo-App --deployment-config-name CodeDeployDefault.OneAtATime --deployment-group-name CodeDeployGitHubDemo-DepGrp --description "My GitHub deployment demo" --github-location repository=repository,commitId=commitId

Step 6: Monitor and Verify the Deployment

In this step, you will use either the AWS CodeDeploy console or the AWS CLI to verify the success of the deployment. You will use your web browser to view the web page that was deployed to the Amazon EC2 instance running Amazon Linux or the Windows Server or RHEL instance.

Note

If you're deploying to an Ubuntu Server instance, use your own testing strategy to determine whether the deployed revision works as expected on the instance, and then go to the next step.

To monitor and verify the deployment (console)

  1. If the Deployments page is not displayed, on the AWS CodeDeploy menu, choose Deployments.

  2. In the list of deployments, look for the row with an Application value of CodeDeployGitHubDemo-App and a Deployment group value of CodeDeployGitHubDemo-DepGrp. If Succeeded or Failed do not appear in the Status column, choose the Refresh button periodically.

  3. If Failed appears in the Status column, follow the instructions in View Instance Details (Console) to troubleshoot the deployment.

  4. If Succeeded appears in the Status column, you can now verify the deployment through your web browser. Our sample revision deploys a single web page to the instance. If you're deploying to an Amazon EC2 instance, in your web browser, go to http://PublicDNS for the instance (for example, http://ec2-01-234-567-890.compute-1.amazonaws.com).

  5. If you can see the web page, then congratulations! Now that you've successfully used AWS CodeDeploy to deploy a revision from GitHub, you can skip ahead to Step 7: Clean Up.

To monitor and verify the deployment (CLI)

  1. Call the list-deployments command to get the deployment ID for the application named CodeDeployGitHubDemo-App and the deployment group named CodeDeployGitHubDemo-DepGrp:

    aws deploy list-deployments --application-name CodeDeployGitHubDemo-App --deployment-group-name CodeDeployGitHubDemo-DepGrp --query "deployments" --output text
  2. Call the get-deployment command, supplying the ID of the deployment in the output from the list-deployments command:

    aws deploy get-deployment --deployment-id deployment-ID --query "deploymentInfo.[status, creator]" --output text
  3. If Failed is returned, follow the instructions in View Instance Details (Console) to troubleshoot the deployment.

  4. If Succeeded is returned, you can now try verifying the deployment through your web browser. Our sample revision is a single web page deployed to the instance. If you're deploying to an Amazon EC2 instance, you can view this page in your web browser by going to http://PublicDNS for the Amazon EC2 instance (for example, http://ec2-01-234-567-890.compute-1.amazonaws.com).

  5. If you can see the web page, then congratulations! You have successfully used AWS CodeDeploy to deploy from your GitHub repository.

Step 7: Clean Up

To avoid further charges for resources you used during this tutorial, you must terminate the Amazon EC2 instance and its associated resources. Optionally, you can delete the AWS CodeDeploy deployment component records associated with this tutorial. If you were using a GitHub repository just for this tutorial, you can delete it now, too.

To delete a AWS CloudFormation stack (if you used the AWS CloudFormation template to create an Amazon EC2 instance)

  1. Sign in to the AWS Management Console and open the AWS CloudFormation console at https://console.aws.amazon.com/cloudformation/.

  2. In the Stack Name column, select the box next to the stack starting with CodeDeploySampleStack.

  3. Choose Delete Stack.

  4. When prompted, choose Yes, Delete. The Amazon EC2 instance and the associated IAM instance profile and service role will be deleted.

To manually deregister and clean up an on-premises instance (if you provisioned an on-premises instance)

  1. Use the AWS CLI to call the deregister command against the on-premises instance represented here by your-instance-name and the associated region by your-region:

    aws deploy deregister --instance-name your-instance-name --delete-iam-user --region your-region
  2. From the on-premises instance, call the uninstall command:

    aws deploy uninstall

To manually terminate an Amazon EC2 instance (if you manually launched an Amazon EC2 instance)

  1. Sign in to the AWS Management Console and open the Amazon EC2 console at https://console.aws.amazon.com/ec2/.

  2. In the navigation pane, under Instances, choose Instances.

  3. Select the box next to the Amazon EC2 instance you want to terminate. Choose Actions, point to Instance State, and then choose Terminate.

  4. When prompted, choose Yes, Terminate.

To delete the AWS CodeDeploy deployment component records

  1. Sign in to the AWS Management Console and open the AWS CodeDeploy console at https://console.aws.amazon.com/codedeploy.

    Note

    Sign in with the same account or IAM user information you used in Getting Started.

  2. If the Applications page is not displayed, on the AWS CodeDeploy menu, choose Applications.

  3. Choose CodeDeployGitHubDemo-App.

  4. At the bottom of the Application details page, choose Delete application.

  5. When prompted, type the name of the application to confirm you want to delete it, and then choose Delete.

To delete your GitHub repository

  1. Open your GitHub dashboard.

  2. In Your repositories, choose CodeDeployGitHubDemo.

  3. In the repository navigation pane, choose Settings.

  4. In Danger Zone, choose Delete this repository.

  5. When prompted, type CodeDeployGitHubDemo, and then choose I understand the consequences, delete this repository.

  6. On your local computer, delete the /tmp/CodeDeployGitHubDemo folder and its contents (for Linux, OS X, or Unix) or the c:\temp\CodeDeployGitHubDemo folder and its contents (for Windows).