Setup Guide

Do you prefer watching a video instead of reading through instructions? Here you go. Otherwise, please skip the video.

1. GitHub

First, install our GitHub app to grant HyperEnv for GitHub Actions Runner access to a GitHub organization and its repositories.

1. Go to GitHub app and click Install.
2. Select one of the shown organizations. Please note, installations for a user are not yet supported. Also ensure, that the GitHub organisations owns at least 1 repository.
3. Grant HyperEnv for GitHub Actions Runner access to all the repositories belonging to the organization and click Install & Authorize.
4. Note down the Installation ID and HyperEnv Key. You will need both when deploying HyperEnv for GitHub Actions Runner to your AWS account.
5. Contine with deploying HyperEnv for GitHub Actions Runner to your AWS account.

2. AWS Marketpalce

HyperEnv for GitHub Actions Runner is available on the AWS Marketplace. The following steps describe how to subscribe to HyperEnv for GitHub Actions Runner.

1. Go to AWS Marketplace and click Continue to Subscribe.
2. Read through the terms and click Accept Terms.
3. It will take a while to enable the susbcription.
4. Wait until the subscription is active and click Continue to Configuration.
5. Keep the defaults for fullfillment option and software version. Choose the region you want to launch HyperEnv for GitHub Actions Runner in and click Continue to Launch.
6. Keep the defaults and click Launch.
7. You are redirected to CloudFormation.

3. Launch with CloudFormation

We provide a CloudFormation template that spins up and configures all the releveant AWS resources - EC2 instances, security groups, an EFS file system with backups enabled, and many more - for you in an automated way.

1. Step Specify template
   1. The AWS Marketplace populates all the configuration parameters for step 1. Proceed by clicking Nex.
   
2. Step Specify stack details
   1. Set a name for the CloudFormation stack. We recommend hyperenv-github-actions.
   2. Continue with the required configuration parameters.
      1. VpcId (Bring Your Own VPC only) - The VPC used when launching EC2 instances to execute GitHub runners.
      2. SubnetIds (Bring Your Own VPC only) - The subnets used when launching EC2 instances to execute GitHub runners. Define at least two subnets with route to Internet or NAT Gateway.
      3. KeyPair - The key pair allowing you to establish a SSH connection with the EC2 instance executing the GitHub runner.
      4. GitHubInstallationId - The GitHub Installation ID you noted down when following section 1 of this guide.
      5. HyperEnvKey - The HyperEnv Key you noted down when following section 1 of this guide.
      
   3. Review the rest of the parameters and go with the defaults (recommended).
3. Step Configure stack options

   There is nothing to configure here. Keep the defaults and click Next

   
4. Step Review

   Scroll to the bottom of the page, enable I acknowledge that AWS CloudFormation might create IAM resources, and click Create stack.

   
5. The stack status is CREATE_IN_PROGRESS. Reload the list of stacks from time to time and …
6. … wait until the CloudFormation stack hyperenv-github-actions switches to CREATE_COMPLETE.

Next, create a GitHub workflow to test HyperEnv for GitHub Actions Runner.

4. Test HyperEnv for GitHub Actions Runner

Add the file .github/workflows/hyperenv-test with the following content to a repository belonging to the GitHub organisation that you selected in section 1.

The file should

name: hyperenv-test
on:
  workflow_dispatch
jobs:
  hyperenv-test:
    runs-on: hyperenv
    steps:
    - run: 'echo "Hello HyperEnv"'
        

After commiting and pushing the changes, open the Actions tab of the GitHub repository as shown in the following figure.

1. Select the workflow hyperenv-test from the sub navigation.
2. Press the Run workflow button.
3. Select the main or master branch.
4. Press the green Run workflow button.

It will take 1-2 minutes until the job succeeds.

Next, update exsisting GitHub workflows.

5. Update GitHub workflows

In case you are already using GitHub Actions and want to execute jobs on HyperEnv updating the workflows is required.

To run GitHub jobs on HyperEnv for GitHub Actions Runner, you need to update your workflows. To do so look into the .yml files in your repository's .github/workflows folder.

The runs-on property defines where GitHub Actions runs the job. Search for ubuntu-22.04 and replace it with hyperenv or the lables that you defined in the GitHubRunnerLabels parameters in the previous section.

name: example-workflow
jobs:
  example-job:
    runs-on: hyperenv
    steps:
    - ...