Repository files navigation

⚠️ If you like the project, please considersupporting Ukraine in awar against russian occupants. Any help would be much appreciated!

(image byNina Dzyvulska)

Start your EC2self-hosted runner right before you need it.Run the job on it.Finally, stop it when you finish.And all this automatically as a part of your GitHub Actions workflow.

Seebelow the YAML code of the depicted workflow.

Table of Contents

• Use cases
  • Access private resources in your VPC
  • Customize hardware configuration
  • Save costs
• Usage
  • How to start
  • Inputs
  • Environment variables
  • Outputs
  • Example
  • Advanced: JIT runners
  • Advanced: Multi-AZ failover
  • Advanced: Debug mode
  • Real user examples
• Self-hosted runner security with public repositories
• License Summary

The action can start the EC2 runner in any subnet of your VPC that you need - public or private.In this way, you can easily access any private resources in your VPC from your GitHub Actions workflow.

For example, you can access your database in the private subnet to run the database migration.

GitHub provides one fixed hardware configuration for their Linux virtual machines: 2-core CPU, 7 GB of RAM, 14 GB of SSD disk space.

Some of your CI workloads may require more powerful hardware than GitHub-hosted runners provide.In the action, you can configure any EC2 instance type for your runner that AWS provides.

For example, you may run a c5.4xlarge EC2 runner for some of your compute-intensive workloads.Or r5.xlarge EC2 runner for workloads that process large data sets in memory.

If your CI workloads don't need the power of the GitHub-hosted runners and the execution takes more than a couple of minutes,you can consider running it on a cheaper and less powerful instance from AWS.

According toGitHub's documentation, you don't need to pay for the jobs handled by the self-hosted runners:

Self-hosted runners are free to use with GitHub Actions, but you are responsible for the cost of maintaining your runner machines.

So you will be charged by GitHub only for the time the self-hosted runner start and stop.EC2 self-hosted runner will handle everything else so that you will pay for it to AWS, which can be less expensive than the price for the GitHub-hosted runner.

Use the following steps to prepare your workflow for running on your EC2 self-hosted runner:

1. Prepare IAM user with AWS access keys

1. Create new AWS access keys for the new or an existing IAM user with the following least-privilege minimum required permissions:

   {"Version":"2012-10-17","Statement": [    {"Effect":"Allow","Action": ["ec2:RunInstances","ec2:TerminateInstances","ec2:DescribeInstances","ec2:DescribeInstanceStatus"      ],"Resource":"*"    }  ]}

   If you use therunner-debug input to enable debug logging, you will also need to allow theec2:GetConsoleOutput permission so the action can poll the EC2 serial console output during startup:

   {"Version":"2012-10-17","Statement": [    {"Effect":"Allow","Action": ["ec2:GetConsoleOutput"      ],"Resource":"*"    }  ]}

   If you plan to attach an IAM role to the EC2 runner with theiam-role-name parameter, you will need to allow additional permissions:

   {"Version":"2012-10-17","Statement": [   {"Effect":"Allow","Action": ["ec2:ReplaceIamInstanceProfileAssociation","ec2:AssociateIamInstanceProfile"     ],"Resource":"*"   },   {"Effect":"Allow","Action":"iam:PassRole","Resource":"*"   } ]}

   If you use theaws-resource-tags parameter, you will also need to allow the permissions to create tags:

   {"Version":"2012-10-17","Statement": [   {"Effect":"Allow","Action": ["ec2:CreateTags"     ],"Resource":"*","Condition": {"StringEquals": {"ec2:CreateAction":"RunInstances"       }     }   } ]}

   These example policies above are provided as a guide. They can and most likely should be limited even more by specifying the resources you use.

2. Add the keys to GitHub secrets.

3. Use theaws-actions/configure-aws-credentials action to set up the keys as environment variables.

2. Prepare GitHub personal access token

1. Create a new GitHub personal access token with therepo scope.The action will use the token for self-hosted runners management in the GitHub account on the repository level.
2. Add the token to GitHub secrets.

3. Prepare EC2 image

1. Create a new EC2 instance based on any Linux distribution you need.

