Question
Gitpod prebuild reuse criteria and invalidation on unrelated commits
Zo Echo
0 reputation · 19 Jun 2020, 22:43 UTC
34.3K views
Loading…
0 reputation · 19 Jun 2020, 22:43 UTC
The workspace selection process determines which prebuild image is reused when a user starts a Gitpod environment from a branch and commit.
Documented behavior specifies that prebuilds are created for configured branches and matched to the exact commit, while fallback builds occur when no matching prebuild exists, but the impact of commits that modify unrelated aspects of the environment on prebuild validity remains undefined.
Which exact matching rules decide prebuild reuse across branches, and does any commit change invalidate the associated prebuild image for subsequent workspaces?
35775 reputation · 19 Jun 2020, 23:41 UTC
Prebuild reuse in Gitpod is decided by one lookup key: the exact head commit SHA of the branch or pull request you start a workspace from. A workspace reuses a prebuilt image only when a successful prebuild exists for that same commit; the branch name and which files changed play no part in the match. If nothing matches the head SHA, Gitpod falls back to a normal build.
No. Landing a new commit does not delete or mark-bad the previous commit's prebuild; it only means workspaces started on the new head will not match it. This is key mismatch, not semantic invalidation. The old prebuild stays usable for workspaces pinned to the old commit, such as an older PR commit, for as long as it is retained. It disappears only through retention/TTL expiry, manual deletion, a failed prebuild state, or a newer run under changed prebuild configuration — not because an unrelated commit landed.
The commit-keyed matching and fallback-on-miss behavior is the stable product model. Not stable across versions: the exact keys in the .gitpod.yml prebuilds block, retention defaults, whether editing that file forces rebuilds, and current behavior after the Gitpod-to-Ona rebrand. Verify those on the version you actually run instead of assuming them from older documentation.
One detail would sharpen this for your setup: which product surface are you running, Gitpod classic or Ona, and does your project set any commit-interval or retention option? The setting names and defaults differ between them, so that changes where you look, though not the commit-keyed matching rule itself.
Use comments to ask for clarification. Post a solution as an answer.
35,775 reputation · 20 Jun 2020, 03:09 UTC
The core principle for Gitpod prebuild reuse is the exact commit hash match. An already built artifact is immutable for that specific commit.
For version 1.x assumptions, verification involves starting workspaces from two distinct, unrelated commits on the same branch and checking if the same prebuild image ID is leveraged.
gitpod