Prebuilds save time by executing init tasks defined in the .gitpod.yml ahead of time. init tasks can take a lot of time, like a build or test suite, etc. When a workspace is started later on, the prebuild is used as a base for the new workspace. In effect, init is already done and developers are immediately ready-to-code.
For understanding prebuilds, it helps to be familiar with the following Gitpod features:
  1. Imported repositories
  2. Tasks
  3. .gitpod.yml

​
Configuring prebuilds

To configure a prebuild for a repository, you have to:
  1. Add an init or before task in the repository’s .gitpod.yml.
  2. Import the repository (see Imported Repositories).
  3. Enable prebuilds in the repository’s settings.

​
Configuring prebuild tasks

A prebuild cannot be executed unless you tell Gitpod explicitly which steps in your .gitpod.yml to run. You can do this by ensuring you have either an init or before task present. The below example .gitpod.yml shows a repository that will run npm install inside a prebuild. The command task with npm start is not executed in the prebuild as it’s assumed to be a long-running process, e.g. a web server. 
tasks:
    - init: |
          npm install
    - command: |
          npm start
Immediately test your changes using gp validate --prebuild.

​
Enabling prebuilds

To enable prebuilds for a repository:
  1. Select it under /repositories
  2. Under prebuild settings, flip the switch and optionally, configure them to your liking.
When a prebuild runs successfully, you will see a message similar to the following in your workspace output: 
🍊 This task ran as a workspace prebuild
⏱️ Well done on saving 6 minutes
Since prebuilds are included in all our metered pay-as-you-go plans, configuring prebuild settings in your project should help with managing prebuild usage and costs.

​
How it works

​
Triggers

Gitpod uses “workspace started” as trigger to decide whether or not to run a fresh prebuild. How often a prebuild is actually executed can be configured in the prebuild settings. If that is not enough, you can also use our API to trigger prebuilds like this: 
curl -X POST -H "Content-Type: application/json" \
    --data '{"configurationId":"<repositorySettingsId>", "gitRef": "<branch/tag>"}' \
    -H "Authorization: Bearer <PAT>" \
    https://gitpod.io/public-api/gitpod.v1.PrebuildService/StartPrebuild
See What are webhook-based prebuild activity triggers? below for more information about prebuilds triggered by webhooks.

​
Use of prebuilds

When a workspace is started, Gitpod will search the last 100 ancestor commits for a successful prebuild to use as a base for that workspace. This search is interrupted in two scenarios:
  • the Dockerfile referenced in the .gitpod.yml changed (if configured)
  • the tasks definition for either a before or init task in the .gitpod.yml changed
In both cases the assumption that a prior prebuild can be used as base for the new workspace is likely to not be true anymore.

​
Prebuild settings

These are the options that can be set in every Organization to adjust prebuild behavior to fit your needs and control costs.

​
Commit interval

To balance frequency of prebuilds with repository activity (e.g. frequency of commits) you can adjust the number of commits that are skipped between prebuilds. The default is 20. For example:
  • when workspace A is started, and there has been no prior prebuild, a fresh prebuild 1 is executed for the exact commit referenced.
  • when workspace B is started on the same repository, 15 commits after workspace A, no fresh prebuild will be triggered, because of the configured commit interval
  • when workspace C is started on the same repository, 21 commits after workspace A, a fresh prebuild 2 is executed for that very commit

​
Filtering prebuilds

A prebuild filter allows you to further constrain when a prebuild is actually execute. Prebuild filters help to save costs by not running prebuilds unnecessarily. You can filter prebuilds in your project settings by:
  1. Enabling (or disabling) prebuilds entirely
  2. Constraining execution to certain git branches:
    • all branches (the default setting)
    • the default branch only (e.g. main)
    • any branches specified via glob pattern

​
Debugging prebuilds

If an init tasks fails, these are the ways to debug it and understand why.

​
Use gp validate to test changes to .gitpod.yml

