Docs · Concepts

Environments and variables

Keeping credentials and per-context values out of your queries, and the order in which names resolve.

Everything in Mosaic that substitutes a value uses one syntax: {{name}}.

It works anywhere in a source's configuration — a URL, a header, a body, a SQL statement, a bind, a Mongo pipeline. Not just the fields that look like they would take one.

#Environments

An environment is a named set of values: "Keep values and credentials separate for each system context."

The usual shape is one per tier — Test, Staging, Production — each defining the same names with different values. The same Check then points at either by switching environment, with nothing edited.

Each variable has a key, a value, an enabled switch and a secret flag.

Secret values are encrypted at rest and masked once saved. The field then reads "Saved — type to replace", and the value is never shown again.

#The active environment is yours, not the workspace's

This surprises people, so it is worth stating plainly: the environment selector in the top bar is per person. Your colleague can be pointed at Test while you are on Production. There is no workspace-wide default.

The choice is remembered for your account and sent with every run. The empty choice is No environment.

Deleting an environment clears the selection for anyone using it, and the data sources that referenced its variables stop resolving.

#Library variables

Named values every Check can read as {{name}}, without being added to any of them. A variable saved in the library resolves everywhere in the workspace.

Any Check can override one by declaring a parameter of the same name. The parameter says so when it does, and offers to revert.

#The order names resolve in

Four scopes, narrowest wins:

library variable → Check parameter → environment variable → run-time override

The reasoning, which makes it easy to remember:

• The library sits at the bottom because it is the only scope nobody opted into. It is readable everywhere, so it must be overridable everywhere.
• The environment beats the Check because it is the more specific context: the same Check points at test or production by switching it.
• A run-time override beats everything, because somebody typed it moments ago.

#Where credentials belong

In an environment variable, marked secret. Not in a parameter, and not typed into a field.

Mosaic says so in both places it matters. On a webhook URL: "A webhook URL is a credential. Keep it in an environment variable and reference it as {{name}}; typed in directly it is stored and exported in cleartext." And on parameters: "Credentials belong in an environment, not here: report parameters are stored and exported in cleartext."

That is not a style preference. Parameters travel — into run records, into exports, into a published page's filters.

#Who can change them

Reading an environment is a viewer's right. Creating, editing and deleting one is an admin's, because an environment holds the credentials every source running under it will use.