Skip to main content
← Back to workflows

How to Use On-demand Self-hosted AWS EC2 Runner for GitHub Actions

machulav/ec2-github-runner -
GitHub Action
v2.3.6
GitHub Org's stars
Contributors
Categories
CICube banner
The GitHub Actions dashboard helps you spot bottlenecks and optimize your CI pipeline with actionable insights.
Usage
name: do-the-job
on: pull_request
jobs:
start-runner:
name: Start self-hosted EC2 runner
runs-on: ubuntu-latest
outputs:
label: ${{ steps.start-ec2-runner.outputs.label }}
ec2-instance-id: ${{ steps.start-ec2-runner.outputs.ec2-instance-id }}
steps:
- name: Configure AWS credentials
uses: aws-actions/configure-aws-credentials@v1
with:
aws-access-key-id: ${{ secrets.AWS_ACCESS_KEY_ID }}
aws-secret-access-key: ${{ secrets.AWS_SECRET_ACCESS_KEY }}
aws-region: ${{ secrets.AWS_REGION }}
- name: Start EC2 runner
id: start-ec2-runner
uses: machulav/ec2-github-runner@v2
with:
mode: start
github-token: ${{ secrets.GH_PERSONAL_ACCESS_TOKEN }}
ec2-image-id: ami-123
ec2-instance-type: t3.nano
subnet-id: subnet-123
security-group-id: sg-123

do-the-job:
name: Do the job on the runner
needs: start-runner
runs-on: ${{ needs.start-runner.outputs.label }}
steps:
- name: Hello World
run: echo 'Hello World!'

stop-runner:
name: Stop self-hosted EC2 runner
needs:
- start-runner
- do-the-job
runs-on: ubuntu-latest
if: ${{ always() }}
steps:
- name: Configure AWS credentials
uses: aws-actions/configure-aws-credentials@v1
with:
aws-access-key-id: ${{ secrets.AWS_ACCESS_KEY_ID }}
aws-secret-access-key: ${{ secrets.AWS_SECRET_ACCESS_KEY }}
aws-region: ${{ secrets.AWS_REGION }}
- name: Stop EC2 runner
uses: machulav/ec2-github-runner@v2
with:
mode: stop
github-token: ${{ secrets.GH_PERSONAL_ACCESS_TOKEN }}
label: ${{ needs.start-runner.outputs.label }}
ec2-instance-id: ${{ needs.start-runner.outputs.ec2-instance-id }}

ec2-github-runner logo

ec2-github-runner

Start and stop EC2 runners dynamically as part of GitHub Actions workflows.


This GitHub Action allows you to dynamically start and stop an AWS EC2 instance as a self-hosted runner for GitHub Actions, providing customizable hardware configurations for your workflows. This approach can also save costs by using more affordable AWS EC2 instances when compared to the GitHub-hosted runners.

How to Specify Mode

The mode input specifies whether to start or stop the EC2 runner.

  • start: Starts a new runner.
  • stop: Stops the previously created runner.
with:
mode: start

How to Provide GitHub Token

The github-token input is required for managing self-hosted runners in your GitHub repository. It should be stored in GitHub secrets as a Personal Access Token (PAT) with the repo scope.

with:
github-token: ${{ secrets.GH_PERSONAL_ACCESS_TOKEN }}

How to Set EC2 Image ID

The ec2-image-id input is required in start mode and specifies the Amazon Machine Image (AMI) to use for creating the EC2 instance.

with:
ec2-image-id: ami-123

How to Select EC2 Instance Type

The ec2-instance-type input specifies the EC2 instance type, such as t3.nano, c5.4xlarge, etc. This input is required in start mode.

with:
ec2-instance-type: t3.nano

How to Specify Subnet ID

The subnet-id input is required in start mode and defines the VPC subnet where the EC2 instance will be created.

with:
subnet-id: subnet-123

How to Specify Security Group ID

The security-group-id input is required in start mode and specifies the security group for the EC2 instance. The security group should only allow outbound traffic on port 443 for communicating with GitHub.

with:
security-group-id: sg-123

How to Provide a Unique Runner Label

The label input is required in stop mode. This label is used to remove the runner from GitHub once the job is complete.

with:
label: ${{ needs.start-runner.outputs.label }}

How to Provide EC2 Instance ID

The ec2-instance-id input is required in stop mode and specifies the EC2 instance to be terminated. The instance ID is provided by the output of the start mode.

with:
ec2-instance-id: ${{ needs.start-runner.outputs.ec2-instance-id }}

How to Attach an IAM Role to the EC2 Runner

The iam-role-name input allows you to specify an IAM role for the EC2 runner to use. This is optional and requires additional AWS permissions.

with:
iam-role-name: my-role-name

How to Add AWS Resource Tags

The aws-resource-tags input allows you to specify tags for the EC2 instance. This is a stringified JSON array of tag objects.

with:
aws-resource-tags: >
[
{"Key": "Name", "Value": "ec2-github-runner"},
{"Key": "GitHubRepository", "Value": "${{ github.repository }}"}
]

How to Use Pre-runner Script

The pre-runner-script input allows you to specify bash commands to run before the runner starts, such as installing dependencies.

with:
pre-runner-script: |
sudo yum update -y && \
sudo yum install docker git libicu -y && \
sudo systemctl enable docker

Environment Variables

In addition to the inputs, you also need to configure AWS credentials as environment variables, such as AWS_ACCESS_KEY_ID, AWS_SECRET_ACCESS_KEY, and AWS_REGION. You can use aws-actions/configure-aws-credentials to set these up.

- name: Configure AWS credentials
uses: aws-actions/configure-aws-credentials@v1
with:
aws-access-key-id: ${{ secrets.AWS_ACCESS_KEY_ID }}
aws-secret-access-key: ${{ secrets.AWS_SECRET_ACCESS_KEY }}
aws-region: ${{ secrets.AWS_REGION }}

Monitoring GitHub Actions Workflows

CICube is a GitHub Actions monitoring tool that provides you with detailed insights into your workflows to further optimize your CI/CD pipeline. With CICube, you will be able to track your workflow runs, understand where the bottlenecks are, and tease out the best from your build times. Go to cicube.io now and create a free account to better optimize your GitHub Actions workflows!

CICube GitHub Actions Workflow Duration Monitoring