Setting up AWS runners

Prerequisites

• Admin access to the Gitpod organization.
• AWS account with permissions to deploy the CloudFormation stack.

Create AWS runner

Go to Settings -> Runners, and press Setup an AWS runner:

Choose a name and select the AWS region to deploy the runner into, then press Create. This creates the runner reference in Gitpod. You will now need to run the CloudFormation stack to fully deploy your runner.

Note: runners are regional, and can only launch environments in the AWS region they are deployed in. For a multi-region support we recommend to set up multiple runners in different regions. The region cannot be changed once deployed, but you can deploy multiple runners in different regions.

CloudFormation template

Next, ensure you are signed into the right AWS account in the AWS console, and then press Open AWS CloudFormation to start deploying the runner into your AWS account. This will link you to the AWS console to create the CloudFormation stack:

Most parameters are auto-filled already. For Network Configuration, choose a VPC (e.g. the default VPC) and one or more Availability Zones and subnets. The runner will create environments in the selected network configuration values.

When done with configuring the stack parameters, press Create stack. The stack is relatively simple and includes e.g. an ECS service and DynamoDB.

Wait until the Stack is deployed successfully, and return to Gitpod Desktop. This can take a few minutes. Once deployed you should see a screen like this:

Configuring repository access

Before the runner can be used to launch any environment, it must be configured with a provider that can access your repos (this includes public repositories).

Press Add a provider and select one of the supported providers such as GitHub:

Configure the host, or leave the default if using github.com. If you want to support multiple hosts, you can add a separate provider for each host.

Next, choose at least one of OAuth or Personal Access Token support. You can set up an OAuth app to make it easy for users to sign in quickly. Personal Access Token allows users to provide their own PAT to sign in. Users will be prompted to authenticate when they start a new environment on the runner.

Press Save once done. You can now start environments for repos on the specified host:

Whenever a user starts an environment for the first time for that host, they will get prompted to authenticate first, and get the option to authenticate through the OAuth app or using a PAT token (whichever is configured in the integration). Once authenticated, the token is encrypted and stored to be remembered for the next time the user creates an environment for this host.

When an admin disables OAuth/PAT support in an integration, or deletes an integration entirely for a host, any existing tokens obtained for the host through the disabled/deleted authentication method will get deleted and users might have to re-authenticate before they can create environments again for that host.