Heads up! On October 1, we introduced Gitpod Flex. You can swap between documentation by using the switcher in the left navigation bar.

User level Environment Variables

You can utilize environment variables with Gitpod in the same way as you do locally. You can set environment variables at the user level, which will make them available in all your workspaces (or a specified subset of them).

Additionally, you can also set environment variables at the repository level, which will make them available in all workspaces for that repository in your organization.

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.

User-Specific Environment Variables

Gitpod supports encrypted, user-specific environment variables. They are stored as part of your user settings and can be used to set access tokens, or pass any other kind of user-specific information to your workspaces.

Ways of setting user-specific environment variables

Using the command line: gp env

The Workspace CLI prints and modifies the persistent environment variables associated with your user for the current repository.

To set the persistent environment variable foo to the value bar use:

language icon bash
gp env foo=bar

Beware that this does not modify your current terminal session, but rather persists this variable for the next workspace on this repository. gp can only interact with the persistent environment variables for this repository, not the environment variables of your terminal. If you want to set that environment variable in your terminal, you can do so using -e:

language icon bash
eval $(gp env -e foo=bar)

If you’re using the fish shell:

language icon bash
eval (gp env -e foo=bar)

To update the current terminal session with the latest set of persistent environment variables, use:

language icon bash
eval $(gp env -e)

If you’re using the fish shell:

language icon bash
eval (gp env -e)

To delete a persistent environment variable use:

language icon bash
gp env -u foo

# And if you want to remove it from your shell session too:
unset foo

Note that you can only delete/unset variables if their repository pattern matches the repository of the workspace exactly. This means that you cannot delete environment variables with a repository pattern such as */foo, foo/* or */*. To remove them, you can use the account settings.

language icon bash
Usage:
  gp env [flags]

Flags:
  -e, --export   produce a script that can be eval'ed in Bash
  -h, --help     help for env
  -u, --unset    deletes/unsets persisted environment variables

Using the account settings

You can also configure and view the persistent environment variables in your account settings, where you can add as many environment variables as you wish.

Environment Variables in Account Settings

The repository pattern of each variable determines the workspaces they will be available in. Repository patterns follow the owner/repository pattern. You can use a wildcard on either of the parts, e.g. gitpod-io/* would make that variable available in all repositories owned by gitpod-io. Conversely, */vscode would make that variable available on all repositories called vscode, which is especially useful for forks. Subsequently, */* makes that variable available in all of your workspaces.

Note: For GitLab, which allows to have nested group/repository structures like owner/some-group/sub-group/repo, the number of segments in the pattern has to match the number of segments in the repository name. This constraint exists to avoid surprises and leaking of content into unexpected repositories. For matching arbitrary segments to the right, there is a dedicated pattern of **.

Some example patterns (for GitLab) and results for the mentioned owner/some-group/sub-group/repo repository:

  • */**: ✅
  • */*: ❌ (for GitLab)
  • owner/some-group/*/*: ✅
  • owner/some-group/*: ❌
  • owner/some-group/**: ✅
  • owner/**: ✅
  • owner/some-group/sub-group/repo: ✅
  • */some-group/sub-group/repo: ✅

Beware: While the variable values are stored encrypted, they are available as plain text inside a workspace. Be careful when sharing your live workspace or when using */* or */** as repository pattern.

Using the DOCKERD_ARGS environment variable

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 that have been created within the container. The content of the environment variable should look like this:

language icon json
{ "remap-user": "1000" }

Using secrets with 3rd-party services

If you use tools like aws, gcloud or vault with Gitpod, you might want to consider using OpenID Connect (OIDC) over environment variables for authentication. OIDC makes the whole process of sharing secrets between a workspace and a 3rd-party more secure and scalable.

Was this helpful?

← Previous: Browser bookmarklet Next: Dotfiles →