Running gp validate --prebuild in the workspace you are editing the .gitpod.yml in simulates the execution of a prebuild right in your workspace. This offers the best turnaround time for debugging a prebuild.

​
View prebuilds

You can find a log of past prebuilds of your imported repositories on the /prebuilds page. Additionally, you can also filter for a specific repository or only show prebuilds in a specific state in the dropdowns at the top of the page.

​
Rerun a prebuild

Prebuilds can be triggered manually for debugging purposes. To rerun a prebuild:
  1. Select the desired prebuild from the prebuilds list.
  2. Click “Rerun prebuild”.

​
Start debug workspace

If you need to inspect the file system of a “Failed” (or “Ready”) prebuild, you can start a workspace right on that prebuild using the “Start Debug Workspace” button.

​
Prebuild limitations

​
Only the /workspace directory is persisted from a prebuild

Once a prebuild is completed, a snapshot of the filesystem is taken. However, this snapshot only includes the /workspace directory. Other directories like the home directory are not saved by prebuilds. To ensure the necessary files are saved, copy them to the /workspace directory before the prebuild completes, and/or restore those files in your command task.

​
Garbage collection

Prebuilds will be garbage-collected after 7 days of not being used to create new workspaces. The process of garbage collection deletes all of the prebuild’s files and logs and removes the prebuild from the list in /prebuilds. To see a list of all prebuilds that ever ran, please consult Gitpod’s usage report.

​
Prebuilds have a 1 hour time limit

Prebuilds have a timeout of 1 hour. If your before and init tasks combined exceed 1 hour, your prebuild will be terminated.

​
Prebuilds are only available to organization members

Even if your repository is public, only members of your Gitpod Organization will have access to its prebuilds. Public contributors to your repository will not be able to use prebuilds at this time.

​
Frequently Asked Questions (FAQs)

​
My prebuilds are not triggering after my specified number of commits, what should I do?

For new repository setups (June 2024 onwards), Gitpod is no longer installing webhooks to get information about when to trigger prebuilds. Instead, Gitpod will check if creating a new prebuild is necessary whenever you create a new workspace on the repository. If you want to trigger a prebuild manually, you can do so from the prebuilds page. Or use our API to do so.

​
Can I use project environment variables in prebuilds?

Yes, environment variables that are defined in project settings will be visible in prebuilds.

​
Can I see JetBrains IDE prebuild logs?

Yes, if you have set up prebuilds for JetBrains IDEs in your .gitpod.yml, you can view their logs alongside other tasks on the prebuilds detail page.

​
Can I see logs of image builds?

When Gitpod doesn’t have the necessary image for a prebuild cached, it will build the image before running any of the prebuild tasks. You can inspect the logs of the image build as it’s happening on the prebuild detail page, but these will not be persisted into the later phases of the prebuild.

​
Where has the Create Workspace button gone?

The Create Workspace from prebuild button has been removed from prebuild detail pages. We recommend opening your repositories (and even specific branches/commits) using the Create Workspace page or our browser extension, which will automatically pick up the latest prebuild without the need to manually select it and potentially ending up on an old commit.

​
What are webhook-based prebuild activity triggers?

Prebuilds can be triggered by two basic strategies:
  • Webhook-based triggers work by installing a webhook on your SCM (e.g. GitHub) repository that let Gitpod know when to trigger a prebuild. Default for repositories created before June 2024.
  • Activity-based triggers work by checking if a prebuild is necessary whenever you create a new workspace on the repository. This is the default for repositories created after June 2024 and is more reliable, intuitive and cost-effective in most scenarios. If a repository has webhook-based triggers enabled, activity-based ones are complimentary to webhook-based triggers.
You can check which strategy is in use for your repository by looking at the prebuild settings under the imported repository. If you want to switch to activity-based triggers, you can do so by removing the webhook from your SCM repository settings. Please note that for the change to be reflected in the repository settings, you may need to create a new commit and start a workspace on the repository (although activity-based triggers will start working immediately).