Skip to main content
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
  • AWS or GCP Enterprise runner or Ona Cloud
Note for AWS and GCP Enterprise runners: If you have an existing Enterprise runner, you’ll need to update to the latest infrastructure 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. Configure the executor to run prebuilds as yourself or a service account
  5. 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 Executor

Choose which identity runs your prebuilds:
  • User (default): Prebuilds run as the user who enabled prebuilds for the project
  • Service account: Prebuilds run as a service account, using the service account’s SCM credentials
When to use a service account:
  • Ensures prebuilds continue working regardless of individual user availability
  • Provides consistent permissions independent of user role changes
  • Clearly attributes prebuild activity to a dedicated account
Requirements for service accounts:
  • The service account must have Git authentication configured on all runners where prebuilds will run
  • The service account’s Personal Access Token must have access to the project’s repository
Note: Regardless of which executor is selected, no user secrets are used during prebuilds. Only organization and project secrets are available. Permissions: Project admins can change the executor to themselves or a service account. If another user is currently set as the executor, admins can leave it unchanged but cannot change it to a different user.

​
5. 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.

​
6. 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
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. See the timeouts overview for details on timeout limits and behavior.

​
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 Tasks and Services for Prebuilds

You can also configure automation tasks to run during prebuilds by adding the prebuild trigger: 
version: 1.0
tasks:
  seedDatabase:
    name: Seed the database with test data
    triggeredBy:
      - prebuild
    command: npm run db:seed

  downloadAssets:
    name: Download large asset files
    triggeredBy:
      - 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