Github Runner AMI User Guide

Last updated on 
Github Runner AMI User Guide

Managing your Github Runner just got easier with the Prezelfy Github Runner AMI. Built on Amazon Linux 2023 and hardened according to CIS (Center for Internet Security) benchmarks, this pre-configured Amazon Machine Image takes the headache out of setting up GitHub runner. Forget spending hours on installation and configuration—this AMI is ready to go, so you can focus on writing code and delivering great software. With seamless integration into AWS services and security best practices already in place, the Prezelfy GitHub runner AMI gives you everything you need for a reliable and secure GitHub runner environment.

What do we offer with our GitHub AMI?

1. Security Best Practices

Our AWS GitHub runner AMI is configured with security best practices in mind. As minimum AMI includes recommended settings and configurations required by AWS, reducing the risk of overlooking crucial security measures. The operating system settings are hardened by CIS rules to reduce the attack surface, and unnecessary services or ports are disabled to minimize potential entry points for malicious actors. Our approach significantly reduces the likelihood of overlooking critical security configurations that might be missed when setting up a GitHub runner Host manually. Moreover, our GitHub runner AMIs incorporate the latest security updates and patches, providing a solid foundation that aligns with current security standards (CIS).

2. Time and Effort Savings

Setting up GitHub runner from scratch can be time-consuming and frustrating, especially when dealing with configurations, dependencies, and troubleshooting. The Prezelfy AMI removes that headache completely. It’s a fully pre-configured environment that’s ready to use as soon as you launch it. You don’t have to waste hours or even days tweaking settings or fixing issues—you can start focusing on building and deploying your applications right away. It’s designed to save you time and effort, letting you get back to what really matters: delivering value to your users.

3. Consistency Across Environment

One of the biggest challenges in managing GitHub runner is ensuring that your development, staging, and production environments are consistent. With the Prezelfy AMI, you can deploy the exact same GitHub runner setup across all your environments, ensuring there are no surprises or inconsistencies. This consistency helps minimize errors, simplifies troubleshooting, and creates a more predictable CI/CD pipeline. Whether you’re a solo developer or managing a large team, having the same reliable setup everywhere makes life so much easier.

4. Version Control and Updates

Keeping GitHub runner up to date can feel like a never-ending task. With Prezelfy, you don’t have to worry about manually checking for updates or patching vulnerabilities. We’ve taken care of it for you, ensuring that the AMI is always running the latest, most secure version of Github runner and its dependencies. This not only keeps your environment secure but also ensures compatibility with new features and AWS services. You can trust that your GitHub runner environment is current and optimized without lifting a finger.

5. Automatic registration with GitHub

Our Prezelfy GitHub Runner AMI makes it effortless to set up self-hosted GitHub Actions runners on AWS. Designed for scalability and performance, this AMI eliminates the hassle of manual configuration by offering automatic registration with GitHub. Simply set two parameters in AWS Systems Manager Parameter Store—/github/url (your GitHub repository or organization URL) and /github/token (your GitHub token with runner registration permissions)—and the runner will automatically connect to your GitHub environment. Whether you're optimizing your CI/CD pipelines for speed or security, our AMI provides a cost-effective and seamless alternative to GitHub-hosted runners.

6. Documentation

Ever spent hours trying to figure out how to configure something, only to find outdated or confusing documentation? Prezelfy AMIs come with clear, thorough documentation that’s written with developers in mind. Whether you’re a beginner or an experienced user, you’ll have access to everything you need to get started quickly, troubleshoot issues, and make the most of your GitHub runner setup. From setup guides to pipeline tips, we’ve got you covered.

Architectural design

