Variables and secrets

Set workspace variables, keep secrets write-only, and connect runs to your cloud with credential profiles.

Variables pass inputs and environment settings to your runs. Credential profiles give runs access to your cloud without storing long-lived keys.

Add a variable

Open the workspace and select the Variables tab.
Under Add a variable, choose a Category:
- OpenTofu input — passed as an OpenTofu input variable.
- Environment — set as an environment variable for the run.
Enter the Variable key, an optional Description, and the Variable value.
Turn on Parse as HCL for OpenTofu inputs that are lists, maps, or other HCL expressions.
Turn on Sensitive value for passwords, tokens, and other secrets.
Select Create variable.

To add many non-sensitive variables at once, select Add several at once and paste KEY=value lines, then select Create variables from lines. Blank lines and lines starting with # are skipped.

With the API, use POST /v1/workspaces/{workspace_id}/variables.

Variables are per workspace; shared variable sets aren’t available.

Edit or delete a variable

Select Edit on a row to change its description, HCL setting, or value. Leave the value blank to keep the current one. To change whether a variable is sensitive, enter the value again.

Runs that already started keep the value they began with; edits and deletions affect new runs only.

Changing variables requires the admin or owner role. Members can view variable names and non-sensitive values.

Sensitive values

A sensitive value is write-only:

the dashboard and API never show it again after you save it — the API returns null for its value and value_digest;
runs receive it, but speculative pull-request runs never do; and
to change it, enter a new value.

Keep a copy of each secret in your own secret manager.

A plan fails if a sensitive value of 8 or more characters appears in a resource attribute your configuration doesn’t mark sensitive, so the value never reaches policy checks. Declare the variable that carries it with sensitive = true and plan again.

Limits

Limit	Value
Key length	256 characters
Description length	1,024 characters
Value size	64 KiB (65,536 bytes)

Reserved environment variable names

You can’t set these environment variable names:

anything starting with STACKSHIP_, TFC_, TF_CLI_ARGS, or TF_LOG;
TF_TOKEN_stackship_run, TF_CLI_CONFIG_FILE, TF_WORKSPACE, TF_DATA_DIR, TF_IN_AUTOMATION, TF_FORCE_LOCAL_BACKEND, TF_STATE_PERSIST_INTERVAL, and TF_ENCRYPTION; and
TF_CLOUD_HOSTNAME, TF_CLOUD_ORGANIZATION, TF_CLOUD_PROJECT, TF_PLUGIN_CACHE_DIR, TF_PLUGIN_CACHE_MAY_BREAK_DEPENDENCY_LOCK_FILE, TF_REATTACH_PROVIDERS, and TF_DISABLE_PLUGIN_TLS.

For a provider setting, use the provider’s own variable name instead. For OpenTofu inputs, use the OpenTofu input category rather than TF_VAR_ environment variables.

Cloud credentials

Credential profiles connect a workspace to AWS, Google Cloud, or Microsoft Azure through short-lived federation: each run gets temporary credentials, and no cloud key is stored in StackShip.

Create a profile

Go to Credentials and select Create credential profile.
Choose the Workspace, enter a Profile name, and choose the Provider.
Select Create profile.

Add and verify a version

On the profile page, choose a Run phase:
- Plan and apply — used by normal runs.
- Speculative plan — used only by pull-request plans when you select it on the workspace’s Source tab. Give this role read-only cloud permissions.

Enter your provider details:

Provider	Fields
Amazon Web Services	AWS region and AWS role ARN
Google Cloud	Service account email and Workload provider name (`projects/NUMBER/locations/global/workloadIdentityPools/POOL/providers/PROVIDER`)
Microsoft Azure	Azure application client ID, Azure subscription ID, and Azure tenant ID

Select Create pending version.
Copy the provider trust template shown beside the version and apply it in your cloud account. It lets StackShip runs for this workspace and phase assume your role.
Select Verify version. Runs use the version only after it verifies.

An organization can start at most 20 verifications every 10 minutes. Beyond that, verification fails with 429 CREDENTIAL_VERIFICATION_RATE_LIMITED; wait a few minutes and try again. Retrying with the same Idempotency-Key returns the original result and doesn’t count as another verification.

AWS profiles support the commercial AWS partition. GovCloud and China regions aren’t supported.

With the API, use POST /v1/workspaces/{workspace_id}/credential-profiles, then POST /v1/credential-profiles/{id}/versions, GET /v1/credential-profiles/{id}/trust-template, and POST /v1/credential-profiles/{id}/versions/{version_id}/actions/verify.

Revoke or archive

Revoke version stops that version from being used immediately, including by runs already queued.
Archive profile detaches a profile from its workspace immediately. Its history is kept.

Both actions are recorded in the audit log. Managing credentials requires the admin or owner role.

Generic environment secrets

When a service has no federation option, create a profile with the Generic environment secrets provider and add the secret values as environment variables.

Each version holds 1 to 32 secrets, up to 64 KiB in total.
Names must start with a letter or underscore and contain only letters, digits, and underscores (up to 128 characters). Reserved names, and names like PATH, HOME, or LD_PRELOAD, aren’t allowed.
Values are write-only and can’t be read back.
Generic secrets are used for Plan and apply only — never for pull-request plans.

Your configuration, providers, and modules can read these values during a run, and runs have outbound internet access; you must acknowledge this before you save. Use generic secrets only with repositories and modules you trust, give each secret the least access it needs, and prefer federation when available.