Running GitHub Actions on a private subnet with AWS CodeBuild

Last week, the Developer Tools team announced that AWS CodeBuild now supports GitHub Actions. AWS CodeBuild is a fully managed continuous integration service for building and testing code. CodeBuild builds are defined as a collection of build commands and associated settings in YAML format, called BuildSpec. You can now define GitHub Actions steps directly in BuildSpec and run them with CodeBuild commands. In this article, the authors will use Liquibase GitHub Actions to implement changes to the Amazon Aurora database in a private subnet.

Background

The GitHub Marketplace contains many actions developed by other companies and the open-source community. At the time of writing this, there are almost 20,000 shares available on the marketplace. Using shares from the market can save time and effort that would have been spent creating scripts to install and configure the various tools required in the compilation process.

While developers love GitHub actions, they often want to run my compilation in AWS. For example, they may want to access a resource in a private VPC or reduce the latency between the compilation service and my resource. They could achieve this by hosting the GitHub Action Runner on Amazon Elastic Compute Cloud (Amazon EC2). However, hosting the GitHub Action Runner requires additional work to set up and maintain the environment in which the runner resides.

AWS CodeBuild is a fully managed continuous integration service. CodeBuild requires no ongoing maintenance and can access resources on a private subnet. You can now use GitHub Actions in AWS CodeBuild. This feature provides simplified configuration and management of CodeBuild with the rich GitHub Actions marketplace. In the section below, you will learn how to configure CodeBuild to run GitHub Actions.

Guide

In this tutorial, the authors will configure AWS CodeBuild to use Liquibase GitHub Actions to deploy change logs to a PostgreSQL database hosted on Amazon Aurora on a private subnet. As shown in the image below, AWS CodeBuild will be configured to run on a private subnet along with my Aurora instance. First, CodeBuild will download the GitHub action using a NAT gateway to access the internet. Second, CodeBuild will apply the change log to the Aurora instance on the private subnet.

You already have a GitHub repository with Liquibase configuration properties and change logs, as shown in the image below. Liquibase configuration is not the topic of this blog post, but you can read more in Introduction to Liquibase. The source in question also contains a buildspec.yaml file, which will be explained later in this blog post.

To create your build project, open CodeBuild in the AWS console and select Create build project. Then, provide a name and optional description for the build. Your example project is called liquibase-blog-post.

If you already have a connection to GitHub, you can connect using your personal access token, as shown in the image below.

Once successfully connected to GitHub, you can paste the URL to my repository, as shown in the image below.

Configure your build environment to use the standard build environment in Amazon Linux 2. GitHub Actions are built using JavaScript or a Docker container. You must enable the Privileged flag if the action uses a Docker platform container. The Liquibase image uses a Docker container, so check the box to allow Privileged mode.

For VPC configurations, select the VPC and the private subnet where your Aurora instance is hosted, then click Validate VPC Settings to ensure your configuration is correct.

Your buildspec file is included in the source. Therefore, select Use a buildspec file and enter the path to the buildspec file in the repository.

Your buildspec.yaml file contains the following content: Note that the pre_build phase induces a series of commands. Commands have always been supported in CodeBuild and include a series of command-line commands to run. In this case, register some environment variables for later debugging.

version: 0.2
phases:
  pre_build:
    commands:
      - echo $AWS_DEFAULT_REGION
      - echo $URL
  build: 
    steps:
      - uses: liquibase-github-actions/[email protected]
        with:
          changelogFile: changelog-root.xml
          url: ${{ env.URL }}
          username: postgres
          password: ${{ $env.PASSWORD }}
          headless: true

Note also that the compile phase includes a number of new steps that trigger GitHub actions. Each compile phase supports either a list of commands or a list of steps, but not both at the same time. In this example, specify a Liquibase update action (liquibase-github-actions/update) with several configuration parameters. You can see the full list of parameters in the Liquibase Update Action repository on GitHub.