This diagram illustrates the architecture of the Prezelfy GitHub Runner AMI deployment in AWS. On the left side, it shows the key components required for setup. The SSH key is used to access the EC2 instance running the GitHub runner. The Prezelfy GitHub Runner AMI is a pre-configured Amazon Machine Image that simplifies the deployment of self-hosted GitHub Actions runners. To function properly, the runner requires an IAM role, referred to as the GitHub Runner AMI Role, which grants necessary permissions. Additionally, AWS Systems Manager Parameter Store is used to store two critical parameters: /github/url, which holds the GitHub repository or organization URL, and /github/token, which contains the GitHub token required for authentication and runner registration. On the right side, the diagram represents the AWS infrastructure where the GitHub runner is deployed. The runner operates within an AWS VPC, ensuring network isolation and security. The deployment is designed to be multi-availability zone ready, making it highly available and resilient. The GitHub runner instance is placed within a public subnet, allowing it to communicate with GitHub over the internet. This EC2 instance serves as the actual GitHub Actions runner, which, upon launch, automatically registers itself with GitHub using the stored parameters. Overall, this architecture enables a seamless and automated CI/CD setup on AWS. By simply setting two parameters in AWS Systems Manager, users can deploy a self-hosted GitHub Actions runner that integrates effortlessly with their GitHub workflows, offering a cost-effective, scalable, and secure alternative to GitHub-hosted runners.

Installation guide

  1. Generate key pair and save private key on secure placeFollow the steps: Create and Manage Key Pairs - AWS EC2 Documentation
  2. Create parameters in SSM Parameter storeFollow the steps: Create and Manage SSM Parameters (SecureString) - AWS SSM Documentation2 required parameters:
    - /github/url
    - /github/token
  3. Create GitHub runner AMI RoleFollow the steps: Create and Manage AMI Instance profile - AWS IAM DocumentationMinimum permissions for role:
    - ssm:GetParameter
    - ssm:GetParameters
    - secretsmanager:GetSecretValue
  4. Get github url and token and update ssm parametersFollow the steps: Get guthub URL and Token for slef hosted runner - GitHub DocumentationOnce you get URL and Token value, update SSM parameters accordingly.
  5. Launch Prezelfy GitHub runner AMIFollow the steps:
    • Go to AWS Marketplace and search for Prezelfy GitHub runner AMI
    • Subscribe to the AMI by, click on the Prezelfy GitHub Runner AMI listing, review the pricing and terms of service and click the “Continue to Subscribe” button and confirm your subscription
    • Configure Your AMI in EC2, by go to your AWS Management Console and navigate to EC2 and click Launch Instance and choose Prezelfy Github Runner AMI from your subscribed AMIs
    • Set Instance Details, by choosing your instance type, configure networking, like adding the instance to an existing VPC and selecting subnets, add or select a security group to control access to your GitHub runner server, allow port port 22 for SSH access if needed. Port 22 is not required.
    • Attach create IAM role instance profile
    • Launch Your Instance, by review your settings and click Launch and select an SSH key pair created in step 1
    • In GitHub under Settings - Runners you will have idle runner that is ready to be used
  6. Secure Remote SSH Accessusername: ec2-user
    password: use SSH-key generated in step 1.

    Example:
    ssh -i /Users/Prezelfy/Keys/github-runner.pem ec2-user@ec2-ip-from-step-5

Troubleshooting when GitHub runner is not working

This are some of the cations we recommended to take when GitHub runner server is not functioning as intended:

1. Check Network Connectivity

Ensure that security group associated with GitHub runner allows outbound traffic on port 80 and 443 and verify that there are no network ACLs or route table rules blocking the traffic.

2. Verify GitHub runner Instance Status

Check the status of the GitHub runner host instance. If it's terminated, you may need to relaunch it.

3. SSH Key Pair and Permissions

Verify that you are using the correct SSH key pair to connect to the GitHub runner host and check the permissions on the private key file (it should only be readable by the owner).

4. EC2 Instance Metadata

On the GitHub runner host, check the EC2 instance metadata for errors or issues. Access metadata at http://169.254.169.254/latest/meta-data/ on the GitHub runner host.

5. IAM Role Trust Relationships

Review the trust relationship policy attached to the IAM role in the target account, Ensure that it allows the GitHub runner account to assume the role and check if the IAM role in the target account is still valid and has not been modified.

Check SSM Parameter values

Review that values for parameters in SSM and GitHub are matching.