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 (ordered from lowest to highest priority) for environment variables in a Gitpod workspace:

Image environment variables

• Set in the Dockerfile using ENV instructions or provided by the underlying image
• Provides base environment configuration
• Documentation →

Global environment variables (.gitpod.yml[env])

• Set workspace-wide variables in your .gitpod.yml
• Apply to all tasks in the workspace
• Documentation →

User-specific environment variables

• Set in user settings
• Apply across all workspaces
• Documentation →

Repository-specific environment variables

• Set in the repository settings in the Dashboard
• Documentation →

One-time environment variables (via context URL)

• Pass temporary variables through the Gitpod URL
• Format: https://gitpod.io/#var=value,var2=value2/[repository-url]
• Values are URL encoded
• Not suitable for sensitive information
• Example: template-selective-services

When using context URL environment variables, avoid passing sensitive information like passwords or API tokens. Both Gitpod and the Open Web Application Security Project recommend against passing sensitive information through query strings. See CWE-598 for more information.

Task-specific environment variables (.gitpod.yml[tasks][n][env])

• Set per-task environment variables in your .gitpod.yml
• Useful for task-specific configurations
• Documentation →

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.

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:

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.