Step 2: Create Launch Template

Define your EC2 instance configuration:

# CloudFormation template excerpt
LaunchTemplate:
  Type: AWS::EC2::LaunchTemplate
  Properties:
    LaunchTemplateName: github-runner-template
    LaunchTemplateData:
      ImageId: ami-0123456789abcdef0  # Amazon Linux 2023
      InstanceType: t3.large
      IamInstanceProfile:
        Name: !Ref RunnerInstanceProfile
      SecurityGroupIds:
        - !Ref RunnerSecurityGroup
      UserData:
        Fn::Base64: !Sub |
          #!/bin/bash
          # Install dependencies
          yum update -y
          yum install -y docker git
# Start Docker
          systemctl start docker
          systemctl enable docker
# Install GitHub Actions runner
          mkdir /actions-runner && cd /actions-runner
          curl -o actions-runner-linux-x64.tar.gz -L \
            https://github.com/actions/runner/releases/download/v2.311.0/actions-runner-linux-x64-2.311.0.tar.gz
          tar xzf actions-runner-linux-x64.tar.gz
# Configure runner (token retrieved from Secrets Manager)
          RUNNER_TOKEN=$(aws secretsmanager get-secret-value \
            --secret-id github-runner-token \
            --query SecretString --output text)
./config.sh --url https://github.com/your-org \
            --token $RUNNER_TOKEN \
            --name "ec2-runner-$(hostname)" \
            --labels "self-hosted,linux,x64,ec2" \
            --unattended
# Install and start as service
          ./svc.sh install
          ./svc.sh start

Step 3: Configure Auto Scaling

Set up auto scaling for runner capacity:

AutoScalingGroup:
  Type: AWS::AutoScaling::AutoScalingGroup
  Properties:
    AutoScalingGroupName: github-runners-asg
    LaunchTemplate:
      LaunchTemplateId: !Ref LaunchTemplate
      Version: !GetAtt LaunchTemplate.LatestVersionNumber
    MinSize: 2
    MaxSize: 10
    DesiredCapacity: 2
    VPCZoneIdentifier:
      - !Ref PrivateSubnet1
      - !Ref PrivateSubnet2
    Tags:
      - Key: Name
        Value: github-runner
        PropagateAtLaunch: true

Step 4: Security Group Configuration

Allow necessary network access:

RunnerSecurityGroup:
  Type: AWS::EC2::SecurityGroup
  Properties:
    GroupDescription: Security group for GitHub runners
    VpcId: !Ref VPC
    SecurityGroupEgress:
      - IpProtocol: tcp
        FromPort: 443
        ToPort: 443
        CidrIp: 0.0.0.0/0
        Description: HTTPS for GitHub API
      - IpProtocol: tcp
        FromPort: 80
        ToPort: 80
        CidrIp: 0.0.0.0/0
        Description: HTTP for package downloads

How Do You Use Self-Hosted Runners in Workflows?

Target Self-Hosted Runners

name: Build and Deploy
on:
  push:
    branches: [main]
jobs:
  build:
    runs-on: [self-hosted, linux, x64, ec2]
steps:
      - uses: actions/checkout@v4
- name: Build application
        run: |
          npm ci
          npm run build
- name: Run tests
        run: npm test

Using Custom Labels

Target specific runner configurations:

jobs:
  gpu-training:
    runs-on: [self-hosted, gpu, p3]
    steps:
      - name: Train ML model
        run: python train.py
standard-build:
    runs-on: [self-hosted, linux, x64]
    steps:
      - name: Build app
        run: make build

For teams also integrating code quality tools, self-hosted runners are particularly effective when combined with SonarQube analysis in GitHub Actions since you can cache SonarQube scanner packages locally for faster scans.

Runner Registration Automation

GitHub App for Token Management

Create a GitHub App for programmatic runner registration:

import jwt
import requests
import time
def get_runner_registration_token(org_name, app_id, private_key):
    # Generate JWT
    now = int(time.time())
    payload = {
        'iat': now,
        'exp': now + 600,
        'iss': app_id
    }
    token = jwt.encode(payload, private_key, algorithm='RS256')
# Get installation token
    headers = {
        'Authorization': f'Bearer {token}',
        'Accept': 'application/vnd.github+json'
    }
# Get installation ID
    response = requests.get(
        f'https://api.github.com/orgs/{org_name}/installation',
        headers=headers
    )
    installation_id = response.json()['id']
# Get installation access token
    response = requests.post(
        f'https://api.github.com/app/installations/{installation_id}/access_tokens',
        headers=headers
    )
    access_token = response.json()['token']
# Get runner registration token
    headers['Authorization'] = f'Bearer {access_token}'
    response = requests.post(
        f'https://api.github.com/orgs/{org_name}/actions/runners/registration-token',
        headers=headers
    )
return response.json()['token']

What Are the Best Scaling Strategies for Self-Hosted Runners?

Webhook-Based Scaling

Scale runners based on workflow demand:

from flask import Flask, request
import boto3
app = Flask(__name__)
asg = boto3.client('autoscaling')
@app.route('/webhook', methods=['POST'])
def handle_webhook():
    event = request.json
if event['action'] == 'queued':
        # Increase capacity
        current_capacity = get_current_runner_count()
        asg.set_desired_capacity(
            AutoScalingGroupName='github-runners-asg',
            DesiredCapacity=current_capacity + 1
        )
return 'OK', 200

Scheduled Scaling

Scale based on expected demand:

When choosing between EC2 and Fargate for container workloads, keep in mind that EC2-based runners give you the most flexibility for caching, custom tooling, and GPU access, while Fargate can be a simpler option for ephemeral, container-based build environments.

Security Best Practices

Instance Hardening

• Use minimal AMI with only necessary packages
• Enable automatic security updates
• Configure instance metadata service v2 (IMDSv2)
• Implement CIS benchmarks

Network Security

• Deploy runners in private subnets
• Use NAT Gateway for outbound internet access
• Restrict security group rules
• Consider VPC endpoints for AWS services

Secrets Management

• Store runner tokens in AWS Secrets Manager
• Rotate tokens regularly
• Use IAM roles instead of access keys
• Implement least privilege access

Monitoring and Maintenance

CloudWatch Metrics

Monitor runner health and performance:

CloudWatchAlarm:
  Type: AWS::CloudWatch::Alarm
  Properties:
    AlarmName: runner-cpu-high
    MetricName: CPUUtilization
    Namespace: AWS/EC2
    Statistic: Average
    Period: 300
    EvaluationPeriods: 2
    Threshold: 80
    ComparisonOperator: GreaterThanThreshold
    Dimensions:
      - Name: AutoScalingGroupName
        Value: !Ref AutoScalingGroup

Log Aggregation

Centralize runner logs: