Enterprise Runner is exclusively available to customers on the Enterprise tier. If you’re an Enterprise customer, contact your Gitpod account manager for more information.
Deploy your Enterprise AWS Runner using our enhanced CloudFormation template with custom ingress capabilities. This comprehensive guide walks you through the complete deployment process using the AWS Management Console.

​
Prerequisites

Before starting the deployment, ensure you have:
  • Admin access to the Gitpod organization
  • AWS Account with appropriate permissions to create CloudFormation stacks
  • VPC and Subnets configured in your AWS account
  • SSL/TLS Certificate provisioned in AWS Certificate Manager (ACM) with both root domain and wildcard subdomain SANs
  • Domain Name that you control and can modify DNS records for
  • Permissions to deploy CloudFormation stacks with IAM resources

​
Create Enterprise Runner in Gitpod

Go to Settings -> Runners, and press Setup a new runner:

Runners in settings

After choosing AWS from the list of available providers, continue with the Enterprise Runner template.

Provider selection

CloudFormation Template selection

Choose the Enterprise Runner template, provide a name and select the AWS region to deploy the Runner into, then press Create. This creates the Runner reference in Gitpod.
Runners are regional, and can only launch Environments in the AWS region they are deployed in. For multi-region support we recommend setting up multiple Runners in different regions. The region cannot be changed once deployed.

Add an AWS Runner

Runner details

​
CloudFormation Template Deployment

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. The template is organized into several parameter groups and has to be filled out carefully.

​
Gitpod Configuration

Core authentication and API connection settings for your Gitpod Runner.
ParameterDescriptionRequired
Runner IDUnique identifier for your Runner (auto-generated by Gitpod)✅ Yes
Exchange TokenAuthentication token for the EC2 Runner (auto-generated by Gitpod)✅ Yes
API EndpointURL of the Gitpod API (auto-generated by Gitpod)✅ Yes
⚠️ Important: These values are automatically generated by Gitpod when you create a Runner configuration. Do not modify these values manually.

​
Network Configuration (Mandatory)

VPC and subnet settings for deploying the Runner infrastructure.
ParameterDescriptionExample ValueRequired
VPCThe VPC where the Runner will be deployedvpc-12345abcd✅ Yes
Availability ZonesAZs for high availability (select 2-3)us-east-1a, us-east-1b✅ Yes
EC2 Instances SubnetPrivate subnets for EC2 instances (can be non-routable from internal network). Should match the number of AZssubnet-123abc, subnet-456def✅ Yes
Loadbalance SubnetsSubnets for load balancer with CIDR ranges routable from your internal network. Should match the number of AZssubnet-123abc, subnet-456def✅ Yes
Recommendations:
  • Select 2-3 Availability Zones for high availability
  • EC2 subnets: Use private subnets, must be sufficiently large for your expected workload
  • Load balancer subnets: Must have CIDR ranges routable from your internal network for user access
  • Ensure connectivity from user locations via VPN, Direct Connect, or Transit Gateway

​
DNS Configuration

Domain name, SSL certificate, and load balancer visibility settings.
ParameterDescriptionExample ValueRequired
Load Balancer VisibilityChoose between internal or internet-facinginternal✅ Yes
Domain NameYour domain name for Gitpod accessyourdomain.com✅ Yes
Certificate ARNARN of your SSL certificate from ACMarn:aws:acm:us-east-1:123456789012:certificate/abc123...✅ Yes
Load Balancer Visibility Options:
  • internal: Load balancer is only accessible from within your VPC (recommended for private deployments)
  • internet-facing: Load balancer is accessible from the internet (only if using public subnets)

​
Network Configuration (Optional)

Configure additional network settings for enterprise security requirements.
ParameterDescriptionExample ValueRequired
Custom Security Group for Load BalancerSecurity group to attach to the load balancer for traffic controlsg-abcdef123❌ Optional
HTTP ProxyHTTP proxy server URLhttp://proxy.company.com:8080❌ Optional
HTTPS ProxyHTTPS proxy server URLhttps://proxy.company.com:8080❌ Optional
No ProxyComma-separated list of hosts to bypass proxy.internal,169.254.0.0/16,...⚠️ Required if proxy configured
Custom CA CertificateCustom certificate authority from SSM/Secrets Manager{{resolve:ssm:/gitpod/ca-cert}}❌ Optional
Security Group Behavior:
  • If not provided: An automatic security group will be created that allows all traffic (0.0.0.0/0) to ports 80 and 443
  • If provided: You can specify a custom security group to narrow down the allowed traffic sources for enhanced security
