Prebuilds help optimize the time to start a workspace by executing any defined installation tasks from the
.gitpod.yml in an associated repository asynchronously ahead of time. Gitpod will search the last 100 ancestor commits for a successful prebuild to use as a base for a workspace. Prebuilds work similarly to Continuous Integration (CI) systems by responding to an SCM trigger (e.g. a webhook). For Prebuilds, it helps to be familiar with the following Gitpod features:
To balance frequency of prebuilds with repository activity (e.g. number of commits) you can adjust the number of commits that are skipped between prebuilds. The default is
A Prebuild filter allows you to configure when a Prebuild should execute. Prebuild filters help to save costs by not running Prebuilds unnecessarily. You can filter prebuilds in your project settings by:
- Enable (or disable) Prebuilds
- On every push event for:
- all branches (the default setting)
- default branch only (e.g. main)
- only branches specified (via glob pattern)
To configure a Prebuild for a repository you must:
- Add a
beforetask in the repository gitpod.yml.
- Create a corresponding Project for the repository.
- Enable Prebuilds in the project settings.
Tip: You can test changes to your tasks and
.gitpod.ymldirectly in your workspace by running the
gp validate --prebuildcommand.
A prebuild cannot be executed unless you tell Gitpod explicitly which steps in your
.gitpod.yml should be ran in the prebuild. You can do this by ensuring you have either an
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. running a web server.
tasks: - init: | npm install - command: | npm start
When a Prebuild ran successfully, you will see 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.
You can find a log of past Prebuilds in your Project settings.
- Go to the /projects page.
- Select the Project.
- Navigate to the “Prebuilds” tab to see Prebuild history.
Prebuilds can be triggered manually for debugging purposes. To rerun a prebuild:
- Navigate to your project and select the Prebuilds tab.
- Select the Prebuild.
- Select “Rerun Prebuild”.
Enabling Prebuilds requires the user to have SCM permissions to create a webhook.
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
Prebuilds have a timeout of 1 hour. If your
init tasks combined exceed 1 hour, your Prebuild will be terminated.
To pull git information into a workspace, Prebuilds are executed on behalf of the user who created the Prebuild.
Even if your repository is public, only members of your Gitpod organization will have access to prebuilds. Public contributors to your repository will not be able to use prebuilds at this time.
Environment variables that are defined in project settings will be visible in Prebuilds.