[.gitpod.yml] Introduce top-level env

[filiptronicek]

Description

The .gitpod.yml spec has not changed for more than 2 years! Let's break the streak.

This PR introduces the top-level env keyword to the .gitpod.yml file, defining key-value pairs of environment variables that ought to be available on workspaces created from it.

Here is an example:

image: gitpod/workspace-full

env:
  BOND: "007"

Simple enough. The funny part comes when you try to plug this approach into our existing approaches for setting environment variables.

graph TD
    A["Environment Variable Overriding in Gitpod Workspaces"] 
    A --> |"1 (Highest Priority)"| B[".gitpod.yml[tasks][n][env]"]
    B --> |"2"| C["Environment variables passed via the context URL"]
    C --> |"3"| D["Repository-specific environment variables"]
    D --> |"4"| E["User-specific environment variables"]
    E --> |"5 (this PR's addition)"| F[".gitpod.yml[env]"]
    F --> |"6 (Lowest Priority)"| G["Image's environment variables (e.g., ENV in Dockerfile)"]
    
    style A fill:#f9f9f9,stroke:#333,stroke-width:2px;
    style B fill:#f2f2f2,stroke:#3a86ff,stroke-width:2px;
    style C fill:#f2f2f2,stroke:#8338ec,stroke-width:2px;
    style D fill:#f2f2f2,stroke:#ff006e,stroke-width:2px;
    style E fill:#f2f2f2,stroke:#fb5607,stroke-width:2px;
    style F fill:#f2f2f2,stroke:#ffbe0b,stroke-width:2px;
    style G fill:#f2f2f2,stroke:#00a676,stroke-width:2px;

Loading

Related Issue(s)

Fixes CLC-874

How to test

1. You can try starting a workspace in the preview environment based off of https://github.com/filiptronicek/test-foofies/blob/ft/envvars/.gitpod.yml.
2. You should see $VAR populated with a value in the resulting workspace

This PR also updates tests

Documentation

Yes it does. Documentation in https://github.com/gitpod-io/website/pull/4942

[geropl]

Thank you @filiptronicek for the thoughtful change, the diagram and the superb description. ✨

I got the two questions above, and would love to quickly talk through it; happy to ✔️ right after.

[geropl]

Code LGTM, tests are green and works! ✔️

[filiptronicek]

> gitpod /workspace/test-foofies (ft/envvars) $ echo $VAR
userr

It works!