Note the environment variables used in the buildspec.yml file. Remember to pass the URL and PASSWORD to your database as environment variables. This allows you to change these values from one environment to another easily. As shown in the image below, you have configured these environment variables in the CodeBuild project definition. The URL is configured as Plain Text, and the PASSWORD is configured as Secrets Manager. Running the GitHub action in CodeBuild provides easy access to the secrets stored in AWS Secrets Manager and the configuration data stored in the AWS Systems Manager Parameter Store.

It should also be noted that the syntax used to access environment variables in the buildspec.yaml file is different when using GitHub Actions. GitHub actions access environment variables using the environment context. Therefore, in the pre_build phase you use the CodeBuild syntax of $NAME. On the other hand, in the compile phase, use the GitHub syntax in the format ${{env:NAME}}.

Once the configuration is complete, select Create build project and then manually run the build to test the configuration. In the example below, you can see the logs from the Liquibase update. Notice that two sets of changes were successfully applied to the database.

####################################################
##   _     _             _ _                      ##
##  | |   (_)           (_) |                     ##
##  | |    _  __ _ _   _ _| |__   __ _ ___  ___   ##
##  | |   | |/ _` | | | | | '_ \ / _` / __|/ _ \  ##
##  | |___| | (_| | |_| | | |_) | (_| \__ \  __/  ##
##  \_____/_|\__, |\__,_|_|_.__/ \__,_|___/\___|  ##
##              | |                               ##
##              |_|                               ##
##                                                ##
##  Get documentation at docs.liquibase.com       ##
##  Get certified courses at learn.liquibase.com  ##
##  Free schema change activity reports at        ##
##      https://hub.liquibase.com                 ##
##                                                ##
####################################################
Starting Liquibase at 18:33:23 (version 4.21.1 #9070)
Liquibase Version: 4.21.1
Liquibase Open Source 4.21.1 by Liquibase
Running Changeset: changelogs/changelog-1.0.0.xml::1::BobR
Running Changeset: changelogs/changelog-1.0.1.xml::2::BobR
  
UPDATE SUMMARY
Run: 2
Previously run: 0
Filtered out: 0
-------------------------------
Total change sets: 2
  
Liquibase: Update has been successful.
Liquibase command 'update' was executed successfully.

Phase complete: BUILD State: SUCCEEDED
Phase context status code: Message:
Entering phase POST_BUILD
Connect to the Aurora database and describe the tables. You will see that Liquibase has created an actors table (as defined in Liquibase Quick Start) along with the Liquibase databasechangelog and databasechangeloglock audit tables. Everything works as you assumed, and you do not have to install and configure Liquibase!

mydatabase=> \dt
List of relations
Schema  |         Name          | Type  |  Owner
--------+-----------------------+-------+----------
public  | actor                 | table | postgres
public  | databasechangelog     | table | postgres
public  | databasechangeloglock | table | postgres
(3 rows)

This example taught you how to update an Aurora database on a private subnet using a Liquibase GitHub action running in CodeBuild. GitHub actions provide a rich catalog of pre-configured actions to simplify configuration. CodeBuild provides a managed service that simplifies the setup and maintenance of your compilation environment. Used together, they can get the best features of both CodeBuild and GitHub Actions.

Tidying up

In this tutorial, the authors have shown you how to create a CodeBuild project. If you no longer need the project, you can delete it in the console. If you have made other resources, for example, the Aurora database, that are not explained in this post, you should also delete them.

Applications

The GitHub Marketplace contains a catalog of almost 20,000 activities developed by third parties and the open-source community. AWS CodeBuild is a fully managed continuous integration service that integrates tightly with other AWS services. The authors used the GitHub action for Liquibase in this article to deploy a database update on a private subnet. The authors are eager to see what you can accomplish with GitHub Actions support in CodeBuild. You can read more about this exciting new feature in the GitHub Action runner in AWS CodeBuild.