Skip to main content
Early AccessPrebuilds are currently in early access. If you’re interested in trying this feature, please contact us.
This guide walks you through configuring prebuilds for your project to reduce environment startup times.

​
Prerequisites

  • Organization administrator permissions
  • An existing project with at least one environment class configured
  • Prebuilds feature enabled for your organization (contact us for early access)
  • AWS Enterprise runner or Ona Cloud (GCP support coming soon)
Note for AWS Enterprise runners: If you have an existing AWS Enterprise runner, you’ll need to update your CloudFormation stack to the latest version before you can use prebuilds.

​
Enabling Prebuilds

​
1. Navigate to Project Settings

  1. Go to your organization dashboard at https://app.gitpod.io
  2. Select your project from the projects list
  3. Click on the project to open its settings

​
2. Configure Prebuild Settings

In the project settings, you’ll find the prebuild configuration section where you can:
  1. Enable prebuilds for the project
  2. Select environment classes for which prebuilds should be created
  3. Configure the schedule for automatic prebuild creation
  4. Set timeout for prebuild execution (only configurable through the CLI right now)
Important: When you enable prebuilds, the daily schedule is activated. When you disable prebuilds:
  • The daily schedule stops running
  • New environments will no longer use existing prebuild snapshots
  • Existing prebuild snapshots remain until they expire (7 days)
You can manually trigger prebuilds at any time, even when the schedule is enabled, to create fresh prebuilds after configuration changes or to retry failed prebuilds.

​
3. Select Environment Classes

Choose which environment classes should have prebuilds created:
  • Check the boxes next to the environment classes you want to prebuild
  • Prebuilds will be created for each selected class on the configured schedule
  • Consider your team’s usage patterns when selecting classes
Tip: If your team primarily uses specific environment classes (e.g., “Regular” for most work), enable prebuilds only for those classes to optimize costs.

​
4. Configure the Schedule

Set up when prebuilds should run automatically:
  1. Daily schedule: Choose the hour (UTC) when prebuilds should trigger
  2. Recommended timing: Schedule prebuilds during off-hours (e.g., 2 AM UTC) so fresh prebuilds are ready when your team starts work
Example: If your team is in EST (UTC-5) and starts work at 9 AM, schedule prebuilds for 1 PM UTC (8 AM EST) to have fresh prebuilds ready.

​
5. Set Timeout (Via CLI)

Configure how long prebuilds can run before timing out using the Gitpod CLI: 
gitpod project configure-prebuilds <project-id> --enabled --timeout 90m
  • Default: 1 hour
  • Minimum: 5 minutes
  • Maximum: 2 hours
Adjust based on how long your build and setup commands typically take. If your builds consistently take 30 minutes, consider setting a 45-minute timeout to allow some buffer. Note: Timeout configuration is currently only available via the CLI, not through the web UI.

​
Configuring Your Dev Container for Prebuilds

To get the most out of prebuilds, structure your Dev Container configuration appropriately:

​
Commands That Run During Prebuilds

Place time-consuming setup tasks in these lifecycle hooks: 
{
  "initializeCommand": "echo 'Runs before container creation'",
  "onCreateCommand": "npm install && npm run build",
  "updateContentCommand": "npm install"
}

​
Commands That Run After Prebuilds

Place user-specific or session-specific commands here: 
{
  "postCreateCommand": "echo 'Runs after container creation'",
  "postStartCommand": "npm run dev",
  "postAttachCommand": "echo 'Welcome!'"
}

​
Configuring Automations for Prebuilds

You can also configure automation tasks to run during prebuilds by adding the prebuild trigger: 
version: 1.0
tasks:
  - name: seed-database
    description: Seed the database with test data
    triggers:
      - prebuild
    command: npm run db:seed
    
  - name: download-assets
    description: Download large asset files
    triggers:
      - prebuild
    command: ./scripts/download-assets.sh
Tasks with the prebuild trigger will execute during prebuild creation, alongside your Dev Container lifecycle commands. Note: Organization and project secrets are available to automation tasks during prebuilds, but user secrets are not. Ensure any credentials needed for prebuild tasks are configured at the organization or project level.

​
Manually Triggering a Prebuild

In addition to scheduled prebuilds, you can manually trigger prebuilds:

​
Via Web UI

  1. Navigate to your project settings
  2. Click the Prebuild button in the top right corner
This triggers a prebuild for all selected environment classes. Manual prebuilds are useful for:
  • Testing prebuild configuration changes
  • Creating a fresh prebuild after significant code changes
  • Preparing prebuilds before scheduled time

​
Via CLI

You can also trigger prebuilds for specific environment classes using the CLI: 
gitpod prebuild trigger <project-id> --environment-class-id <class-id>

​
Verifying Your Setup

After enabling prebuilds, test your configuration to ensure everything works correctly:
  1. Trigger a manual prebuild to verify it completes successfully
  2. Check the prebuild logs for any errors or warnings
  3. Create a new environment and confirm it starts from the prebuild
  4. Verify the schedule is set correctly for your timezone
If the prebuild fails, check the logs for error messages and ensure all required secrets are configured at the organization or project level.

​
Best Practices

​
Optimizing for Speed and Cost

Only install dependencies necessary for development. Schedule prebuilds during off-hours (e.g., 2 AM UTC) so fresh prebuilds are ready when your team starts work. Start by enabling prebuilds for one or two commonly used environment classes, then expand based on usage patterns and cost considerations.

​
Structuring Your Commands

Place stable, time-consuming operations in prebuild commands: dependency installation, database seeding, and asset downloads. Reserve postCreateCommand for dynamic operations like starting dev servers or user-specific setup. Ensure all commands are idempotent so they can run multiple times safely.

​
Managing Secrets

Use organization secrets for shared credentials needed during builds, and project secrets for project-specific credentials. Remember that user secrets aren’t available during prebuilds, so ensure any required credentials are configured at the organization or project level.

​
Troubleshooting Common Issues

Prebuild fails to complete: Check logs for error messages, verify secrets are configured correctly, and ensure commands don’t require user interaction. If builds consistently timeout, increase the timeout using the CLI. Environment doesn’t use prebuild: Verify a successful prebuild exists for the environment class, check it’s less than 7 days old, and ensure the environment class matches exactly. Prebuild succeeds but environment has issues: Some commands may need to run per-environment rather than in the prebuild. Move user-specific or session-specific commands to postCreateCommand, and verify file permissions are correct after the snapshot. For more detailed troubleshooting guidance, see Managing Prebuilds.

​
Next Steps