> ## 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.

# .gitpod.yml

The `.gitpod.yml` file instructs Gitpod on how to prepare and build a project, such as starting development servers and configuring [Prebuilds](/classic/user/configure/repositories/prebuilds). Below is a full reference of all available properties. To see the underlying schema, please refer to [`gitpod-io/gitpod`](https://github.com/gitpod-io/gitpod/blob/main/components/gitpod-protocol/data/gitpod-schema.json) in the [gitpod-io/gitpod](https://github.com/gitpod-io/gitpod) repository.

<Note>
  For a more comprehensive configuration guide, see [configuring a project](/classic/user/configure/workspaces).
</Note>

* [.gitpod.yml](#.gitpod.yml)
  * [`additionalRepositories`](#additionalrepositories)
  * [`checkoutLocation`](#checkoutlocation)
  * [`coreDump`](#coreDump)
  * [`env`](#env)
  * [`gitConfig`](#gitconfig)
  * [`github`](#github)
  * [`image`](#image)
    * [`image.file`](#imagefile)
    * [`image.context`](#imagecontext)
  * [`jetbrains`](#jetbrains)
    * [`jetbrains.plugins`](#jetbrainsplugins)
    * [`jetbrains.[product]`](#jetbrainsproduct)
    * [`jetbrains.[product].plugins`](#jetbrainsproductplugins)
    * [`jetbrains.[product].prebuilds`](#jetbrainsproductprebuilds)
    * [`jetbrains.[product].vmoptions`](#jetbrainsproductvmoptions)
  * [`ports`](#ports)
    * [`ports[n].name`](#portsnname)
    * [`ports[n].description`](#portsndescription)
    * [`ports[n].onOpen`](#portsnonopen)
    * [`ports[n].port`](#portsnport)
    * [`ports[n].visibility`](#portsnvisibility)
    * [`ports[n].protocol`](#portsprotocol)
  * [`tasks`](#tasks)
    * [`tasks[n].before`](#tasksnbefore)
    * [`tasks[n].command`](#tasksncommand)
    * [`tasks[n].env`](#tasksnenv)
    * [`tasks[n].init`](#tasksninit)
    * [`tasks[n].name`](#tasksnname)
    * [`tasks[n].openIn`](#tasksnopenin)
    * [`tasks[n].openMode`](#tasksnopenmode)
    * [`tasks[n].prebuild`](#tasksnprebuild)
  * [`mainConfiguration`](#mainconfiguration)
  * [`vscode`](#vscode)
    * [`vscode.extensions`](#vscodeextensions)
  * [`workspaceLocation`](#workspacelocation)

## `additionalRepositories`

> additionalRepositories is currently in Beta. [Send feedback](https://github.com/gitpod-io/gitpod/issues/8623).

Defines additional source control repositories to clone and where the repository is cloned under `/workspaces`

| Type     | Default   |
| -------- | --------- |
| `object` | `<empty>` |

**Demo**

[![Open in Gitpod](https://gitpod.io/button/open-in-gitpod.svg)](https://gitpod.io/#https://github.com/gitpod-io/demo-multi-repo-backend)

**Example**

```yml theme={null}
additionalRepositories:
    - url: https://github.com/gitpod-io/demo-multi-repo-backend
      # checkoutLocation is optional and relative to /workspaces.
      # by default the location defaults to the repository name.
      checkoutLocation: backend
```

When the above configuration is defined then the following additional steps happen when Gitpod workspace is started:

1. If you open a workspace on a branch, Gitpod will clone the same-named branch in all repositories. If such a branch doesn't exist Gitpod checks out the default branch.
2. The contents of the branch is cloned under `/workspaces/`
3. The contents of `https://github.com/gitpod-io/demo-multi-repo-backend` is cloned to `/workspaces/backend`

After all of the source control repositories have been cloned then the `before`, `init` and `command` [tasks](/classic/user/configure/workspaces/tasks) are executed as per normal.

If you need to run commands (such as package installation or compilation) on the source control repositories which have been cloned then change your working directory to the use configured or default `checkoutLocation` location using the `before` task.

**Example**

```yml theme={null}
# example .gitpod.yml from https://github.com/gitpod-io/demo-multi-repo-frontend
additionalRepositories:
    - url: https://github.com/gitpod-io/demo-multi-repo-backend
      # checkoutLocation is optional and relative to /workspaces.
      # by default the location defaults to the repository name.
      checkoutLocation: backend

tasks:
    - name: backend
      # change working directory as per configured in `checkoutLocation`
      # which is configured above as `/workspaces/backend`
      before: |
          cd ../backend
      init: |
          echo npm install
      command: |
          echo npm run dev

      # changing of working directory is not required as these tasks will
      # by default by executed in `/workspaces/demo-multi-repo-frontend`
    - name: frontend
      init: |
          echo npm install
          echo npm run build
      command: |
          echo npm run dev
```

## `checkoutLocation`

Define where Gitpod checks out the project's code, relative to `/workspace`.

In most cases, this is not needed. If you work on an older Go project, please see the [Go Language Page](/classic/user/introduction/languages/go) for more details.

| Type     | Default      |
| -------- | ------------ |
| `string` | `/workspace` |

**Example**

```yml theme={null}
checkoutLocation: 'go/src/github.com/demo-apps/go-gin-app'
```

## `coreDump`

Define workspace core dump behavior.

For most cases, setting the `coreDump` property is not required. However, it can be a valuable feature to debug C++, or when debugging add-ons in Rust, Python, or node.js.

| Type     | Default   |
| -------- | --------- |
| `object` | `<empty>` |

**Example**

```yml theme={null}
coreDump:
    enabled: true
```

You can also set custom size values for the generated core files using the `softLimit` and `hardLimit` values (see example below). The setting `softLimit` configures the upper limit on the size of the core dump file that will be produced if a process receives a core dump signal, while `hardLimit` allows setting a hard limit to act as a ceiling for the soft limit.

```yml theme={null}
coreDump:
    enabled: true
    softLimit: <bytes>
    hardLimit: <bytes>
```

For more details, please see the [Linux man page for `getrlimit`](https://man7.org/linux/man-pages/man2/getrlimit.2.html)

## `env`

Define environment variables that will be available in the workspace. This is an alternative to setting environment variables in the Repository settings. See the [Workspace Environment Variable Prioritization Stack](/classic/user/configure/workspaces/environment-variables#workspace-environment-variable-prioritization-stack) for information on how Gitpod prioritizes environment variables from different sources.

| Type     | Default   |
| -------- | --------- |
| `object` | `<empty>` |

**Example**

```yml theme={null}
env:
    DB_HOST: localhost:3306
    DB_USER: readOnlyUser
```

## `gitConfig`

Define a workspace's git configuration as key-value pairs.

Please refer to [https://git-scm.com/git-config#\_values](https://git-scm.com/git-config#_values) for a list of accepted values.

| Type     | Default   |
| -------- | --------- |
| `object` | `<empty>` |

**Example**

```yml theme={null}
gitConfig:
    alias.st: status
    core.autocrlf: input
```

## `github`

Configure the [GitHub Gitpod](https://github.com/apps/gitpod-io) app.

> **Heads up!** Gitpod no longer uses the GitHub App on GitHub repositories and hence the `github` configuration in your `.gitpod.yml` file will have no effect. To enable prebuilds on a repository, see [Configuring prebuilds](/classic/user/configure/repositories/prebuilds#configuring-prebuilds) instead. To continue having easy access to creating workspaces without `github.prebuilds.addBadge` or `github.prebuilds.addComment`, you can use the [Gitpod browser extension](/classic/user/configure/user-settings/browser-extension).

| Type     | Default   |
| -------- | --------- |
| `object` | `<empty>` |

## `image`

Define a custom Docker image to be used for workspaces. To learn more, please review [Custom Docker Image](/classic/user/configure/workspaces/workspace-image#configure-a-custom-dockerfile).

Public images are hosted on [Docker Hub](https://hub.docker.com/u/gitpod/) and can be referenced by their name, e.g. `ubuntu:latest`.

To see a list of Gitpod-provided images, please see [gitpod-io/workspace-images](https://github.com/gitpod-io/workspace-images).

| Type                 | Default                 |
| -------------------- | ----------------------- |
| `object` or `string` | `gitpod/workspace-full` |

**Examples**

*With a public image*

```yml theme={null}
image: ubuntu:latest
```

*With a custom image*

```yml theme={null}
image:
    file: .gitpod.Dockerfile
```

*With an optional context*

```yml theme={null}
image:
    file: .gitpod.Dockerfile
    context: ./docker-content
```

### `image.file`

To define a custom Docker image, you can use the following configuration:

For a list of examples, please see [https://github.com/gitpod-io/workspace-images](https://github.com/gitpod-io/workspace-images).

| Type     | Default   |
| -------- | --------- |
| `string` | `<empty>` |

### `image.context`

Optionally, you can set the `image.context`. This is useful when you want to copy files into the Docker image. The [Docker docs](https://docs.docker.com/engine/reference/builder/#usage) describe this in more detail.

| Type     | Default   |
| -------- | --------- |
| `string` | `<empty>` |

## `jetbrains`

> JetBrains is currently in Beta · [Send feedback](https://github.com/gitpod-io/gitpod/issues/6576).

Define the integration between Gitpod and JetBrains IDEs.

| Type     | Default   |
| -------- | --------- |
| `object` | `<empty>` |

### `jetbrains.plugins`

> JetBrains plugin support (via gitpod.yml) is currently in Beta · [Send feedback](https://github.com/gitpod-io/gitpod/issues/6576).

Define a list of plugins which should be installed for all compatible JetBrains IDEs when starting a workspace. To find the plugin identifier, from the [JetBrains Marketplace](https://plugins.jetbrains.com), find the desired plugin, open the 'Versions' tab, select any version and copy the 'Plugin ID' (like `${publisher}.${name}`).

| Type    | Default   |
| ------- | --------- |
| `array` | `<empty>` |

### `jetbrains.[product]`

> JetBrains is currently in Beta · [Send feedback](https://github.com/gitpod-io/gitpod/issues/6576).

Define the integration between Gitpod and a specific JetBrains IDE. Install plugins and configure prebuilds to speed up the IDE indexing.

Specify the 'product' with one of the following values:

* `intellij`
* `goland`
* `pycharm`
* `phpstorm`

| Type     | Default   |
| -------- | --------- |
| `object` | `<empty>` |

### `jetbrains.[product].plugins`

> JetBrains plugin support (via gitpod.yml) is currently in Beta · [Send feedback](https://github.com/gitpod-io/gitpod/issues/6576).

Define a list of plugins which should be installed for the given JetBrains IDE when starting a workspace. To find the plugin identifier, from the [JetBrains Marketplace](https://plugins.jetbrains.com), find the desired plugin, open the 'Versions' tab, select any version and copy the 'Plugin ID' (like `${publisher}.${name}`).

| Type    | Default   |
| ------- | --------- |
| `array` | `<empty>` |

**Example**

```yml theme={null}
jetbrains:
    intellij:
        plugins:
            - zielu.gittoolbox
            - izhangzhihao.rainbow.brackets
```

### `jetbrains.[product].prebuilds`

> JetBrains prebuilds support (via gitpod.yml) is currently in Alpha · [Send feedback](https://github.com/gitpod-io/gitpod/issues/6576).

Define whether Gitpod enables prebuilds for a specific JetBrains IDE.

| Type     | Default   |
| -------- | --------- |
| `object` | `<empty>` |

**Example**

```yml theme={null}
jetbrains:
    intellij:
        prebuilds:
            version: stable
```

The `version` is defined as follows:

| Type     | Default  | Values                     |
| -------- | -------- | -------------------------- |
| `string` | `stable` | `stable`, `latest`, `both` |

### `jetbrains.[product].vmoptions`

> Configuration of JVM options (via gitpod.yml) is currently in Alpha · [Send feedback](https://github.com/gitpod-io/gitpod/issues/8704).

Configure JVM options for a specific JetBrains IDE.

| Type     | Default   |
| -------- | --------- |
| `string` | `<empty>` |

**Example**

```yml theme={null}
jetbrains:
    intellij:
        vmoptions: '-Xmx4g'
```

## `ports`

Configure how Gitpod treats various ports your application may listen on. You can learn more about this in the [Exposing Ports](/classic/user/configure/workspaces/ports) documentation.

| Type    | Default   |
| ------- | --------- |
| `array` | `<empty>` |

**Example**

```yml theme={null}
ports:
    - name: Website
      port: 3000
      onOpen: open-preview
    - name: VNC
      description: full GUI Virtual Desktop
      port: 6080
      onOpen: open-browser
    - name: Server
      port: 10000
      onOpen: ignore
```

### `ports[n].name`

Define a name for the port, which will be shown as a column in the output of `gp ports list` and in the `Port` column inside of the ports list in VS Code Browser and Desktop.

[More detail](/classic/user/configure/workspaces/ports#specifying-port-names--descriptions)

| Type     | Default   |
| -------- | --------- |
| `string` | `<empty>` |

### `ports[n].description`

Adds a description to the port, which will be shown as a column in the output of `gp ports list`.

You can find the port's description in the ports view table column, following the `Address` field (the same description can be found in the `Remote Explorer` as a tooltip \[on hover] of the port).

| Type     | Default   |
| -------- | --------- |
| `string` | `<empty>` |

### `ports[n].onOpen`

Define what to do when Gitpod detects a given port is being listened on.

| Type     | Default   | Values                                                                              |
| -------- | --------- | ----------------------------------------------------------------------------------- |
| `string` | `<empty>` | `open-browser`,<br /><br />`open-preview`,<br /><br />`notify`,<br /><br />`ignore` |

**Please note:** For JetBrains IDEs connected to Gitpod via [JetBrains Gateway](/classic/user/integrations/jetbrains-gateway) `open-preview` will behave exactly the same as `open-browser`, as there is no functionality for a web preview in the JetBrains IDE.

### `ports[n].port`

Define a single port or a range of ports, e.g. `3000-3100`.

| Type                 | Default   |
| -------------------- | --------- |
| `number` or `string` | `<empty>` |

### `ports[n].visibility`

Define whether to expose the port publicly or keep it private.

A public port allows you to share a URL for a given port with team members, for example if you want to get their feedback on a new feature you develop.

| Type     | Default   | Values                         |
| -------- | --------- | ------------------------------ |
| `string` | `private` | `private`,<br /><br />`public` |

### `ports[n].protocol`

Define whether a running port in the workspace is HTTP or HTTPS.

| Type     | Default | Values                       |
| -------- | ------- | ---------------------------- |
| `string` | `http`  | `http`, <br /><br /> `https` |

## `tasks`

Define how Gitpod prepares & builds your project and how it can start the project's development server(s). To learn more, please visit [Start Tasks](/classic/user/configure/workspaces/tasks). Each array element opens in its own terminal.

| Type    | Default   |
| ------- | --------- |
| `array` | `<empty>` |

**Example**

```yml theme={null}
tasks:
    - before: sh ./scripts/setup.sh
      init: npm install
      command: npm run dev
    - name: Database
      init: sh ./scripts/seed-database.sh
      command: npm start-db
      env:
          DB_HOST: localhost:3306
          DB_USER: readOnlyUser
```

### `tasks[n].before`

A shell command to run before `init` and the main `command`. This command is executed on every start and is expected to terminate. If it fails, the following commands will not be executed.

Learn more about [Start Tasks](/classic/user/configure/workspaces/tasks) in the docs.

| Type     | Default   |
| -------- | --------- |
| `string` | `<empty>` |

### `tasks[n].command`

The main shell command to run after `before` and `init`. This command is executed last on every start and doesn't have to terminate.

Learn more about [Start Tasks](/classic/user/configure/workspaces/tasks) in the docs.

| Type     | Default   |
| -------- | --------- |
| `string` | `<empty>` |

### `tasks[n].env`

Define environment variables that will be available in a given task. They have precedence over all other sources of environment variables (see the [Workspace Environment Variable Prioritization Stack](/classic/user/configure/workspaces/environment-variables#workspace-environment-variable-prioritization-stack) for more information).

Please note that the environment variables will only be available in the task's terminal and not globally across the workspace. To set environment variables globally, use the [`env`](#env) property or configure a [Repository Environment Variable](/classic/user/configure/repositories/environment-variables).

| Type     | Default   |
| -------- | --------- |
| `object` | `<empty>` |

### `tasks[n].init`

A shell command to run between `before` and the main `command`.

This task is executed only once. When you start a workspace that does not have a [prebuild](/classic/user/configure/repositories/prebuilds), `init` is executed at workspace start. When you start a workspace that has a prebuild, `init` executes as part of the prebuild, but does NOT execute again at workspace start.

This task is expected to terminate. If it fails, the `command` property will not be executed.

Learn more about [Start Tasks](/classic/user/configure/workspaces/tasks) in the docs.

| Type     | Default   |
| -------- | --------- |
| `string` | `<empty>` |

### `tasks[n].name`

A name for the task, also shown on the terminal tab.

| Type     | Default   |
| -------- | --------- |
| `string` | `<empty>` |

### `tasks[n].openIn`

Deprecated. This does not have an impact in VS Code.

### `tasks[n].openMode`

Configure how the terminal should be opened relative to the previous task.

| Type     | Default   | Values                                                                                  |
| -------- | --------- | --------------------------------------------------------------------------------------- |
| `string` | `<empty>` | `tab-after`,<br /><br />`tab-before`,<br /><br />`split-right`,<br /><br />`split-left` |

Note: `split-top` and `split-bottom` are deprecated values.

### `tasks[n].prebuild`

Deprecated. Please use the [`init`](#tasksninit) task instead.

## `mainConfiguration`

> mainConfiguration is currently in Beta. [Send feedback](https://github.com/gitpod-io/gitpod/issues/8623).

Defines the repository with the main `.gitpod.yml` file and makes it possible to open the same workspace from any issue, branch or other context URL from any repository defined in a multi repository configuration.

| Type     | Default   |
| -------- | --------- |
| `string` | `<empty>` |

**Demo**

[![Open in Gitpod](https://gitpod.io/button/open-in-gitpod.svg)](https://gitpod.io/#https://github.com/gitpod-io/demo-multi-repo-backend)

**Example**

```yml theme={null}
mainConfiguration: https://github.com/gitpod-io/demo-multi-repo-frontend
```

## `vscode`

Configure the VS Code editor.

| Type     | Default   |
| -------- | --------- |
| `object` | `<empty>` |

### `vscode.extensions`

Define a list of extensions which should be installed for users of this workspace. The identifier of an extension is always `${publisher}.${name}`. For example: 'vscodevim.vim'.

Please note, Gitpod uses the [Open VSX registry](https://open-vsx.org/) to find extensions. If you cannot find an extension you know exists in your local VS Code, please get in touch with us or open a new PR in the [open-vsx/publish-extensions](https://github.com/open-vsx/publish-extensions) repository to add the extension to Open VSX 🙏.

| Type     | Default   |
| -------- | --------- |
| `object` | `<empty>` |

By default, extensions will use the latest available version unless you use a specific version number. The version number must use semantic versioning rules. If you are interested in importing an extension that is not published on the Open VSX registry you can directly use the full URL.

**Example**

```yml theme={null}
vscode:
    extensions:
        - svelte.svelte-vscode
        - bradlc.vscode-tailwindcss@0.6.11
        - https://example.com/abc/releases/extension-0.26.0.vsix
```

## `workspaceLocation`

Define which path Gitpod considers the project's workspace directory, relative to `/workspace`.

In most cases, this is not needed. If you work on an older Go project, please see the [Go Languages](/classic/user/introduction/languages/go) page for more details.

| Type     | Default      |
| -------- | ------------ |
| `string` | `/workspace` |

**Example**

```yml theme={null}
workspaceLocation: '.'
```