How do I use GitHub Enterprise to deploy an Amazon ECS application through CodePipeline?

Last updated: 2020-02-11

I want to use GitHub Enterprise to deploy an Amazon Elastic Container Service (Amazon ECS) application through AWS CodePipeline.

Short Description

Choose one of the following options:

  • Create a custom webhook with AWS Lambda and Amazon API Gateway by integrating Git with CodePipeline.
  • Integrate GitHub Enterprise as the source of an AWS CodeBuild project by completing the steps in the following Resolution section.

In the following resolution, you create a CodeBuild project with your GitHub Enterprise repository as the source.

Here's how the resolution works:

  • The project includes two buildspec.yml files. The first file, for CodeBuild, creates and moves the artifact to Amazon Simple Storage Service (Amazon S3). The other file is for CodePipeline. This file builds and pushes a Docker image to Amazon Elastic Container Registry (Amazon ECR).
  • An Amazon S3 bucket receives a new cb-artifact.zip file created by each build.
  • In CodePipeline, you have a source, build, and deploy stage. The source stage points to the Amazon S3 object (cb-artifact.zip). The build stage builds and pushes a Docker image to Amazon ECR. The deploy stage updates the task definition version on your Amazon ECS service.

Resolution

Create a new CodeBuild project with GitHub Enterprise as the source

1.    Open the CodeBuild console.

2.    Choose Create build project.

3.    For Project name, enter a unique name for your project.

4.    In the Source section, for Source provider, choose GitHub Enterprise.

5.    For GitHub Enterprise personal access token, enter the token that's generated from your GitHub account, and then choose Save token.

Note: You must enter and save the personal access token only once. All future CodeBuild projects use this token.

6.    For Repository URL, enter the path to your repository, including the name of the repository.

7.    Expand Additional configuration.

8.    To ignore SSL warnings while connecting to your GitHub enterprise project repository, choose Enable insecure SSL.

Note: It's a best practice to enable insecure SSL for testing only, not for production environments.

9.    In the Primary source webhook events section, select the Rebuild every time a code change is pushed to this repository check box.

10.    For Environment image, choose Managed Image.

11.    For Operating system, choose Amazon Linux 2.

12.    For Runtime(s), choose Standard.

13.    For Image, choose aws/codebuild/amazonlinux2-x86_64-standard:2.0.

14.    For Image version, choose Always use the latest image for this runtime version.

15.    For Environment type, choose Linux.

16.    Leave the Enable this flag if you want to build Docker images or want your builds to get elevated privileges check box empty.

17.    For Service role, choose New service role.

Note: Update the new service role and add permissions for CodeBuild to access the Amazon S3 bucket where you store the zip file.

18.    In the Buildspec section, for Build specifications, choose Use a buildspec file or Insert build commands based on your needs. See the following example buildspec:

version: 0.2
  phases:
    install:
      runtime-versions:
        docker: 18
    build:
      commands:
          - echo Uploading Artifacts to S3
  artifacts:
      files:
          - '**/*'

Note: There are two buildspec.yml files for the same project. Each file is stored in a different folder in the project. The first file path is defined as codebuild/buildspec.yml.

19.    In Artifacts, for Type, choose Amazon S3.

20.    For Bucket name, choose a bucket from the list, or create a new one.

Important: Use an existing Amazon S3 bucket or create a new Amazon S3 bucket with versioning enabled. The Amazon S3 bucket stores the zip file created by each build. With each new build, a new zip file is pushed to the Amazon S3 bucket. The code pipeline is triggered with each new zip file.

21.    For name, choose cb-artifact.zip.

22.    For Path and Namespace type, leave the default options.

23.    For Artifacts packaging, choose zip.

24.    Choose Create build project.

Note: A new role created in the CodeBuild console is named codebuild-YourProjectName-service-role.

Create a new code pipeline with an Amazon S3 bucket as the source

1.    Open the CodePipeline console.

2.    Choose Create pipeline.

3.    For Pipeline name, enter the name for your pipeline.

