Ubuntu custom AMI example

This module shows how to create GitHub action runners using a prebuilt AMI for the runners.

• Configured to run with org level runners.
• GitHub runner binary syncer is not deployed.

@@ Usages

Steps for the full setup, such as creating a GitHub app can be found in the root module's README. First download the Lambda releases from GitHub. Alternatively you can build the lambdas locally with Node or Docker, there is a simple build script in <root>/.ci/build.sh. In the main.tf you can simply remove the location of the lambda zip files, the default location will work in this case.

This example assumes local built lambda's available. Ensure you have built the lambda's. Alternatively you can download the lambda's. The version needs to be set to a GitHub release version, see https://github.com/github-aws-runners/terraform-aws-github-runner/releases

cd ../lambdas-download
terraform init
terraform apply -var=module_version=<VERSION>
cd -

Packer Image

You will need to build your image. This example deployment uses the image example in /images/linux-amz2. You must build this image with packer in your AWS account first. Once you have built this you need to provider your owner ID as a variable

Deploy

To use your image in the terraform modules you will need to set some values on the module.

Assuming you have built the linux-al2023 image which has a pre-defined AMI name in the following format github-runner-al2023-x86_64-YYYYMMDDhhmm you can use the following values.

module "runners" {
  ...
  # set the name of the ami to use
  ami_filter        = { name = ["github-runner-al2023-x86_64-2023*"], state = ["available"] }
  # provide the owner id of
  ami_owners        = ["<your owner id>"]

  enable_userdata = false
  ...
}

If your owner is the same as the account you are logging into then you can use aws_caller_identity to retrieve it dynamically.

data "aws_caller_identity" "current" {}

module "runners" {
  ...
  ami_owners       = [data.aws_caller_identity.current.account_id]
  ...
}

You can then deploy the terraform

terraform init
terraform apply

The module will try to update the GitHub App webhook and secret (only linux/mac). You can receive the webhook details by running:

terraform output webhook_secret

Requirements

Name	Version
terraform	>= 1.3.0
aws	~> 5.27
local	~> 2.0
random	~> 3.0

Providers

Name	Version
aws	5.82.1
random	3.6.3

Modules

Name	Source	Version
base	../base	n/a
runners	../../	n/a
webhook_github_app	../../modules/webhook-github-app	n/a

Resources

Name	Type
random_id.random	resource
aws_caller_identity.current	data source

Inputs

Name	Description	Type	Default	Required
ami_name_filter	AMI name filter for the action runner AMI. By default amazon linux 2 is used.	string	"github-runner-al2023-x86_64-*"	no
aws_region	AWS region.	string	"eu-west-1"	no
environment	Environment name, used as prefix.	string	null	no
github_app	GitHub for API usages.	object({ id = string key_base64 = string })	n/a	yes
runner_os	The EC2 Operating System type to use for action runner instances (linux,windows).	string	"linux"	no

Outputs

Name	Description
webhook_endpoint	n/a
webhook_secret	n/a