Personal Environment Variables

About 887 wordsAbout 3 min

Personal Environment Variables is a user-level configuration that automatically injects the secret files you specify as environment variables when starting a Workspace (cloud-native development) environment.

When to use: when one set of personal secrets is needed in the development environments of several repositories — configuring imports per repository means repeating it for each one, while personal environment variables only need to be set once.

Unlike configuring imports per repository in .cnb.yml, personal environment variables take effect at your individual user level, and use a use_in_slugs allowlist to control which repositories they can be injected into. This makes them ideal for reusing your personal development secrets across multiple repositories.

Tips

Personal environment variables only take effect in Workspace environments and do not affect regular Builds.

Where to Configure

On the Profile > Workspaces(Open in new window) page, find Personal Environment Variables, fill it in as YAML, and save.

Format

The configuration is a YAML array. Each item contains two fields (imports uses the same syntax as pipeline imports):

Field	Type	Required	Description
`imports`	`String` \| `Array<String>`	Yes	Secret file addresses
`use_in_slugs`	`String` \| `Array<String>`	Yes	Repositories allowed to receive these secrets, supports Glob

use_in_slugs is required

If an item has no use_in_slugs, or the current workspace's repository does not match it, that item will not be injected, preventing your personal secrets from leaking into untrusted repositories.

Example:

- imports: https://cnb.cool/<your-secret-repo-slug>/-/blob/main/npm.yml
  use_in_slugs:
    - your-group/**
- imports:
    - https://cnb.cool/<your-secret-repo-slug>/-/blob/main/docker.yml
    - https://cnb.cool/<your-secret-repo-slug>/-/blob/main/k8s.yml
  use_in_slugs:
    - your-group/project-a
    - your-group/project-b

In the example above:

npm.yml from the first item is injected into the workspace of every repository under your-group/;
docker.yml and k8s.yml from the second item are injected only into your-group/project-a and your-group/project-b.

Scope and Precedence

Scope: only the Workspace environments started by the current user.
Precedence: personal environment variables are injected after the repository pipeline imports, so when variable names collide, personal environment variables override the same-named variables from the repository imports. Variables explicitly declared in env of .cnb.yml still have the highest precedence.

Security and Authorization

Personal environment variables reuse the full imports authorization chain. Before injection, all of the following conditions must be met:

Injection allowlist: the current repository matches the item's use_in_slugs (controls injection targets at the user level).
Reference authorization: before injection, the system checks whether the repository where the current workspace is started is allowed to read the secret file. The rules are the same as pipeline imports:
- The secret file resides in the current repository, or its repository is public — pass directly;
- Cross-repo reference, and the secret file's content declares fields such as allow_slugs (written inside the yml/json file to specify which repositories are allowed to reference it) — checked against those declarations;
- Cross-repo reference, and the file content declares no allow_* at all — you must have read (pull) permission on the secret file's repository.
See Configuration File Reference Authorization for the full rules.

Tips

It is recommended to store secret files in a dedicated secret repository for higher security and reference auditing. The format and parsing rules of secret files are the same as pipeline imports. See File Parsing Rules.

Notes

The total length of the configuration is limited (currently up to 2000 characters); do not store overly long content.
imports only supports CNB in-site file addresses, or relative paths (which are resolved to a file in the repository where the current workspace is started, e.g. ./.cnb/env.yml); external addresses will not be loaded.
Invalid items (e.g. malformed YAML, missing use_in_slugs) are ignored and do not affect normal startup of the development environment.
However, secret file addresses must be accessible: wrong paths, missing files, or failed authorization will cause the workspace to fail to start.

Security Notes

Read inside the container — please follow these recommendations

Personal environment variables are injected into the workspace as environment variables and can be read by any script inside the container (e.g. env, echo $XXX). It is recommended to:

Only inject into groups or repositories you trust: use_in_slugs must scope to a group or specific repositories you trust, and avoid broad wildcards like **; injecting into untrusted repositories risks secret theft — for example, anyone with write permission on those repositories can exfiltrate your injected environment variables in .cnb.yml in many ways (such as curl to an external server, printing to build logs, etc.);
Store secret files in a dedicated secret repository, and never put secret files in public repositories; if you configure allow_slugs inside the secret file, note that it means "allow these repositories to reference this file" — setting it too broadly (e.g. **) will let others reference your secret file too, so keep it as narrow as possible; if the file is for your own use only, you may omit allow_slugs and rely on the pull permission check.