Accelerate Gitpod Workspaces with Prebuilds: Setup and Verification

Desired outcome

Reduce the time it takes to start a Gitpod workspace from several seconds to under a second by using a prebuilt snapshot of the project’s initialization tasks.

Prerequisites

• A Gitpod account with the target repository connected.
• Write access to the repository to add or edit .gitpod.yml.
• Permission to enable prebuilds (repository admin or maintainer role).
• Optional: a personal access token with repo scope if you prefer to trigger prebuilds via the Gitpod API.
• Gitpod CLI (gp) installed locally if you want to use CLI commands (not required for the dashboard method).

Procedure

1. Add or verify .gitpod.yml

   Ensure the repository contains a .gitpod.yml file that defines the initialization tasks you want to snapshot. A minimal example:

   # .gitpod.yml
   image: gitpod/workspace-full
   
   tasks:
     - init: npm install
       command: npm run build
   
   ports:
     - port: 3000
       onOpen: open-preview
   

   Commit and push this file to the branch where you want prebuilds enabled.

2. Enable prebuilds for the branch
   1. Open the repository in the Gitpod dashboard (https://gitpod.io/#/<workspace‑url>).
   2. Navigate to Settings → Prebuilds.
   3. Toggle the switch for the target branch (e.g., main) to Enabled.
   4. Optionally set prebuilds: in .gitpod.yml to enforce the setting:

   # .gitpod.yml (add at top level)
   prebuilds:
     enabled: true
   

3. Trigger the first prebuild

   Prebuilds start automatically on each push to the enabled branch. To trigger one immediately without waiting for a push:

   1. Using the dashboard: open the Prebuilds page, click Trigger prebuild for the branch.
   2. Using the API (requires a personal token):

   # Replace placeholders
   curl -X POST "https://api.gitpod.io/api/v0/workspace/prebuilds" \
     -H "Authorization: Bearer <PERSONAL_TOKEN>" \
     -H "Content-Type: application/json" \
     -d '{
       "repository": "<OWNER>/<REPO>",
       "branch": "<BRANCH>",
       "snapshot": true
     }'
   

   The API call returns a JSON object with a prebuildId you can use to track progress.

4. Monitor prebuild status

   In the Gitpod dashboard under Prebuilds you will see columns:

   • Queued – waiting for a builder.
   • Building – the init tasks are running.
   • Ready – snapshot stored and available.

   Note the timestamp; a recent Ready status indicates a fresh snapshot.

5. Launch a workspace from the prebuild

   Open the repository in Gitpod (e.g., https://gitpod.io/#/<OWNER>/<REPO>) or click New Workspace from the dashboard. The workspace should start from the snapshot, bypassing the init tasks.

6. Verify the speed improvement

   Measure the time from clicking “New Workspace” to the appearance of the terminal prompt:

   1. Open the browser’s developer tools (F12) and enable the Network tab.
   2. Record the timestamp when the request to start the workspace is sent.
   3. Record the timestamp when the terminal shows the prompt (you can also watch for the ready event in the console).
   4. Subtract the two times. Compare with a workspace launched from a branch without prebuilds (disable prebuilds temporarily).

   If the prebuild is working, the startup time should be noticeably lower (often under one second for modest projects).

Expected checks

• Dashboard shows a Ready prebuild with a timestamp within the last few minutes/hours.
• Workspace launch skips the npm install and npm run build steps visible in the terminal logs.
• Measured startup time is reduced compared to a non‑prebuild launch.

Recovery options (if the prebuild becomes stale or you need to revert)

Enabling prebuilds creates a stored snapshot; this is a state‑changing operation, so you can roll back by:

1. Disable prebuilds – return to Settings → Prebuilds and toggle the branch off. New workspaces will fall back to the regular init flow.
2. Delete the stale prebuild – in the Prebuilds list, select the entry and click Delete. The next push or manual trigger will create a fresh snapshot.
3. Rebuild after changes – if you modify Dockerfile, init tasks, or dependencies, the existing prebuild is outdated. Simply disable and re‑enable prebuilds (or delete and trigger a new one) to capture the updated state.

Limitations and practical verification

• Prebuild storage counts toward your workspace quota; older prebuilds are garbage‑collected after 7 days of inactivity.
• Enabling prebuilds for many branches or large repositories can increase storage usage and may affect billing limits.
• If the init tasks rely on external services that change state (e.g., a database), the snapshot may become invalid; consider making those services part of the workspace startup rather than the prebuild.

To confirm that a prebuild is being used, check the workspace logs for the absence of the init task output and verify the Ready badge in the dashboard. If the logs still show the init steps running, the prebuild was not applied—re‑check the prebuild status and ensure the branch is still enabled.