Upgrade Guide

We regularly release new versions of HyperEnv for GitHub Actions Runner to add features, improve performance, or patch vulnerabilities (see our release notes).

The latest versions is: v2.8.0

HyperEnv supports minor version updates without downtime. You don’t need to be afraid of updating HyperEnv, even while jobs are running.

How to upgrade HyperEnv for GitHub Actions Runner to the latest version?

First, you need to find out the fulfillment option you are using: Bring Your Own VPC or Dedicated VPC with public subnets.

  1. Log in to the AWS Management Console.
  2. Open the AWS CloudFormation console.
  3. Select the HyperEnv stack, which is named hyperenv-github-actions in case you followed our documentation.
  4. Go to the Outputs tab.
  5. Search for the value of the output FulfillmentOption.

The following table maps the output values with a description and a CloudFormation template URL. Copy the CloudForamtion template URL, you will need it in the next step.

IdentifierDescriptionCloudFormation Template URL
public-vpcDedicated VPC with public subnetshttps://s3.amazonaws.com/awsmp-fulfillment-cf-templates-prod/6652b15b-51a9-4d22-a90a-855988f37fed/52d9b98b40d7497496ec854fec385938.template
byo-vpcBring Your Own VPChttps://s3.amazonaws.com/awsmp-fulfillment-cf-templates-prod/6652b15b-51a9-4d22-a90a-855988f37fed/27ad520f4f0f4bb89e1f158837552a64.template

Second, update the CloudForamtion stack to deploy the latest version.

  1. Select the HyperEnv stack, which is named hyperenv-github-actions in case you followed our documentation, and press the Update button as shown in the following screenshot. Upgrade HyperEnv: Step 1
  2. Select the Replace current template option. Copy and paste the CloudFormation template URL from step one into the Amazon S3 URL input field. Click the Next button. Upgrade HyperEnv: Step 2
  3. Keep the defaults in Step 2 Specify stack details and press the Next button at the bottom of the page.
  4. Same for Step 3 Configure stack options. Keep the defaults and click the Next button.
  5. Review the details shown in Step 4 Review, confirm I acknowledge that AWS CloudForamtion might create IAM resources. and press the Submit button as illustrated in the following screenshot. Upgrade HyperEnv: Step 3
  6. Now, the stack is in status UPDATE_IN_PROGRESS. Typically, the update takes about five minutes. Upgrade HyperEnv: Step 4
  7. Wait for the stack to reach status UPDATE_COMPLETE. You are now running the latest version of HyperEnv! Upgrade HyperEnv: Step 5

Are you upgrading from v1 to v2? Ensure to re-install the GitHub app as described below!

Are you upgrading from v1 to v2?

HyperEnv v1 (1.x.x) is using a backend and a public GitHub app to authenticate and authorize runners. With HyperEnv v2 (2.x.x) the public app and backend is no longer needed. The whole solution runs in your own AWS account which increases security and reliabilty.

However, it is necessary to install a private GitHub app after updating to 2.x.x as described in the following.

  1. Select the the CloudFormation stack hyperenv-github-actions and ensure it is in status UPDATE_COMPLETE.
  2. Switch to the Outputs tab and search for the output named NextStepUrl and click the shown link. Upgrade HyperEnv: Step 6

By following the NextStepUrl you will be guided through the process of installing the GitHub app next.