Variable scopes

Gigadrive Network stores a variable at one of three scopes, and the same name can exist at all three at once. The narrowest scope wins, so an environment value beats an application value, which beats an organization value.

The three scopes

Every application starts with a production and a preview environment, and you can add more. Environments covers creating them.

How a value resolves

The three scopes are merged in a fixed order at build time and again when a Function starts: organization first, then application-wide, then the environment the deployment belongs to. Each pass overwrites names it has already seen, so the last writer wins.

A deployment that belongs to no environment resolves the first two scopes only.

What sits outside the scopes

Two more sources are applied after all three, and one candidate is not a source at all. A framework adapter can record values while your project builds, such as NEXT_BUILD_ID on a Next.js project, and those land on top of yours. The platform applies its own values last, so a name it owns cannot be shadowed by one you store: System variables lists them.

The env map in gigadrive.yaml is not a source at all. It passes schema validation and nothing in the deployment pipeline applies what it holds, so a name written there reaches neither a build nor a Function. The Configuration reference records it alongside the other keys that are accepted and not applied.

Setting an organization variable

This stores a shared value on the organization, where every application picks it up without being configured individually.

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

const client = new GigadriveClient();

const variable = await client.organizations.envVars.create('0197b2aa-1c33-7f10-9c41-111111111111', {
  key: 'SENTRY_ORG',
  value: 'acme-eu',
});

console.log(`${variable.key} now applies to every application in the organization.`);

Organization variables have no pull endpoint. gigadrive env pull runs against an application and returns the merged non-sensitive result, which already includes whatever the organization contributes.

Picking a scope

The organization is the right home for a value several applications genuinely share, such as an observability project slug or an internal registry host. Anything that identifies one application and stays the same across its environments belongs on the application. Everything that differs between production and preview goes on the environment, and so does every secret: Sensitive values explains why secrets are confined to those two.