Variables

Variables store configuration values and sensitive information (like passwords or API keys) so you don't have to write them in your rules and custom code. You define a value once and reference it by name.

Project and Global Variables

There are two scopes of variables:

Any user who can open the page can see the list. Users without permission to manage variables don't see the Create button or the Actions column.

When a job or a test runs in a project, Gigantics merges both scopes: first the global variables, then the project variables. A project variable overrides a global variable with the same name.

Global variables         Project variables        Values used in the project
----------------         -----------------        --------------------------
api_url = https://a      api_url = https://b  ->  api_url = https://b
api_key = ••••••                              ->  api_key = (global secret)
                         region  = eu         ->  region  = eu

Names must be unique inside their scope: two variables of the same project, or two global variables, can't share a name. The same name can exist as a global variable and as a project variable (that is how you override a global value).

Variable Types

There are two types of variables:

• Plain: regular text variables, stored as they are.
• Secret: for sensitive data like passwords or API keys. The value is encrypted before it is stored in the database, and it is shown as ••••••• in the UI.

Creating and Managing Variables

UI Overview

The Variables page shows a table with these columns:

Use Search to filter the table by name, type or value.

Adding a New Variable

1. Click Create in the top right corner.
2. A right panel opens with the New variable form:
   • Name: the variable identifier (required).
   • Type: Plain or Secret.
   • Value: a text area for Plain variables, or a password input for Secret variables (required).
3. Click Save.

Editing a Variable

1. Open the action menu next to the variable.
2. Select Edit. The panel title is Edit variable - <name>.
3. Change the name, type or value.
4. Click Save.

For Secret variables, the value field shows •••••••. If you don't change it, the stored secret is kept.

Deleting a Variable

1. Open the action menu next to the variable.
2. Select Delete.
3. Confirm with Yes, delete in the "Are you sure you want to delete this variable?" dialog.

Using Variables

Inserting a Variable from the Editor

The custom function editor, the custom code editor of anonymize operations and the YAML editors (for example the Custom Params of a data source) have a variables button (Show variables). It opens a list with two groups:

• Project variables: shown when you are inside a project and the project has variables.
• Global variables.

Each entry shows the reference $(name) and its value (•••••• for secrets). Click an entry to insert that reference at the cursor. The value itself is never inserted, so secrets are not copied into the text and a later change of the variable applies everywhere.

How to Reference Variables

In rules and custom code, reference a variable with:

$(variable_name)

For example, for a variable named api_key:

$(api_key)

Inside custom code, all the variables are also available in the $vars object, for example $vars.api_key.

Variables in Data Sources

The connection fields of a data source (host, port, database, user, password, schema, the tunnel settings, the Custom Params and the settings of its password manager) can reference variables with $(name) or with the short form $name:

Host:     $(db_host)
Database: sales_$(environment)

Gigantics resolves them when it connects, with the variables of the data source's project and the global variables. As everywhere else, a project variable overrides a global variable with the same name. A field that is only a reference takes the value of the variable as it is; a reference inside a longer text is replaced by the value as text. A reference to a variable that doesn't exist is left as written.

The short form $name only allows letters, numbers and _ in the name, so it ends at the first other character: in $db_host.example.com the name is db_host. Use $(name) when the reference is followed by more text.

How Values Are Read

Secret values are decrypted when they are used. Then Gigantics reads the value as a JavaScript expression when it can, and otherwise as text:

If you need a value that looks like a number, a date or a list to stay as text, quote it: "123", "2026-10-21".

Benefits of Using Variables

• Security: Sensitive information like passwords and API keys is encrypted and masked
• Flexibility: Change configuration values without modifying your code
• Reusability: Use the same variable across several functions and rules
• Per-project values: Override a global value in one project without affecting the others

Best Practices

1. Use Secret variables for sensitive data: Always use the "Secret" type for passwords, API keys, and other sensitive information
2. Descriptive names: Use clear, descriptive names for your variables to make their purpose evident
3. Global defaults, project overrides: Keep shared values as global variables and create a project variable with the same name only where a project needs a different value
4. Regular cleanup: Remove unused variables to keep your project organized
5. Access control: Only grant the Edit project settings permission to users who need to create or modify project variables

Example Use Cases

• Storing connection strings or endpoints used by custom functions
• Managing API keys for external services
• Keeping configuration values like thresholds or limits
• Using a different value per project for the same function