4.    For Service role, choose New service role.

5.    Choose Next.

6.    In the Source section, for Source provider, choose Amazon S3.

7.    For Bucket, choose the bucket that contains the zip files created from the build with your bucket name.

8.    For S3 object key, enter cb-artifact.zip.

9.    Choose Next.

10.    Choose Create pipeline.

Create a new CodeBuild project for the build stage

1.    For Build provider, choose AWS CodeBuild, and then choose Create Project.

Note: You're redirected to the CodeBuild project creation page.

2.    For Project name, enter a unique name for your project.

3.    For Environment image, choose Managed Image.

4.    For Operating system, choose Amazon Linux 2.

5.    For Runtime(s), choose Standard.

6.    For Image, choose aws/codebuild/amazonlinux2-x86_64-standard:2.0.

7.    For Image version, choose Always use the latest image for this runtime version.

8.    For Environment type, choose Linux.

9.    Select the Enable this flag if you want to build Docker images or want your builds to get elevated privileges check box.

10.    For Service role, choose New service role.

11.    In the Buildspec section, for Build specifications, choose Use a buildspec file or Insert build commands based on your needs. See the following example buildspec file:

version: 0.2
phases:
  install:
    runtime-versions:
      docker: 18
  pre_build:
    commands:
      - echo Logging in to Amazon ECR...
      - aws --version
      - YOUR_ACCOUNT_ID=$(aws sts get-caller-identity --output text --query 'Account')
      - $(aws ecr get-login --region $AWS_DEFAULT_REGION --no-include-email)
      - REPOSITORY_URI=$(echo $ACCOUNT_ID).dkr.ecr.eu-central-1.amazonaws.com/ECR-REPO-NAME
      - COMMIT_HASH=$(echo $CODEBUILD_RESOLVED_SOURCE_VERSION | cut -c 1-7)
      - IMAGE_TAG=${COMMIT_HASH:=latest}
  build:
    commands:
      - echo Build started on 'date'
      - echo Building the Docker image...
      - docker build -t $REPOSITORY_URI:latest .
      - docker tag $REPOSITORY_URI:latest $REPOSITORY_URI:$IMAGE_TAG
  post_build:
    commands:
      - echo Build completed on 'date'
      - echo Pushing the Docker images...
      - docker push $REPOSITORY_URI:latest
      - docker push $REPOSITORY_URI:$IMAGE_TAG
      - echo Writing image definitions file...
      - printf '[{"name":"YourContainerName","imageUri":"%s"}]' $REPOSITORY_URI:$IMAGE_TAG > imagedefinitions.json
artifacts:
    files: imagedefinitions.json

Note: If you use the preceding example code, update the ECR-REPO-NAME and YourContainerName parameters.

Important: There are two buildspec.yml files for the same project. Each file is stored in a different folder in the project. The second file path is defined as codepipeline/buildspec.yml. The default file name for the file generated by the buildspec is imagedefinitions.json. If you choose to use a different file name, you must provide that name when you create the pipeline deployment stage.

12.    Choose Continue to CodePipeline.

13.    Leave Environment variables and Variable namespace blank.

14.    For Output artifacts, add a unique name (such as BuildArtifact) for later use.

15.    Choose Done.

Deploy the cluster and service with Amazon ECS

After completing the steps in the previous section, you are redirected to the CodePipeline console.

1.    In the Deploy section of the CodePipeline console, for Deploy provider, choose Amazon ECS.

2.    For Input artifacts, choose BuildArtifact.

3.    For Cluster name, choose the cluster that you want to deploy.

4.    For Service name, choose the service that you want to deploy.

5.    Choose Next, and then choose Create pipeline.

6.    After creating the build project and pipeline, update the service role in the AWS Identity and Access Management (IAM) console.

Note: The new role created in the CodeBuild console is named codebuild-YourProjectName-service-role. This role doesn't have the permissions to push the image to Amazon ECR. For more information, see Step 3: Add Amazon ECR Permissions to the CodeBuild Role.