2. Connect to the instance using SSH, installdocker andgit, then enabledocker service.

   For Amazon Linux 2023:

    sudo dnf update -y&& \ sudo dnf install docker git libicu -y&& \ sudo systemctlenable docker

   For Amazon Linux 2:

    sudo yum update -y&& \ sudo yum install docker git libicu -y&& \ sudo systemctlenable docker

   For other Linux distributions, it could be slightly different.

3. Install any other tools required for your workflow.

4. Create a new EC2 image (AMI) from the instance.

5. Remove the instance if not required anymore after the image is created.

Important: If your AMI was created from an instance that previously ran a GitHub Actions runner, make sure to delete the stale runner configuration files (.runner,.credentials,.credentials_rsaparams) from the runner directory before creating the AMI. The action handles this automatically, but a clean AMI avoids unnecessary warnings.

Alternatively, you can use a vanilla EC2 AMI and set up the dependencies viapre-runner-script or thepackages input in the workflow YAML file.

Compatibility note: This action uses a#cloud-boothook user-data format to ensure the setup script runs during cloud-init's init stage. This is compatible with Amazon Linux 2, Amazon Linux 2023, Ubuntu, and other distributions that support cloud-init. The boothook approach avoids issues with some AMIs wherecloud_final_modules (used byruncmd) may be empty or misconfigured.

4. Prepare VPC with subnet and security group

1. Create a new VPC and a new subnet in it.Or use the existing VPC and subnet.
2. Create a new security group for the runners in the VPC.Onlyoutbound traffic on port TCP/443 is required to pull jobs from GitHub.No inbound traffic is required for this purpose, but if your workflow needs to access external repositories or internal SSH, other ports like TCP/22, TCP/80, etc ... may be required.

5. Configure the GitHub workflow

1. Create a new GitHub Actions workflow or edit the existing one.
2. Use the documentation and example below to configure your workflow.
3. Please don't forget to set up a job for removing the EC2 instance at the end of the workflow execution.Otherwise, the EC2 instance won't be removed and continue to run even after the workflow execution is finished.

Now you're ready to go!

In addition to the inputs described above, the action also requires the following environment variables to access your AWS account:

• AWS_DEFAULT_REGION
• AWS_REGION
• AWS_ACCESS_KEY_ID
• AWS_SECRET_ACCESS_KEY

We recommend usingaws-actions/configure-aws-credentials action right before running the step for creating a self-hosted runner. This action perfectly does the job of setting the required environment variables.

The workflow showed in the picture above and declared indo-the-job.yml looks like this:

name:do-the-jobon:pull_requestjobs:start-runner:name:Start self-hosted EC2 runnerruns-on:ubuntu-latestoutputs:label:${{ steps.start-ec2-runner.outputs.label }}ec2-instance-id:${{ steps.start-ec2-runner.outputs.ec2-instance-id }}steps:      -name:Configure AWS credentialsuses:aws-actions/configure-aws-credentials@v4with: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 runnerid:start-ec2-runneruses:machulav/ec2-github-runner@v2with:mode:startgithub-token:${{ secrets.GH_PERSONAL_ACCESS_TOKEN }}ec2-image-id:ami-123ec2-instance-type:t3.nanosubnet-id:subnet-123security-group-id:sg-123iam-role-name:my-role-name# optional, requires additional permissionsaws-resource-tags:># optional, requires additional permissions            [              {"Key": "Name", "Value": "ec2-github-runner"},              {"Key": "GitHubRepository", "Value": "${{ github.repository }}"}            ]block-device-mappings:># optional, to customize EBS volumes            [              {"DeviceName": "/dev/sda1", "Ebs": {"VolumeSize": 100, "VolumeType": "gp3"}}            ]do-the-job:name:Do the job on the runnerneeds:start-runner# required to start the main job when the runner is readyruns-on:${{ needs.start-runner.outputs.label }}# run the job on the newly created runnersteps:      -name:Hello Worldrun:echo 'Hello World!'stop-runner:name:Stop self-hosted EC2 runnerneeds:      -start-runner# required to get output from the start-runner job      -do-the-job# required to wait when the main job is doneruns-on:ubuntu-latestif:${{ always() }}# required to stop the runner even if the error happened in the previous jobssteps:      -name:Configure AWS credentialsuses:aws-actions/configure-aws-credentials@v4with: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 runneruses:machulav/ec2-github-runner@v2with:mode:stopgithub-token:${{ secrets.GH_PERSONAL_ACCESS_TOKEN }}label:${{ needs.start-runner.outputs.label }}ec2-instance-id:${{ needs.start-runner.outputs.ec2-instance-id }}

