> ## Documentation Index
> Fetch the complete documentation index at: https://ona.com/docs/llms.txt
> Use this file to discover all available pages before exploring further.

# Prebuilds

Prebuilds save time by executing `init` [tasks](/classic/user/configure/workspaces/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*.

<Tip>
  For understanding prebuilds, it helps to be familiar with the following Gitpod features:

  1. [Imported repositories](/classic/user/configure/repositories)
  2. [Tasks](/classic/user/configure/workspaces/tasks)
  3. [.gitpod.yml](/classic/user/references/gitpod-yml)
</Tip>

## 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](/classic/user/references/gitpod-yml).
2. Import the repository (see [Imported Repositories](/classic/user/configure/repositories)).
3. [Enable prebuilds](#enabling-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.

```yml theme={null}
tasks:
    - init: |
          npm install
    - command: |
          npm start
```

<Tip>
  Immediately test your changes using [`gp validate --prebuild`](#use-gp-validate-to-test-changes-to-gitpodyml).
</Tip>

### Enabling prebuilds

To enable prebuilds for a repository:

1. Select it under [`/repositories`](https://gitpod.io/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:

```txt theme={null}
🍊 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](/classic/payg/billing/overview) plans, configuring [prebuild settings](#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](#prebuild-settings).

If that is not enough, you can also use our API to trigger prebuilds like this:

```bash theme={null}
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?](#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](/classic/user/configure/orgs) 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](https://gitpod.io/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](https://gitpod.io/usage/).

### 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](/classic/user/configure/orgs) 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](#triggers).

### 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](/classic/user/references/gitpod-yml#jetbrainsproductprebuilds) 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](https://gitpod.io/new) page or our [browser extension](/classic/user/configure/user-settings/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).