Prebuilds

Prebuilds reduce wait time, by installing dependencies or running builds before you start a new workspace.

.gitpod.yml

Prebuilds are typically configured using an init task in your gitpod.yml.

In the example below, the init task installs npm packages into the node_modules directory of the workspace. The command task runs ‘npm start’ on every workspace startup.

Enable prebuilds on your repository project

Use the following steps to enable prebuilds on your repository:

• Create a project for the repository.
• Define the prebuild steps in an init task in your gitpod.yml.

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.

Projects and prebuilds

For prebuilds to run automatically, you also need a project for your repository.

To create a new project:

• Click on New Project in the Projects page of one your organizations.

• If necessary, you will be prompted for additional authorization to install and configure the Gitpod GitHub app, so that Gitpod can watch your repositories and trigger prebuilds.

• Select the repository for your project.

View prebuilds

You can find a list of recent prebuilds under the Prebuilds tab for your project.

From here, you may also trigger a new prebuild based on the last commit in the project. Selecting a prebuild will open the details page showing the current status as well as additional logs. From the prebuild details page, you may rerun the selected prebuild or start a new workspace based on it.

Rerun a prebuild

Prebuilds can be triggered again which can be particularly useful when debugging an unexpected failure.

To rerun a prebuild:

1. Navigate to your project and select the Prebuilds tab.
2. Select the prebuild you wish to rerun.
3. Select Rerun Prebuild.

Start workspace based on existing prebuild

To start a workspace using an existing prebuild:

1. Navigate to your project and select the Prebuilds tab.
2. Select the prebuild you wish to start a workspace on top of.
3. Select New Workspace (with this prebuild).

Prebuilds are shared

Gitpod can trigger a prebuild whenever there is a commit to a repository. That prebuild will then be used for all new workspaces opened on that branch. This is ideal for working together on branches for testing or code reviews.

Prebuild users will see a message in their workspace terminal like this:

Workspace directory only

Prebuilds save only the workspace directory. Other directories like the home directory are not saved by prebuilds.

To use global installs like ‘npm install -g’, we suggest using a custom Dockerfile or a before task, which runs before the init task, and runs again before the command task.

Project environment variables

Environment variables which are defined in project settings will be visible in prebuilds. This is useful for prebuilds to access restricted services.

WARNING Care should be taken with secrets in prebuilds. Do not save secrets in a way which could leak into workspaces. This especially true for public repositories.

Configuring prebuilds manually

All prebuilds require a Gitpod project for the repository.

For a GitLab or Bitbucket repository, allow Gitpod to install repository webhooks, by granting api permissions in your git provider integrations

For GitLab, if you want to trigger new Gitpod prebuilds for specific branches only, you can configure this in your GitLab project settings.

By default, Gitpod prepares prebuilt workspaces for all changes on the default branch and for pull/merge requests coming from the same repository.

Note: Prebuilds are executed as the user who enabled them. This means that if you want to use prebuilds on a private repository, you must give Gitpod access to private repositories.

Prebuilds are configured in your repository’s .gitpod.yml file with the following start tasks:

• before
• init

Note the absence of the command task. Since this task may potentially run indefinitely, e.g. if you start a dev server, Gitpod does not execute the command task during prebuilds.

Prebuilds have a timeout of 1 hour. If your before and init tasks combined exceed 1 hour, your prebuild will fail. Subscribe to this issue for updates when this limit will be lifted.

Each prebuild starts with a clean environment. In other words, Gitpod does not cache artifacts between prebuilds.

Incremental Prebuilds use an earlier, successful Prebuild as the base. This can reduce the duration of your Prebuilds significantly, especially if they normally take more than ten minutes to complete. Incremental Prebuilds can be found under the project settings in your Gitpod dashboard.

GitHub-specific configuration

The github prebuilds section in the .gitpod.yml file configures when prebuilds are run. By default, prebuilds are run on push to the default branch and for each pull request coming from the same repository. Additionally, you can enable prebuilds for all branches (branches) and for pull requests from forks (pullRequestsFromForks).

Note: The Gitpod GitHub app has no equivalent for GitLab or Bitbucket yet, so this entire section is GitHub-specific for now.

Additional GitHub integration

Once the GitHub app is installed, Gitpod can add helpful annotations to your pull requests.

Checks

By default, Gitpod registers itself as a check to pull requests - much like a continuous integration system would do.

The default behavior, however, would not make the checks fail when the prebuild failed. This can be enabled with the following snippet:

You can disable this behaviour in the .gitpod.yml file in your default branch:

Comment

Gitpod can add a comment with an “Open in Gitpod” button to your pull requests.

You can enable this behaviour in the .gitpod.yml file in your default branch:

Badge

Instead of adding a comment, Gitpod can also modify the description of a pull request to add the “Open in Gitpod” button. This approach produces fewer GitHub notifications, but can also create a concurrent editing conflict when the bot and a user try to edit the description of a pull request at the same time.

You can enable this behaviour in the .gitpod.yml file in your default branch:

The addComment and addBadge behaviours are not mutually exclusive (i.e. enabling one does not disable the other). If you don’t want the comments to be added, disable them using addComment: false.

User specific environment variables in prebuilds

It is not necessarily best practice to have user specific environment variables in a prebuild init block, but sometimes there are build time requirements that mean certain tokens need setting or files need creating. Environment variables defined within your Gitpod Variables preferences are not imported by default, but they can be accessed with the following command within a before or init block:

After that, the available environment variables will be installed into the rest of you shell script and can be accessed normally.