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

Integrating CodeDeploy with GitHub

CodeDeploy supports GitHub, a web-based code hosting and sharing service. CodeDeploy can deploy application revisions stored in GitHub repositories or Amazon S3 buckets to instances.

Video Introduction to CodeDeploy Integration with GitHub

This short video (5:20) demonstrates how to automate application deployments with CodeDeploy from your existing GitHub workflows.

Deploying CodeDeploy Revisions from GitHub

To deploy an application revision from a GitHub repository to instances:

  1. Create a revision that's compatible with CodeDeploy and the Amazon EC2 instance type to which you will deploy.

    To create a compatible revision, follow the instructions in Plan a Revision for CodeDeploy and Add an Application Specification File to a Revision for CodeDeploy.

  2. Use a GitHub account to add your revision to a GitHub repository.

    To create a GitHub account, see Join GitHub. To create a GitHub repository, see Create a Repo.

  3. Use the Create deployment page in the CodeDeploy console or the AWS CLI create-deployment command to deploy your revision from your GitHub repository to target instances configured for use in CodeDeploy deployments.

    If you want to call the create-deployment command, you must first use the Create deployment page of the console to give CodeDeploy permission to interact with GitHub on behalf of your preferred GitHub account for the specified application. You only need to do this once per application.

    To learn how to use the Create deployment page to deploy from a GitHub repository, see Create a Deployment with CodeDeploy.

    To learn how to call the create-deployment command to deploy from a GitHub repository, see Create an EC2/On-Premises Compute Platform Deployment (CLI).

    To learn how to prepare instances for use in CodeDeploy deployments, see Working with Instances for CodeDeploy.

For more information, see Tutorial: Use CodeDeploy to Deploy an Application from GitHub.

GitHub Behaviors with CodeDeploy

GitHub Authentication with Applications in CodeDeploy

After you give CodeDeploy permission to interact with GitHub, the association between that GitHub account and application is stored in CodeDeploy. You can link the application to a different GitHub account. You can also revoke permission for CodeDeploy to interact with GitHub.

To link a GitHub account to an application in CodeDeploy

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

    Note

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

  2. In the navigation pane, expand Deploy, and then choose Applications.

  3. Choose the application you want to link to a different GitHub account.

  4. If your application does not have a deloyment group, choose Create deployment group to create one. For more information, see Create a Deployment Group with CodeDeploy. A deployment group is required to choose Create deployment in the next step.

  5. From Deployments, choose Create deployment.

    Note

    You don't have to create a new deployment. This is currently the only way to link a different GitHub account to an application.

  6. In Deployment settings, for Revision type, choose My application is stored in GitHub.

  7. Do one of the following:

    • To create a connection for AWS CodeDeploy applications to a GitHub account, sign out of GitHub in a separate web browser tab. In GitHub token name, 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 your application. Continue to step 10.

    • To use a connection you have already created, in GitHub token name, select its name, and then choose Connect to GitHub. Continue to step 8.

    • To create a connection to a different GitHub account, sign out of GitHub in a separate web browser tab. In GitHub token name, type a name to identify the connection, and then choose Connect to GitHub. The web page prompts you to authorize CodeDeploy to interact with GitHub for your application. Continue to step 10.

  8. If you are not already signed in to GitHub, follow the instructions on the Sign in page to sign in with the GitHub account to which you want to link the application.

  9. Choose Authorize application. GitHub gives CodeDeploy permission to interact with GitHub on behalf of the signed-in GitHub account for the selected application.

  10. If you do not want to create a deployment, choose Cancel.

To revoke permission for CodeDeploy to interact with GitHub

  1. Sign in to GitHub using credentials for the GitHub account in which you want to revoke AWS CodeDeploy permission.

  2. Open the GitHub Applications page, locate CodeDeploy in the list of authorized applications, and then follow the GitHub procedure for revoking authorization for an application.

CodeDeploy Interaction with Private and Public GitHub Repositories

CodeDeploy supports the deployment of applications from private and public GitHub repositories. When you give CodeDeploy permission to access GitHub on your behalf, CodeDeploy will have read-write access to all of the private GitHub repositories to which your GitHub account has access. However, CodeDeploy only reads from GitHub repositories. It will not write to any of your private GitHub repositories.

CodeDeploy Interaction with Organization-Managed GitHub Repositories

By default, GitHub repositories that are managed by an organization (as opposed to your account's own private or public repositories) do not grant access to third-party applications, including CodeDeploy. Your deployment will fail if an organization's third-party application restrictions are enabled in GitHub and you attempt to deploy code from its GitHub repository. There are two ways to resolve this issue.

For more information, see About Third-Party Application Restrictions.

Automatically Deploy from CodePipeline with CodeDeploy

You can trigger a deployment from a CodePipeline whenever the source code changes. For more infomation, see CodePipeline.