terraform-aws-batch-github-runner

Terraform module for self hosted GitHub action runners on AWS Batch.

This project will use Docker image from repo github.com/myoung34/docker-github-actions-runner. Credit to Marc for his amazing work.

How to setup

Step 1. Setup GitHub App

Go to GitHub and create a new app. Beware you can create apps your organization or for a user.

1. Create app in Github
2. Choose a name
3. Choose a website (mandatory, not required for the module).
4. Disable the webhook for now.
5. Permissions for all runners:
   • Repository:
     • Actions: Read-only (check for queued jobs)
     • Checks: Read-only (receive events for new builds)
     • Metadata: Read-only (default/required)
6. Permissions for repo level runners only:
   • Repository:
     • Administration: Read & write (to register runner)
7. Permissions for organization level runners only:
   • Organization
     • Self-hosted runners: Read & write (to register runner)
8. Save the new app.
9. On the General page, make a note of the "App ID" parameters.
10. Generate a new private key and save the app.pem file into configs folder.

Step 2. Local test with Docker

For more environment option / Usage, please visit github.com/myoung34/docker-github-actions-runner or github.com/myoung34/docker-github-actions-runner/wiki

Use with Github App in Repo level, Ephemeral runner

docker run -d --restart always --name github-runner \
  -e EPHEMERAL="1" \
  -e APP_ID="your-app-id" \
  -e APP_PRIVATE_KEY="GitHub App Private Key" \
  -e REPO_URL="https://github.com/<your-username>/<your-repo>" \
  -e RUNNER_NAME_PREFIX="github-runner" \
  -e LABELS="label-1,label-2" \
     myoung34/github-runner:latest

Use with Github App in Org level, Ephemeral runner

docker run -d --restart always --name github-runner \
  -e EPHEMERAL="1" \
  -e APP_ID="your-app-id" \
  -e APP_PRIVATE_KEY="GitHub App Private Key" \
  -e RUNNER_SCOPE="org" \
  -e ORG_NAME="<your-org-name>" \
  -e RUNNER_NAME_PREFIX="github-runner" \
  -e LABELS="my-label,other-label" \
     myoung34/github-runner:latest

Step 3. Edit config

Change/Review all file in configs folder to match with your parameters.

In main.tf update necessary parameters in locals to fit with your needs.

• region = "ap-southeast-1" AWS Region
• org_id = "your-org-id" Your Organization ID
• org_user_ids = ["user1", "user2"] List of user-id in Organization approved to run this runner
• github_app_id = "2xxxxx8" Github App ID in Step 1

Step 4. Run terraform by using the following commands

$ terraform init
$ terraform plan
$ terraform apply --auto-approve

The terraform output displays the API Gateway URL (webhook), which you need in the next step.

Step 5. Set Webhook to Github App

• Use API Gateway URL from Step 4 Output and Set it in Webhook URL of your Github App in Step 1. Don't forget tick on Active
• In the "Install App" section, install the App in your organization, either in all or in selected repositories.

Use in workflow

• If you set ec2 in runs-on parameter of your workflow, job will run on container in EC2 instance.

jobs:
  render-docs:
    runs-on: [self-hosted, ec2]

• If you set fargate in runs-on parameter of your workflow, job will run on Fargate.

jobs:
  render-docs:
    runs-on: [self-hosted, fargate]

---

Many thanks to philips-labs/terraform-aws-github-runner and myoung34/docker-github-actions-runner

Requirements

No requirements.

Providers

Name	Version
aws	n/a
random	n/a

Modules

Name	Source	Version
api_gateway	./modules/api-gateway	n/a
batch	./modules/batch	n/a
iam_role	./modules/iam	n/a
secrets_manager	./modules/secrets-manager	n/a
security_group	terraform-aws-modules/security-group/aws	4.9.0
vpc	terraform-aws-modules/vpc/aws	5.1.0

Resources

Name	Type
random_string.random	resource
aws_availability_zones.available	data source

Inputs

Name	Description	Type	Default	Required
default_tags	(Required) Default tag for AWS resource	map	{ "component": "main", "env": "dev", "github_repo": "", "project": "terraform-aws-batch-github-runner" }	no

Outputs

Name	Description
api_gateway_invoke_url	URL of API Gateway Webhook, use to set in GitHub App webhook
batch_job_definition	A set of AWS Batch job definiton
ec2_batch_job_queue	Set of EC2 batch job queue
fargate_batch_job_queue	Set of fargate batch job queue
secret_app_key	ARN of the GitHub App Private key stored in Secret Manager