AWS, Cloud Computing

3 Mins Read

A Guide to Setting Up a Self-Hosted Runner on an Amazon EC2 Machine

Voiced by Amazon Polly


Setting up a self-hosted runner on an Amazon EC2 machine for GitHub Actions workflows is a powerful way to customize and optimize your continuous integration and deployment (CI/CD) pipelines. This process allows you to leverage your own infrastructure while benefiting from the automation and scalability of GitHub Actions.


This document outlines the step-by-step process of creating and configuring a self-hosted runner on an Amazon EC2 machine. Once set up, the runner acts as a dedicated agent for executing jobs triggered by GitHub Actions workflows associated with your repository. Here’s a brief overview of the key steps involved:

Runner Flow

  1. Registration: Register the self-hosted runner with your GitHub repository. This involves obtaining a registration token from GitHub and configuring the registration token in the Self-Hosted Runner (Amazon EC2).
  2. Authentication: The self-hosted runner will authenticate with GitHub using the provided registration token once registered.
  3. Listening for Jobs: The self-hosted runner will continuously listen for incoming job requests from GitHub Actions workflows associated with the repository.
  4. Job Execution: When a job is triggered, GitHub dispatches it to an available self-hosted runner. The runner executes the job by cloning the repository, running the specified workflow steps, and reporting the results to GitHub.
  5. Cleanup: After completing the job, the self-hosted runner cleans up any temporary files and awaits further instructions

Pioneers in Cloud Consulting & Migration Services

  • Reduced infrastructural costs
  • Accelerated application deployment
Get Started

Step-by-Step Guide

The steps below detail creating and configuring a self-hosted runner on an Amazon EC2 machine for running your GitHub Actions workflows.


  1. Download the Runner Package:

Connect to your Amazon EC2 instance using your preferred SSH client.

Create a directory to store the runner files:



Download the latest runner package using curl. Replace the version number (v2.314.1) with the latest available version you want to use. You can find the latest version on the GitHub Actions releases page



(Optional) Validate the Download:

Note: – Before proceeding, ensure the shasum command is available on your Amazon EC2 instance. You can check by running:


This step verifies the package integrity using its SHA-256 hash. You can find the hash value for each release on the GitHub Actions releases page.


If the hash values match, the download is valid. Otherwise, redownload the package.

Extract the Installer:


Execute sudo ./bin/ to install any missing Dotnet Core 6.0 dependencies.


  1. Configure the Runner:

Run the configuration script:



Replace the following: Replace with the URL of your GitHub repository.

AQ5LI5U2SRPVTMF2RM272BLGBJNCQ: Replace with a valid personal access token generated from your GitHub account with the repo scope. You can create a personal access token under Settings > Developer settings > Personal access tokens.


Setting up a self-hosted runner on an Amazon EC2 machine for GitHub Actions provides enhanced control, customization, and scalability for your CI/CD workflows. This guide outlines the detailed steps to configure and deploy a self-hosted runner, ensuring secure and efficient job execution. By leveraging your own infrastructure, you can tailor the runner environment to meet specific requirements and optimize performance while benefiting from the robust features of GitHub Actions.

Proper setup and management of self-hosted runners on Amazon EC2 instances can significantly improve the efficiency and reliability of your development and deployment pipelines.

Drop a query if you have any questions regarding Amazon EC2 and we will get back to you quickly.

Making IT Networks Enterprise-ready – Cloud Management Services

  • Accelerated cloud migration
  • End-to-end view of the cloud environment
Get Started

About CloudThat

CloudThat is a leading provider of Cloud Training and Consulting services with a global presence in India, the USA, Asia, Europe, and Africa. Specializing in AWS, Microsoft Azure, GCP, VMware, Databricks, and more, the company serves mid-market and enterprise clients, offering comprehensive expertise in Cloud Migration, Data Platforms, DevOps, IoT, AI/ML, and more.

CloudThat is recognized as a top-tier partner with AWS and Microsoft, including the prestigious ‘Think Big’ partner award from AWS and the Microsoft Superstars FY 2023 award in Asia & India. Having trained 650k+ professionals in 500+ cloud certifications and completed 300+ consulting projects globally, CloudThat is an official AWS Advanced Consulting Partner, Microsoft Gold Partner, AWS Training PartnerAWS Migration PartnerAWS Data and Analytics PartnerAWS DevOps Competency PartnerAmazon QuickSight Service Delivery PartnerAmazon EKS Service Delivery PartnerAWS Microsoft Workload PartnersAmazon EC2 Service Delivery Partner, and many more.

To get started, go through our Consultancy page and Managed Services PackageCloudThat’s offerings.


1. Why use a self-hosted runner on an Amazon EC2 machine?

ANS: – Self-hosted runners offer greater customization and control over the execution environment than GitHub-hosted runners. Utilizing an Amazon EC2 machine allows you to leverage your existing infrastructure while integrating seamlessly with GitHub Actions workflows.

2. How do I obtain a registration token from GitHub?

ANS: – You can generate a personal access token with the “repo” scope from your GitHub account settings. This token is used during the configuration of the self-hosted runner.

3. Can I customize the AMI for the self-hosted runner?

ANS: – Yes, you can create a custom AMI with additional tools and configurations to suit your specific requirements. This allows for consistency and efficiency when deploying self-hosted runners.

WRITTEN BY Rajveer Singh Chouhan

Rajveer Singh Chouhan works as a Research Associate at CloudThat. He has been learning and gaining practical experience in AWS and Azure. Rajveer is also passionate about continuously expanding his skill set and knowledge base by actively seeking opportunities to learn new skills. Rajveer regularly reads blogs and articles related to various programming languages, technologies, and industry trends to stay up to date with the latest developments in the field.



    Click to Comment

Get The Most Out Of Us

Our support doesn't end here. We have monthly newsletters, study guides, practice questions, and more to assist you in upgrading your cloud career. Subscribe to get them all!