Proxy Configuration: When configuring HTTP/HTTPS proxy, NO_PROXY must include: .internal, 169.254.0.0/16, app.gitpod.io, and .amazonaws.com. Proxy Update Behavior:
  • Runner infrastructure: Changes take effect immediately after CloudFormation update
  • Component-specific timing:
    • Content initialization: Effective after environment restart
    • Devcontainer: Effective after rebuild
    • Docker in Docker: Effective after container recreation
Custom CA Certificate: Use CloudFormation dynamic references to retrieve certificates from AWS SSM Parameter Store or Secrets Manager. For syntax details, see SSM Parameter Store or Secrets Manager documentation.
Custom CA certificates work in runner, content init (SCM), and docker pull operations. However, they are not supported in devcontainer and devcontainer image build phases - you must add CA certificates to your images for these use cases.

​
Review and Deploy

  1. Review Configuration
    • Verify all parameters are correctly set
    • Review the resource summary
  2. Acknowledge Capabilities
    • Check the box acknowledging that CloudFormation will create IAM resources
    • This is required for the stack to create necessary service roles
  3. Create Stack
    • Click “Create stack” to begin deployment
    • Monitor the deployment progress in the Events tab
The CloudFormation stack deployment typically takes 20-25 minutes.

​
Monitoring Deployment

  1. Stack Status
    • Monitor the stack status on the CloudFormation dashboard
    • Any errors will be displayed in the Events tab
  2. Event Monitoring
    • Click on the “Events” tab to see real-time deployment progress

​
Post-Deployment DNS Configuration

​
Retrieve Load Balancer DNS Name

After successful deployment:
  1. Navigate to Outputs Tab
    • Click on your stack name
    • Go to the “Outputs” tab
  2. Locate DNS Names
    • Find the output value: LoadBalancerDNS: internal-LoadBa-XXXXX-123456789.us-east-1.elb.amazonaws.com

​
Configure DNS Records

Create DNS records in your domain registry or DNS provider for the exact domain name you specified in the CloudFormation parameters.

​
AWS Route 53

If you’re using AWS Route 53 to manage your domain, use alias records for the most AWS-native configuration:
  1. Navigate to Route 53 Console
  2. Create Alias Records
    • Click “Create record”
    • Toggle the Alias switch to enable alias functionality
    • Configure the following records:
TypeNameAlias Target
Ayourdomain.comSelect “Alias to Network Load Balancer” → Choose your region → Select your load balancer
A*.yourdomain.comSelect “Alias to Network Load Balancer” → Choose your region → Select your load balancer

Route 53 Create Alias Records for Network Load Balancer

Advantages of Route 53 Alias Records:
  • No additional charges for alias queries
  • Automatic health checking
  • Better performance with shorter resolution times
  • AWS-native integration with load balancers

​
Standard DNS Providers (CNAME Records)

For other DNS providers or if you prefer CNAME records:
TypeNameValueTTL
CNAMEyourdomain.cominternal-LoadBa-XXXXX-123456789.us-east-1.elb.amazonaws.com300
CNAME*.yourdomain.cominternal-LoadBa-XXXXX-123456789.us-east-1.elb.amazonaws.com300
Example DNS Configuration: If you entered yourdomain.com as your domain name parameter, configure: 
yourdomain.com.     CNAME   internal-LoadBa-XXXXX-123456789.us-east-1.elb.amazonaws.com.
*.yourdomain.com.   CNAME   internal-LoadBa-XXXXX-123456789.us-east-1.elb.amazonaws.com.
⚠️ Important: Replace yourdomain.com with the exact domain name you entered in the CloudFormation parameters.
  • DNS changes typically propagate within 5-60 minutes
  • You can verify DNS resolution using tools like nslookup or dig
  • Test both the root domain and a wildcard subdomain

​
Verification and Testing

  1. Internal Network Test
    • Verify that the load balancer is accessible from within your VPC
    • Test from an EC2 instance in the same VPC: curl -k https://yourdomain.com/_health
  2. DNS Resolution Test 
    nslookup yourdomain.com
nslookup test.yourdomain.com

​
Important Stack Outputs

After deployment, the following outputs provide important information for integration:
Output NameDescriptionUsage
LoadBalancerDNSNetwork Load Balancer DNS namePoint your DNS records here
EnvironmentRoleArnEC2 Environment Role ARNUsed by Gitpod Environments for all operations
InstanceProfileNameOutputEC2 Instance ProfileAttached to Runner EC2 instances

​
Private VPC Endpoints (Optional)

