Environment variables

A variable is plain or secret and applies to one or more targets (production, preview). A shared variable is owned by the team and linked into apps; the link is what injects it.

App variablesCopy Anchor Link

envCopy Anchor Link

Any signed-in principal. Returns [EnvVar!].

Env vars of a single project (requires manage_env).

query {
  env(appId: "prj_9f1c2ab7d3e4f5a6") {
    id
    key
    type
    targets
    isMasked
  }
}

allAppEnvCopy Anchor Link

Any signed-in principal. Returns [AppEnvGroup!].

Every app's env vars in the active team, grouped by project.

query {
  allAppEnv {
    app {
      slug
    }
    vars {
      key
      type
    }
  }
}

upsertEnvCopy Anchor Link

Needs manage_env. Returns EnvVar.

Create or update an env var, then return the stored entity.

mutation {
  upsertEnv(
    input: { appId: "prj_9f1c2ab7d3e4f5a6", key: "DATABASE_URL", value: "postgres://shop:secret@db-orders:5432/orders", type: secret, targets: [production, preview] }
  ) {
    id
    key
    type
    targets
    isMasked
  }
}

renameEnvCopy Anchor Link

Needs manage_env. Returns EnvVar.

Rename an env var's key in place, then return the stored entity.

mutation {
  renameEnv(id: "env_9f1c2ab7d3e4f5a6", newKey: "POSTGRES_URL") {
    id
    key
    type
    targets
    isMasked
  }
}

deleteEnvCopy Anchor Link

Needs manage_env. Returns Boolean.

Delete an env var. Returns true.

mutation {
  deleteEnv(id: "env_9f1c2ab7d3e4f5a6")
}

setAppEnvCopy Anchor Link

Needs manage_env. Returns Int.

Replace an app's whole env set from the .env editor (upsert the given entries, delete the rest). New vars default to plain; existing secrets are left untouched. Returns the resulting variable count.

mutation {
  setAppEnv(
    appId: "prj_9f1c2ab7d3e4f5a6"
    entries: [{ key: "NODE_ENV", value: "production" }, { key: "PORT", value: "3000" }]
    defaultTargets: [production, preview]
  )
}

importEnvCopy Anchor Link

Needs manage_env. Returns EnvImportResult.

Bulk-import a .env-style blob. Every line lands as plain, so a key that already exists as a secret is skipped rather than downgraded.

mutation {
  importEnv(appId: "prj_9f1c2ab7d3e4f5a6", blob: "API_URL=https://api.example.com\nLOG_LEVEL=info", targets: [production]) {
    added
    skippedSecrets
  }
}

makeEnvSecretCopy Anchor Link

Needs manage_env. Returns Boolean.

Make a variable Secret without changing its stored value or scope.

mutation {
  makeEnvSecret(id: "env_9f1c2ab7d3e4f5a6")
}

Shared variablesCopy Anchor Link

sharedVarsCopy Anchor Link

Needs manage_env. Returns [SharedVar!].

All shared variables in the active team, A->Z.

query {
  sharedVars {
    id
    key
    type
    teamWide
  }
}

sharedVarsForAppCopy Anchor Link

Needs manage_env. Returns [AppSharedVar!].

Every team shared variable as seen from one app, with its opt-in (link) state.

query {
  sharedVarsForApp(appId: "prj_9f1c2ab7d3e4f5a6") {
    id
    key
    linked
    inScope
  }
}

saveSharedVarCopy Anchor Link

Needs manage_env. Returns SharedVar.

Create or update a shared variable; returns the saved entity.

mutation {
  saveSharedVar(
    input: { key: "API_BASE_URL", value: "https://api.example.com", type: plain, teamIds: [], projectIds: [], environmentIds: [], appIds: ["prj_9f1c2ab7d3e4f5a6"] }
  ) {
    id
    key
    type
    teamWide
  }
}

setSharedVarAppLinkCopy Anchor Link

Needs manage_env. Returns Boolean.

Link or unlink a shared variable to one app. Returns true.

mutation {
  setSharedVarAppLink(varId: "svar_9f1c2ab7d3e4f5a6", appId: "prj_9f1c2ab7d3e4f5a6", linked: true)
}

deleteSharedVarCopy Anchor Link

Needs manage_env. Returns Boolean.

Delete a shared variable. Returns true.

mutation {
  deleteSharedVar(id: "svar_9f1c2ab7d3e4f5a6")
}

makeSharedVarSecretCopy Anchor Link

Needs manage_env. Returns Boolean.

Make a variable Secret without changing its stored value or scope.

mutation {
  makeSharedVarSecret(id: "svar_9f1c2ab7d3e4f5a6")
}

See alsoCopy Anchor Link