Skip to main content
Variable groups are named collections of key-value pairs scoped to an environment. Link a group to installations that share configuration, such as database credentials or API keys, and update those values in one place. The same group name can exist in several environments with different values. For example, database-credentials in staging can point to a staging database while the group in production holds production credentials.
A production variable group with database configuration and a masked password
For CLI examples, install and authenticate the Ryvn CLI. Commands use your current organization; -e selects the Ryvn environment.

​
Create a variable group

Group names must start with a letter and contain only letters, numbers, hyphens, and underscores. Keys must start with a letter or underscore and contain only letters, numbers, underscores, hyphens, and dots. For environment variables, prefer UPPERCASE_WITH_UNDERSCORES and use names your service reads, such as DATABASE_URL and DATABASE_POOL_SIZE.
1

Choose an environment and name

Open Variables from the sidebar and click Create. Select the target environment and give the group a name, such as database-credentials.
2

Add variables

Add key-value pairs.Toggle the lock icon for sensitive values such as passwords and API keys. A group can contain both sensitive and non-sensitive variables.
3

Save the group

Create the group, then link it to an installation in the same environment. Creating a group alone does not attach it to any installations.

​
Use a group in an installation

In an installation’s Environment Variables section, click the folder-key icon labeled Link variable group and select a group from that environment. Save the installation settings to apply the change.
For server and job installations, every key in the linked group becomes an environment variable with the same name. An environment variable defined directly on the installation takes precedence over a group value with the same key. In installation YAML, add the group under spec.variableGroups:
See the installation YAML reference for the full configuration. Blueprint inputs can also reference individual variable group keys. When group values change, Ryvn queues configuration updates for linked installations and re-evaluates blueprint installations whose inputs reference the group. Review the affected installations after changing shared credentials. Unlinking a group removes its variables from that installation. It does not delete the group or change other installations that use it.

​
Update and compare values

Open a group to add, edit, or remove variables. Review the diff before confirming the update. Changes create revisions so you can inspect the group’s history.
Sensitive values are hidden by default, require permission to reveal, and reveals are audited. A sensitive key cannot be changed to non-sensitive in place. Delete and recreate the key if its sensitivity needs to change. Use Compare to inspect differences between groups or environments. Copy to Environment creates a separate copy in another environment. Future edits to the source group do not keep that copy in sync.

​
Sync from external sources

Ryvn can populate a variable group from Infisical or GCP Secret Manager. A connection stores the provider configuration at the organization level. Each imported group selects a source and a destination Ryvn environment. Imported groups are managed by the external provider. Edit secrets at the source; their values are read-only in Ryvn. Imported values are marked sensitive.
1

Configure a connection

Follow the Infisical setup guide or GCP Secret Manager setup guide, then test the connection.
2

Choose the source

Choose the connection and source settings using the Dashboard or CLI instructions for your provider below.
3

Choose the destination

Give the group a name and select its destination Ryvn environment. The initial sync runs asynchronously.
4

Wait for the first sync

Check the group in the dashboard or with ryvn describe variable-group NAME -e ENVIRONMENT and wait for a successful sync before using its values. Then link it to installations in the destination environment just like a locally managed group.

​
Infisical

Select the connection in Variables > Import, then choose the source project, environment, and secret path. Enable Include imported secrets if needed. Select the destination Ryvn environment, name the group, and click Import Variable Group.
The Infisical environment identifies the source; the Ryvn environment identifies where the imported group will live. The connection’s machine identity must be able to read the selected project, environment, and path.

​
GCP Secret Manager

Select the connection in Variables > Import and add any label filters. Select the destination Ryvn environment, name the group, and click Import Variable Group.
GCP Secret Manager import form with a label filter, variable group name, and destination environment
The connection determines the Google Cloud project. Optionally add secret label filters, such as app=api and stage=production.
  • Every label must match. Multiple filters use AND logic.
  • No filters means all secrets in the connection’s project.
  • A blank label value matches an empty value; it is not a wildcard.
  • Filters cannot be changed after import. Create a new imported group if you need a different selection.
Secret IDs become variable keys without renaming. Use IDs such as DATABASE_URL; IDs starting with a number are not valid variable keys and are skipped with a warning. Hyphens are allowed in group keys, but use underscores for compatibility with applications that expect conventional environment variable names. Ryvn reads the latest version. If that version is disabled or destroyed, it looks for the newest enabled version. Payloads must be UTF-8 text; binary values and secrets without an enabled version are skipped with warnings. The group’s Secret versions section shows which versions were imported.
A complete sync with no matching secrets clears the group’s current values. Check label changes and secret deletions in Google Cloud before relying on the next sync.

​
Sync status and failures

Ryvn syncs imported groups periodically. Imports and manual sync requests run asynchronously.
Click Sync now on the group to request an immediate sync. The group shows its status, last successful sync, errors, and warnings.
Example imported group showing sync status, immutable filters, secret versions, and masked values
Example sync status and version metadata shown with demo data. A failed sync preserves the last successful revision. For GCP imports, if only some secret reads fail, Ryvn retains their previous values where available and reports warnings while updating the secrets it could read. Skipped invalid keys, binary payloads, and secrets with no enabled version do not receive this retention behavior. Revealing imported values requires the group’s read and reveal permissions plus permission to manage organization integrations. Being able to view sync status does not grant access to secret values. Ryvn blocks deletion of a provider connection while imported groups use it. To retire a connection, replace the groups in consuming installations first, then remove the imported groups and delete the connection.