For enhanced security, you can connect to Gitpod’s management plane using AWS PrivateLink instead of traversing the public internet.
Cost consideration: VPC endpoints incur additional AWS charges (~$7.20/month per endpoint per AZ plus data processing fees). See AWS PrivateLink pricing for details.
us-east-1 region specific: When creating VPC endpoints in the us-east-1 region, disable cross-region support. This is due to availability zone mapping differences between AWS accounts that can prevent endpoint creation. The endpoint only needs to exist in one AZ within your VPC - clients in other AZs can still reach it via DNS.

​
Creating the VPC Endpoint

Create an Interface VPC Endpoint to connect privately to Gitpod’s management plane.
Before you begin: You’ll need your VPC ID, subnet IDs, and security group ID. You can find these in the AWS VPC Console or from your CloudFormation stack outputs.Important: Your VPC must have both DNS hostnames and DNS resolution enabled for private DNS names to work properly. You can check and enable these in the VPC Console under Actions → Edit VPC settings.

​
Using AWS CLI

# Replace vpc-xxx, subnet-xxx, and sg-xxx with your actual IDs
aws ec2 create-vpc-endpoint \
    --vpc-id vpc-xxx \
    --service-name com.amazonaws.vpce.us-east-1.vpce-svc-08de744d433e60ff2 \
    --vpc-endpoint-type Interface \
    --subnet-ids subnet-xxx subnet-xxx \
    --security-group-ids sg-xxx \
    --private-dns-enabled \
    --service-region us-east-1
For more CLI options and examples, see the AWS CLI reference for create-vpc-endpoint.

​
Using AWS PowerShell

# Replace vpc-xxx, subnet-xxx, and sg-xxx with your actual IDs
New-EC2VpcEndpoint `
    -VpcId "vpc-xxx" `
    -ServiceName "com.amazonaws.vpce.us-east-1.vpce-svc-08de744d433e60ff2" `
    -VpcEndpointType "Interface" `
    -SubnetId @("subnet-xxx", "subnet-xxx") `
    -SecurityGroupId @("sg-xxx") `
    -PrivateDnsEnabled $true `
    -ServiceRegion "us-east-1"
For more PowerShell options and examples, see the AWS PowerShell reference for New-EC2VpcEndpoint.

​
Using AWS Management Console

  1. Navigate to VPC Console
  2. Create Endpoint
    • Click “Create endpoint”
    • Name tag (optional): Enter a descriptive name like gitpod-management-plane
    • Service type: Select “Endpoint services that use NLBs and GWLBs”
  3. Service Settings
    • Service name: Enter com.amazonaws.vpce.us-east-1.vpce-svc-08de744d433e60ff2
    • Enable Cross Region endpoint: Check this box to connect across regions (Note: For us-east-1 region, leave this unchecked)
    • Region: Select us-east-1 as the region
    • Click “Verify service” to confirm the service is available

VPC Endpoint Service Settings - Enable Cross Region Support

  1. Network Settings
    • VPC: Select the same VPC where your runner is deployed
    • Enable DNS name: Check this box to enable private DNS names (this allows app.gitpod.io to resolve to the endpoint)
    • Subnets: Choose private subnets in available AZs (can be the same subnets as your EC2 runner instances)
    • Security groups: Select or create a security group that allows HTTPS traffic (port 443, inbound). Include the runner security group and the security group for environment access (you can find these in the Output section of the Runner Cloud Formation template).

VPC Endpoint Network Settings - Enable DNS Names

  1. Create and Verify
    • Click “Create endpoint”
    • Wait for the endpoint status to become “Available”
For detailed console instructions, see the AWS documentation on creating interface endpoints.

​
Security Group Configuration

Your VPC endpoint security group needs these rules: Inbound Rules:
  • Type: HTTPS (443)
  • Source: Your runner subnets CIDR or the security group attached to your runner instances
  • Description: Allow runner access to Gitpod management plane
Outbound Rules:
  • Type: All traffic
  • Destination: 0.0.0.0/0 (or keep the default outbound rule)

​
Verification

After creating the VPC endpoint:
  1. Check endpoint status in the VPC console
  2. Verify private DNS resolution in your VPC: 
    nslookup app.gitpod.io
    This should resolve to private IP addresses within your VPC
  3. Confirm private connectivity in Gitpod dashboard:
    • Navigate to Settings → Runners in your Gitpod dashboard
    • Check your runner details - the Connection type should show as “Private”

Runner Dashboard showing Private Connection Type

With private DNS enabled, app.gitpod.io will automatically resolve to your VPC endpoint’s private IP addresses, providing seamless private connectivity.
For more information on VPC endpoints concepts and architecture, see the AWS PrivateLink documentation.

​
Next Steps

Once your Enterprise Runner is deployed, configure your repository access and Environment classes.

Configure Repository Access

Set up access to your repositories

Troubleshoot

Resolve common issues including networking problems and Runner configuration