.gitpod.yml TZ variable persistence across workspace resets requires diagnosis

Direct answer

Put a container-wide TZ in devcontainer.json using containerEnv, not in a top-level .gitpod.yml key unless your Gitpod version’s schema explicitly supports it. A workspace reset normally re-reads repository config and recreates the workspace container from the existing image, so an image rebuild is not required for environment settings to be reapplied. An explicit TZ normally overrides the base image default for glibc-aware tools.

What is well-established

• TZ is a standard environment variable. For timezone-aware programs, it normally takes precedence over the image’s /etc/localtime.
• In devcontainer.json, containerEnv applies environment variables at container start. remoteEnv can affect the VS Code server and terminal environment, depending on the dev container implementation.
• A Gitpod workspace reset restores the repository from git and recreates the workspace container from the existing image. Because .gitpod.yml and devcontainer.json live in the repo, their declared settings are re-read on the next start.
• A reset is not the same as a dev-container rebuild. Changes to Dockerfiles or dev-container features need an explicit rebuild; environment-variable settings generally do not.
• Imperative changes such as export TZ=... in one shell, editing /etc/localtime, or installing timezone data are not retained across a reset unless committed into the repo or image build.

Precedence when both files set TZ

The exact merge order is version-dependent, so treat this as the likely explanation rather than a guaranteed rule:

1. devcontainer.json containerEnv.TZ is container-wide and is applied when the container starts.
2. A TZ value inside a .gitpod.yml task env block is scoped to that task process.
3. Therefore, containerEnv usually dominates a later interactive terminal, while a task-scoped value may override commands launched by that specific task.
4. A top-level .gitpod.yml TZ entry is the uncertain case: it may be ignored if the key is not part of the supported schema for your Gitpod version.

Base-image timezone interaction

The base image default does not normally override an explicitly set TZ for standard glibc-based tools. However, some tools read /etc/localtime directly or use their own timezone database, so TZ may not affect every timestamp source. This is especially worth checking for musl/Alpine-based images, Java runtimes, databases, and language-specific timezone libraries.

Minimal verification after a reset

Commit the devcontainer.json change, reset the workspace, then open a new terminal and run:

printenv TZ
tr '\0' '\n' < /proc/1/environ | grep '^TZ='
readlink -f /etc/localtime
date
ls -l --time-style=full-iso

If the shell value differs from PID 1, a task or shell profile is overriding the container-wide value. If /etc/localtime still points to the image default but date shows the expected zone, that is normal for glibc-aware tools using TZ.

One diagnostic detail that changes the fix

If the behavior still differs, the key detail is whether your .gitpod.yml TZ entry is top-level or inside a task env block. That determines whether the value is being silently dropped as unsupported or scoped only to a task process.