- Introduction
- Getting Started
- Gitpod Tutorial
- Use Cases
- Languages
- Configure
- Workspaces
- User settings
- Repositories
- Organizations
- Authentication
- Billing
- References
- .gitpod.yml
- IDEs & editors
- Integrations
- Gitpod CLI
- Gitpod API
- Gitpod URL
- Compatibility
- Enterprise
- Overview
- Setup and Preparation
- Deploying
- Configure your Gitpod Instance
- Administration
- Upgrading
- Background
- Reference
- Archive
- Help
- Contribute
- Troubleshooting
Prebuilds
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 and triggers a check for a potential new one every time a workspace gets created under the respective repository. For Prebuilds, it helps to be familiar with the following Gitpod features:
Prebuild settings
Commit Interval
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 20
.
Filtering Prebuilds
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:
- Enabling (or disabling) Prebuilds entirely
- Constraining triggering to push events targeting:
- all branches (the default setting)
- the default branch only (e.g.
main
) - any branches specified via glob pattern
Managing Prebuilds
To configure a Prebuild for a repository, you must:
- Add an
init
orbefore
task in the repository’s gitpod.yml. - Import the repository (see Imported Repositories).
- Enable Prebuilds in the repository’s settings.
Tip: You can test changes to your tasks and
.gitpod.yml
directly in your workspace by running thegp validate --prebuild
command.
Configuring Prebuilds
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
Enabling prebuilds
To enable prebuilds for a repository:
- Select it under
/repositories
- 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.
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:
- Select the desired prebuild from the prebuilds list.
- Click “Rerun Prebuild”.
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.
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 executed as the user who enables them
To pull git information into a workspace, Prebuilds are executed on behalf of the user who created the Prebuild.
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.
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.