Environment variables

Environment variables hold the configuration you cannot commit to a repository, such as database URLs, third-party API keys and feature flags. Gigadrive Network encrypts every value at rest and injects the resolved set into your build and into every Function a deployment runs.

Where to set them

A variable belongs to exactly one of three scopes. An organization variable reaches every application the organization owns. An application variable reaches one application. An environment variable reaches a single environment of one application, such as production or preview. When the same name exists at more than one scope, the narrowest one wins, which Variable scopes works through in detail.

In the console, organization variables live at /{organization}/settings/variables and application variables at /{organization}/{application}/settings/variables. Both pages can import a .env file, up to 50 variables at a time.

Setting a variable

Each of these creates DATABASE_URL on one environment and marks it sensitive, so the value is never handed back once it is stored.

import { GigadriveClient } from '@gigadrive/sdk';

// Reads GIGADRIVE_CLIENT_ID and GIGADRIVE_CLIENT_SECRET from the environment.
// The key needs the network:env_vars:write scope.
const client = new GigadriveClient();

const variable = await client.applications.envVars.create('0197b2f1-2f4a-7a0b-8a2d-222222222222', {
  key: 'DATABASE_URL',
  value: 'postgres://app:9f2c1b7e@db.example.com:5432/app',
  environmentId: '0197b2f8-92a4-734f-9b90-999999999999',
  sensitive: true,
});

console.log(`${variable.key} is set on ${variable.environmentName ?? 'the application'}.`);

The CLI takes an environment id after --env, not a slug, and --sensitive requires that environment to be production or preview. Leave --env off and the variable applies to every environment of the application. Without --app or --org, the command works on whatever you linked with gigadrive link.

What a Function receives

The environment is assembled once, when the Function starts, from five sources applied in this order. A later row overwrites a name an earlier row already set.

The first three rows are yours to edit. System variables lists the last one, the set a build gets, and the name prefixes the platform keeps for itself.

A Function reads the merged set at startup, so an edit reaches Functions that start after it and leaves whatever is already running on the old value. Editing never starts a build, so deploy again when you want a change applied everywhere at once.

What a build receives

The sandbox gets its whole environment when it is created, before install and build run. The platform's defaults go in first, your resolved variables are applied over them with sensitive values included, and a short list of platform-owned values is applied last. Setting CI or NITRO_PRESET yourself therefore replaces what the platform picked, while GIGADRIVE_DEPLOYMENT_ID stays as the platform wrote it.

Names and values

Prefix matching ignores case, so gigadrive_token is rejected as well. Reusing a name that already exists in the same scope returns 409, so update the existing variable instead of creating a second one.