JIT (Just-In-Time) runners use GitHub'sgenerate-jitconfig API to create single-use runners that automatically deregister after completing one job. This eliminates the need forconfig.sh and simplifies cleanup.

JIT runners skip the traditional registration-token flow entirely. Instead, the encoded JIT config is passed directly to./run.sh --jitconfig <config>. The runner self-destructs after the job completes, sostop mode only terminates the EC2 instance (no GitHub runner removal needed).

Note: JIT mode is incompatible withrun-runner-as-service: true since JIT runners are inherently single-use.

      -name:Start EC2 runnerid:start-ec2-runneruses:machulav/ec2-github-runner@v2with:mode:startgithub-token:${{ secrets.GH_PERSONAL_ACCESS_TOKEN }}ec2-image-id:ami-123ec2-instance-type:t3.nanosubnet-id:subnet-123security-group-id:sg-123use-jit:truerunner-group-id:1# optional, defaults to the "Default" runner group

Theavailability-zones-config input allows you to specify multiple availability zone configurations. The action will try each one in sequence until an instance is successfully launched. This is useful for handling capacity issues or spot instance unavailability in a specific AZ.

Each configuration object requiresimageId,subnetId, andsecurityGroupId. You can optionally specify aregion per entry; if omitted, theAWS_REGION environment variable is used.

      -name:Start EC2 runnerid:start-ec2-runneruses:machulav/ec2-github-runner@v2with:mode:startgithub-token:${{ secrets.GH_PERSONAL_ACCESS_TOKEN }}ec2-instance-type:t3.nanomarket-type:spotavailability-zones-config:>            [              {"imageId": "ami-123", "subnetId": "subnet-aaa", "securityGroupId": "sg-111"},              {"imageId": "ami-456", "subnetId": "subnet-bbb", "securityGroupId": "sg-222", "region": "us-west-2"},              {"imageId": "ami-789", "subnetId": "subnet-ccc", "securityGroupId": "sg-333", "region": "eu-west-1"}            ]

When a runner fails to register, it can be difficult to diagnose the issue because user-data scripts execute on the remote EC2 instance. Therunner-debug input enables verbose logging to help with troubleshooting.

Whenrunner-debug: true is set, the action will:

1. Inject detailed echo statements into the setup script on the instance — logging each step (architecture detection, runner download, config.sh execution, etc.)
2. Poll the EC2 serial console output during the registration wait loop, streaming new output to the GitHub Actions log as it appears
3. Log the full user-data script content so you can see exactly what was sent to the instance

This requires theec2:GetConsoleOutput IAM permission. Add the following to your IAM policy:

{"Version":"2012-10-17","Statement": [    {"Effect":"Allow","Action":"ec2:GetConsoleOutput","Resource":"*"    }  ]}

Note: EC2 serial console output takes 2-5 minutes to become available after instance launch and may not capture all output from user-data scripts. For full script logs, SSH into the instance and check/tmp/runner-setup.log.

      -name:Start EC2 runnerid:start-ec2-runneruses:machulav/ec2-github-runner@v2with:mode:startgithub-token:${{ secrets.GH_PERSONAL_ACCESS_TOKEN }}ec2-image-id:ami-123ec2-instance-type:t3.nanosubnet-id:subnet-123security-group-id:sg-123runner-debug:truestartup-timeout-minutes:10# increase timeout when debugging

Inthis discussion, you can find feedback and examples from the users of the action.

If you use this action in your workflow, feel free to add your story there as well 🙌

We recommend that you do not use self-hosted runners with public repositories.

Forks of your public repository can potentially run dangerous code on your self-hosted runner machine by creating a pull request that executes the code in a workflow.

Please find more details about this security note onGitHub documentation.

This code is made available under theMIT license.