Gitpod Workspace Starts Slowly Because the Prebuild Didn't Run: A Diagnostic Guide

The symptom: init runs in front of you

You open a Gitpod workspace expecting a warm start, and instead you watch dependency installation scroll by in a terminal for several minutes. The useful mental model: a prebuild is Gitpod running your init tasks ahead of time, on a commit, so that a workspace opened later starts with that work already done. When the prebuild didn't run, didn't succeed, or doesn't match your commit, Gitpod falls back to running init at workspace start — which is exactly the slow behavior you're seeing.

Recognizable signs:

• Workspace start takes minutes instead of seconds.
• The init task (dependency install, code generation) executes in the foreground terminal instead of being already complete.
• The project's prebuilds list in the Gitpod dashboard shows no successful prebuild for your commit or branch (UI paths vary by deployment; look for the project's prebuild history).

Cause-to-check map

Ordered checks

1. Confirm the prebuild exists for your exact commit. In the Gitpod dashboard, open the project's prebuild list and match the commit SHA to your branch HEAD. A prebuild for an older commit is not reused — every push invalidates the previous one, so the first workspace after a push may run init until the new prebuild finishes.
2. Check the prebuild's status and logs. A failed prebuild (any init command exiting non-zero) is silently skipped at workspace start. The prebuild log is the authoritative source — read it before changing anything.
3. Verify the webhook. In your Git provider's repository settings, find the webhook or app integration pointing at Gitpod and inspect recent deliveries. Push events should return 2xx. Missing deliveries, 4xx/5xx responses, or a rotated secret mean no prebuild is ever enqueued — no matter how correct your .gitpod.yml is.
4. Audit .gitpod.yml task placement. Anything under command runs at every workspace start and is never prebuilt. Long installs belong in init.
5. Check branch scope. Project settings can restrict prebuilds to the default branch or an allowlist. A feature branch with no prebuild may be working as configured.

Fixes tied to findings

Webhook or integration broken

Reinstall or re-authorize the Git provider app for the repository, or re-create the webhook with the correct secret and event scope (push events at minimum). After fixing, push a trivial commit and confirm a new prebuild appears in the dashboard. This is the only fix here that changes state outside Gitpod; note the previous secret/configuration before rotating so you can restore it if the new integration misbehaves.

Work in the wrong task block

Move long-running setup into init. A typical split:

tasks:
  - name: app
    init: |
      npm ci
      npm run build
    command: |
      npm run dev

npm ci is prebuilt; the dev server stays in command because it must run interactively. Also check whether your init depends on user-specific environment variables or secrets — prebuilds run without user context, so an init that reads a personal secret will fail in the prebuild and succeed (or prompt) at workspace start, producing exactly this confusing symptom.

Prebuild failing

Fix the failing command shown in the prebuild log. Common causes: a dependency that requires network access to a private registry without credentials available in prebuild context, or a script that assumes an interactive shell. Make init idempotent and non-interactive.

Stale-commit prebuilds

No fix needed — this is expected. If your team pushes frequently and prebuilds take long, the practical mitigation is keeping init fast (cache-friendly install commands, avoiding redundant codegen) so the post-push gap is short.

Verifying the fix

A reliable end-to-end check:

1. Add a temporary marker to init: date > /tmp/prebuild-marker.
2. Push the change and wait for the prebuild to show successful in the dashboard for that commit.
3. Open a workspace from that exact commit and check cat /tmp/prebuild-marker exists, and that init did not re-run in the terminal.

You can also deliberately break init (add exit 1) on a throwaway branch and confirm the prebuild is marked failed and the next workspace falls back to running init at start — this confirms you understand the failure path you're diagnosing.

When to escalate

Escalate to your platform admin or Gitpod support when:

• Prebuild logs show infrastructure errors — image pull failures, runner timeouts, workspace snapshot errors — rather than your task failing.
• Webhook deliveries succeed (2xx) but no prebuild is ever enqueued.
• Prebuilds succeed but workspaces still don't reuse them for the matching commit.

Include the prebuild ID, commit SHA, and webhook delivery IDs in the report.

Note: Gitpod's dashboard layout, setting names, and the differences between legacy self-hosted Gitpod and the current offering change over time. Confirm exact UI paths and configuration keys against your deployment before relying on them.