Environment Variables on Gitpod

Environment variables in Gitpod help you store sensitive information and configure your workspaces. They can be set at different levels, including user-specific and repository-specific settings. See the Prioritization Stack chart below for all the different sources of environmental variables in a workspace.

Environment Variable Priority

Environment variables can come from multiple sources. Below is the order of precedence (from highest to lowest priority):

Tip: the below diagram is interactive, you can click on the different sources to learn more about them.

Providing one-time environment variables via the context URL

This feature is excellent 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 recommend not passing 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 URL when starting a workspace. You can pass temporary environment variables through the Gitpod URL using this syntax:

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.

You can see an example of this feature being used here: https://github.com/gitpod-io/template-selective-services.

Exporting your Gitpod environment variables

You can export all your configured environment variables from your Gitpod workspace to a file. This includes both user-specific and repository-specific environment variables.

bash

gp env > gitpod.env

This will save all your environment variables to a file named gitpod.env.

Special Environment Variables

Default Environment Variables

Gitpod automatically sets these core environment variables in every workspace:

GITPOD_WORKSPACE_ID: A Universally Unique Identifier (UUID) for your workspace
GITPOD_WORKSPACE_URL: The unique URL of your workspace
GITPOD_REPO_ROOT: The path to your cloned git repository in the workspace

Tip: Run env | grep GITPOD_ in your workspace terminal to see all Gitpod-specific environment variables. These are helpful for creating dynamic workspace behaviors.

Reserved Prefix

Gitpod reserves the GITPOD_ prefix for internal use. Any user-defined variables with this prefix (like GITPOD_FOOBAR) will be ignored and overwritten during workspace startup.

Git Configuration

By default, your name and email address for git commits are set using your connected SCM integration. If you want to override these settings, you can use the following environment variables:

GIT_AUTHOR_NAME
GIT_AUTHOR_EMAIL
GIT_COMMITTER_NAME
GIT_COMMITTER_EMAIL

`DOCKERD_ARGS`

The DOCKERD_ARGS environment variable can be used to specify additional arguments to the docker installation running in your workspace. Currently, mapping a user in your container to the gitpod user in your workspace is supported. This helps if you are using an unprivileged user with your containers (e.g., user 1000 in a node image) but need to edit files with VS Code created within the container. The content of the environment variable should look like this:

json

{ "remap-user": "1000" }

`GITPOD_IMAGE_AUTH`

You can use the GITPOD_IMAGE_AUTH environment variable to authenticate against private container registries. See the Workspace Image docs for more information.