Repository level Environment Variables

You can utilize environment variables with Gitpod in the same way as you do locally. You can set environment varibales at repository level, which will make them available in all workspaces for that repository in your organization.

Additionally, You can set environment variables at the user level, which will make them available in all your workspaces (or a specified subset of them).

Default Environment Variables

Below are some environment variables which are set automatically by Gitpod and are guaranteed to exist:

• GITPOD_WORKSPACE_ID: The Universally Unique Identifier (UUID) associated with the workspace.
• GITPOD_WORKSPACE_URL: The unique URL of the workspace.
• GITPOD_REPO_ROOT: Path to the directory where your git repository was cloned inside the workspace.

Tip: Try running env | grep GITPOD_ on a workspace terminal to see all the Gitpod specific environment variables. These can be useful for scripting dynamic workspace behavior.

Reserved Prefix

Environment variables with the prefix GITPOD_ are reserved for internal use by Gitpod and are overridden on every workspace startup. This means that a user-defined variable set with the name GITPOD_FOOBAR will be ignored and will not be accessible in the workspace.

Repository-Specific Environment Variables

Environment variables defined in a repository’s settings will be visible in prebuilds, and optionally also in workspaces. This is useful for prebuilds to access restricted services. Repository-Specific Environment Variables will take precedence over User-Specific Environment Variables. Only members of the Gitpod organization where the repository resides will be able to access the environment variables inside a running workspace. Even if the imported repository is public, people outside of your Gitpod organization will not have access to these environment variables.

Warning: Care should be taken with secrets. If your repository is public and prebuilds are enabled, ensure that neither of your init or before task commands in .gitpod.yml are exposing the sensitive environment variable values to the filesystem (i.e. persistent /workspace dir) and that pullRequestsFromForks (for GitHub) is set to false.

Task terminal-specific Environment Variables

You can set environment variables for a Gitpod task terminal by setting the env property within the task definition in your .gitpod.yml. Please note that such environment variables will be limited to the task terminal and are not globally set across the workspace.

Using the env keyword

yml

tasks:
    - name: Example of setting an environment variable for a task terminal
      env:
          PRINT_ME: 'Hello World!'
      command: echo "$PRINT_ME"

Note: The values should be a static string or integer, you can’t refer to an existing variable via env keyword.

Using the task SHELL

yml

tasks:
    - name: Example of starting yarn with a custom environment variable set
      command: |
          # Example for referring to the existing system variables
          export API_URL="$HOSTNAME"

          # Print out the environment variable
          echo "$API_URL"

          yarn start

    - name: Example of updating PATH environment variable inside a task shell
      command: |
          # Download and install `fzf` binary to ~/.local/bin/
          mkdir -p ~/.local/bin
          curl -sL "https://github.com/junegunn/fzf/releases/download/0.35.1/fzf-0.35.1-linux_amd64.tar.gz" | tar -C ~/.local/bin -xpz

          # Update PATH variable
          export PATH="$HOME/.local/bin:$PATH"

          # Now `fzf` can be called without full path from the task shell
          ls / | fzf

Note: You can use this method when you need to refer to other variables or want to use scripting to set them conditionally.

See .gitpod.yml for more details.

Providing one-time environment variables via the context URL

This feature is great for setting one-time environment variables for dynamic workspace configurations or setups but is not appropriate for configuring sensitive information, such as passwords or long-lived API tokens. Gitpod and the Open Web Application Security Project recommends that you do not pass sensitive information through query strings. Refer to CWE-598 to learn more about this recommendation.

In addition to user-specific environment variables, Gitpod also allows passing in variables through the gitpod.io/# URL. The syntax for that is:

https://gitpod.io/#var=value,var2=value2/https://github.com/my-org/repo-to-work-on

The values are URL encoded to allow any non-ascii characters in values. In case of a conflict, e.g. in the example above if the user already had a variable var2 set, the user’s value would be used.

Exporting all the Gitpod environment variables that you created

You can run the following command in your Gitpod Workspace terminal to save your environment variables (which you have configured in Gitpod Environment Variables) in a different file (e.g.: gitpod.env):

bash

gp env > gitpod.env