Setting up AWS runners
Learn how to set up AWS runners for Gitpod Flex. This guide covers prerequisites, deployment steps, and configuring repository access to launch cloud development environments in your AWS infrastructure.
Prerequisites
- Admin access to the Gitpod organization.
- An AWS account with networking and permissions to deploy the CloudFormation stack.
Create AWS runner
Go to Settings -> Runners, and press Setup an AWS runner:
Runners in settings
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.
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.
Add a AWS runner
Runner details
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:
Create stack in AWS
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.
Parameters configuration in AWS
When done with configuring the stack parameters, press Create stack. The stack is relatively simple and includes e.g. an ECS service and DynamoDB.
AWS stack capabilities
AWS stack component diagram
Wait until the Stack is deployed successfully, and return to Gitpod Desktop.
Once deployed you should see a screen like this:
AWS runner configuration complete
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:
Repository provider
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.
GitHub OAuth
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.
Setup OAuth
Press Save once done. You can now start environments for repos on the specified host:
AWS runner setup done
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.
Was this page helpful?