Release 3.0.0 - Orchestrating self-hosted GitHub Runners with AWS Step Functions

Published on October 16, 2025 | Written by Andreas

We are happy to announce major version 3.0.0 of HyperEnv, our solution to deploy self-hosted GitHub Actions runners on Amazon Web Services.

This release is a huge step forward. We increase fault tolerance and reduce the time required to provision runners. This is possible due to a significant architecture change. Formerly, we used a state machine powered by AWS Step Functions to handle retries and to fall back from spot to on-demand instances in case of temporary capacity issues. HyperEnv missed the ability to track the status of each GitHub job. Also, the logic to handle the EC2 instance lifecycle was spread among the state machine as well as the HyperEnv service running on the EC2 instance.

From version HyperEnv >= 3.0.0 relies on two state machines.

The JobSateMachine tracks the state of each GitHub job.

• Queued indicates a job is waiting for a runner.
• InProgress says a job is currently running on a runner.
• Completed means a job has completed no matter the result (e.g., success or error).

The InstanceStateMachine keeps track of all EC2 instances launched by HyperEnv.

• Retries to launch an EC2 instance in case of insufficient capacity or rate limiting.
• Falls back to launch an on-demand instance, in case spot capacity is not available temporarily.
• Terminates the EC2 instance after the runner completed a job.
• Terminates the EC2 instance after a timeout to ensure machines are not getting stuck.

Moreover, we added two DynamoDB tables to store details about the state of jobs and instances. The following figure shows the revised architecture.

Using AWS Step Functions and Amazon DynamoDB to track the state of GitHub jobs and EC2 instances increases fault tolerance and allows us to implement long awaited features.

One of those features is our brand new look ahead functionality. While this feature is still experimental, it can significantly reduce the time required to provision runners. How does it work?

1. GitHub sends the workflow_run event to HyperEnv when a workflow run starts.
2. HyperEnv fetches information about the previous runs of the workflow.
3. In case a workflow consists of multiple jobs, HyperEnv schedules the launch of EC2 instances to ensure GitHub runners will already be up and running for subsequent jobs.

Here is what you need to do to enable the look-ahead feature.

1. Upgrade to version >=3.0.0 by following the upgrade guide.
2. Remove the GitHub app HyperEnv from your organization.
3. Install the GitHub app again by following the NextStepUrl from the outputs of the CloudFormation stack.
4. Update the CloudFormation stack and set the LookAhead parameter to true.

We are looking forward to your feedback! Stay tuned for more features shipped based on the powerful new architecture.