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
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 }}