GitHub actions runners in AWS EC2

Update (March 2026): Since this post was written, Blacksmith runners have emerged as a significantly faster and simpler alternative to self-hosting runners on EC2. Blacksmith offers up to 2-3× faster builds with zero infrastructure management — we now default to Blacksmith for all Akadenia CI pipelines. This post remains useful if you need full control over your runner environment (custom AMIs, VPC access, on-prem), but Blacksmith is the easier path for most teams.

Spin up EC2 instance

1. Get access to AWS
2. Choose an EC2 instance type that will suit your needs. (We chose t2.xlarge.)
3. Choose a security group that is suitable for the instance. This will dictate which ports (protocols) are open to the internet for inbound and outbound traffic. (I created one called continuous-integration that currently exposes ssh, http, and https to the internet.)
4. Choose the storage amount for the instance
5. Make sure to download the PEM file and store it in 1password

SSH to EC2 instance

1. Use PEM to SSH to instance. (If you've just created this instance and the connection times out you probably need to add inbound/outbound SSH to security group.)

2. SSH to the instance using the instructions from AWS

   Copy

   ssh -i "your-file.pem" username@ec2-instance-public-dns
   

Configure GitHub runners

1. Install Docker: https://docs.aws.amazon.com/AmazonECS/latest/developerguide/docker-basics.html
   1. sudo yum update -y
   2. sudo amazon-linux-extras install docker
   3. sudo service docker start
   4. sudo usermod -a -G docker ec2-user (will not take effect until next login)
   5. sudo systemctl enable docker (required to restart docker when ec2 instance boots up)

2. sudo ./start-org-runner.sh <RUNNER_TOKEN> (This script is in the ec2-user home dir)

   1. GitHub org admins can get an org runner token.
   2. Repo admins can get a repo runner token
   3. Runner tokens expire after a short period of time (maybe an hour).
   4. start-org-runner.sh source

   Copy

   docker run -d --restart always --name github-runner-$(date +%s) \
     -e RUNNER_SCOPE="org" \
     -e ORG_NAME="akadenia" \
     -e LABELS="aws" \
     -e RUNNER_NAME_PREFIX="akadenia-aws" \
     -e RUNNER_TOKEN="$1" \
     -e RUNNER_WORKDIR="/tmp/github-runner-akadenia" \
     -v /var/run/docker.sock:/var/run/docker.sock \
     -v /tmp/github-runner-akadenia:/tmp/github-runner-akadenia \
     myoung34/github-runner:latest
   

3. sudo ./start-org-runner.sh <RUNNER_TOKEN> (

   1. GitHub org admins can get an org runner token.
   2. Repo admins can get a repo runner token
   3. Runner tokens expire after a short period of time (maybe an hour).
   4. start-org-runner.sh source

   Copy

   docker run -d --restart always --name github-runner-$(date +%s) \
     -e RUNNER_SCOPE="org" \
     -e ORG_NAME="akadenia" \
     -e LABELS="aws" \
     -e RUNNER_NAME_PREFIX="akadenia-aws" \
     -e RUNNER_TOKEN="$1" \
     -e RUNNER_WORKDIR="/tmp/github-runner-akadenia" \
     -v /var/run/docker.sock:/var/run/docker.sock \
     -v /tmp/github-runner-akadenia:/tmp/github-runner-akadenia \
     myoung34/github-runner:latest
   

4. sudo ./start-org-runner.sh <RUNNER_TOKEN> (

   1. GitHub org admins can get an org runner token.
   2. Repo admins can get a repo runner token
   3. Runner tokens expire after a short period of time (maybe an hour).
   4. start-org-runner.sh source

   Copy

   docker run -d --restart always --name github-runner-$(date +%s) \
     -e RUNNER_SCOPE="org" \
     -e ORG_NAME="akadenia" \
     -e LABELS="aws" \
     -e RUNNER_NAME_PREFIX="akadenia-aws" \
     -e RUNNER_TOKEN="$1" \
     -e RUNNER_WORKDIR="/tmp/github-runner-akadenia" \
     -v /var/run/docker.sock:/var/run/docker.sock \
     -v /tmp/github-runner-akadenia:/tmp/github-runner-akadenia \
     myoung34/github-runner:latest