Announcing AWS CodeBuild Support for GitHub Enterprise as a Source Type and Shallow Cloning

Thank you to my colleague Harvey Bendana for this blog on how to do shallow cloning on AWS CodeBuild using GitHub Enterprise as a source.

Today we are announcing support for using GitHub Enterprise as a source type for CodeBuild. You can now initiate build tasks from changes in source code hosted on your own implementation of GitHub Enterprise.

We are also announcing support for shallow cloning of a repo when you use CodeCommit, BitBucket, GitHub, or GitHub Enterprise as a source type. Shallow cloning allows you to truncate history of a repo in order to save space and speed up cloning times.

In this post, I’ll walk you through how to configure GitHub Enterprise as a source type with a defined clone depth for an AWS CodeBuild project. I’ll also show you all the moving parts associated with a successful implementation.

AWS CodeBuild is a fully managed build service. There are no servers to provision and scale, or software to install, configure, and operate. You just specify the location of your source code, choose your build settings, and CodeBuild runs build scripts for compiling, testing, and packaging your code.

GitHub Enterprise is the on-premises version of GitHub.com. It makes collaborative coding possible and enjoyable for large-scale enterprise software development teams.

Many enterprises choose GitHub Enterprise as their preferred source code/version control repository because it can be hosted in their own trusted network, whether that is an on-premises data center or their own Amazon VPCs.

Requirements

• You’ll need an AWS account.
• You’ll need a GitHub Enterprise implementation with a repo. If you’d like to deploy one inside your own Amazon VPC, check out our Quick Start Guide.
• You’ll need an S3 bucket to store your GitHub Enterprise self-signed SSL certificate.

Download your GitHub Enterprise SSL certificate:

Note: The following steps are required only for self-signed certificates. You can forego installation of a certificate if you are using self-signed certificates and default to HTTP communication with your repo. For this post, I am using a self-signed certificate and the Firefox browser. These steps may vary, depending on your browser of choice.

1. Navigate to your GitHub Enterprise environment and sign in with your credentials.

2. Choose the lock icon in the upper-left corner to view and export your GitHub Enterprise certificate.

3. When you export and download your certificate, make sure you select the format type, which includes the entire certificate chain.

      4. Open the Amazon S3 console at https://console.aws.amazon.com/s3 and upload your certificate to an S3 bucket in your AWS account.

Now I will show you how to create an AWS CodeBuild project.

Create a sample AWS CodeBuild project:

1. Open the AWS CodeBuild console at https://console.aws.amazon.com/codebuild.

2. If there are no existing build projects, a welcome page is displayed. Choose Get started. If you already have build projects, then choose Create project.

3. On the Configure your project page, type a name for your build project. Build project names must be unique across each AWS account.

4. For Source provider, choose GitHub Enterprise.

5. Generate a personal access token in your GitHub Enterprise environment. Under Select scopes, select repo. For information, see Creating a personal access token for the command line on the GitHub Help website.

6. Enter your personal access token in your CodeBuild project and choose Save Token.

7. Enter the repository URL and choose a Git clone depth value that makes sense for you. Allowed values are 1, 5, 25, or Full. For this post, I am using a depth of 1.

8. Select the Webhook check box.

9. Continue with the rest of the configuration for your project, choosing options that best suit your build needs. For this post, I am using an AWS CodeBuild managed image running the Ubuntu OS with the base runtime configuration. Enter your build specifications or build commands. I am using a simple build command of git log . so that it can be easily found in the CloudWatch logs of the CodeBuild project. It will also be used to demonstrate the shallow clone feature.

10. Next, select Install certificate from your S3 to install your GitHub Enterprise self-signed certificate from S3. For Bucket of certificate, I’ve entered the S3 bucket where I uploaded the certificate. For Object key of certificate, I’ve entered the name of the certificate.

11. Lastly, configure artifacts, caching, IAM roles, and VPC configurations. For this post, I chose not to generate any artifacts from this build. From the following screenshot, you’ll see I’ve opted out of cache, requested a new IAM role with the required permissions, and have not defined VPC access. Choose Continue to validate and complete the creation of the CodeBuild project.

Note: If your GitHub Enterprise environment is in an Amazon VPC, configure VPC access for your project. Define the VPC ID, subnet ID, and security group so that your project has access to the EC2 instances hosting your GitHub Enterprise environment.

12. After the project is created, a dialog box displays a CodeBuild payload URL and secret. They are used to create a webhook for the repo in the GitHub Enterprise environment.

Create a webhook in your GitHub Enterprise repo:

1. In your GitHub Enterprise repo, navigate to Settings, choose Hooks & services, and then choose Add webhook.

2. Paste the payload URL and secret into their respective fields. Under Which events would you like to trigger this webhook? choose an option. For this post, I am using Let me select individual events. I then chose Pull request and Push as the two event triggers.

3. Make sure Active is selected and then choose Add webhook.

4. A webhook has now been created in the GitHub Enterprise repo.

Now I will show you how to test this.

Trigger your AWS CodeBuild project by pushing a change to the GitHub Enterprise repo

1. Clone the repo to the local file system. For information, see Clone the Repository Using the Command Line on the GitHub Help website. Now create a feature branch, push a change, and generate a pull request for review, and, ultimately, merge to master. Here is the state of the GitHub Enterprise repo and AWS CodeBuild project before pushing a change:

2. Use Git command line tools to create a new branch in the repo.

3. Update the README.md for the repo with a link to the AWS CodeBuild documentation.

4. After the changes have been saved, push them to the feature branch.

5. There is now notification of a new branch in the GitHub Enterprise environment.

6. Generate a pull request from the feature branch in preparation of review and merge to master.

7. The reviewer(s) will then review and merge the pull request, pushing all changes to the master branch.

8. Here is the updated repo:

9. After the change has been pushed successfully, a new build is initiated.

10. In the following screenshot, you’ll see the initiator is Github-Hookshot/eb0c46 and the source version is 03169095b8f16ac077388471035becb2070aa12c.

11. In the Recent Deliveries section, under the configuration of the GitHub Enterprise repo webhook, the CodeBuild project initiator is defined as User-Agent. The source version is denoted in the Payload output. They match!

12. A successfully completed build should appear under the CodeBuild project.

13. The entire log output of the CodeBuild project can be viewed in CloudWatch logs. In the following screenshot, the source was downloaded successfully from the GitHub Enterprise repo and the build command of git log . was run successfully. Only the most recent commit appears in the git history output. This is because I defined a clone depth of 1.

14. If I query the git history of the repo on the local repository, the output has the full commit history. This is expected because I am doing a full clone locally.

Conclusion

In this blog post, I showed you how to configure GitHub Enterprise as a source type for your AWS CodeBuild project with a clone depth of 1. These new features expand the capabilities of AWS CodeBuild and the suite of AWS Developer Tools for CI/CD and DevOps processes.

I hope you found this post useful. Feel free to leave your feedback or suggestions in the comments.