Variables and secret references
Vars configure an App without changing its source code. They have three value classes with different visibility and delivery contracts.
| Value class | Use for | Value visibility | Available to |
|---|---|---|---|
| Environment variable | Non-sensitive runtime configuration | Plain text in App settings | Running App containers |
| Runtime secret | Passwords, API keys, tokens, and private keys | Write-only after save | Selected running App containers |
| Build secret | Credentials required while building an image | Write-only after save | The isolated image build, not the running App |
Secret references contain delivery metadata only. Secret values don’t appear in the platform-managed App settings file, the applied configuration read model, operation history, or customer-visible logs.
Environment-variable names
Section titled “Environment-variable names”synsmarts canonicalizes every customer variable and secret-reference name before validation:
- apply Unicode compatibility normalization;
- convert letters to uppercase;
- replace each sequence outside
A-Zand0-9with_; - remove leading and trailing underscores.
Examples:
| Entered name | Effective name |
|---|---|
feature mode | FEATURE_MODE |
payments-api-token | PAYMENTS_API_TOKEN |
__cache.region__ | CACHE_REGION |
already_NORMALIZED | ALREADY_NORMALIZED |
A name that contains no letters or digits after canonicalization is invalid.
Non-secret environment-variable names must be unique by effective name.
Secret-reference names must be unique within each runtime target. For example,
payments-token, PAYMENTS_TOKEN, and payments token collide when they
appear in the same name scope. A runtime secret also can’t use the same
effective name as a non-secret environment variable in a container where that
secret is delivered.
Reserved names
Section titled “Reserved names”Customers can’t replace names owned by the platform.
The following prefixes are reserved:
AWS_DATABASE_MAGENTO_OTEL_S3_UPLOADS_
Current exact reserved names outside those prefixes are:
CRON_MAX_OVERLAPCRON_STATE_DIRLOG_FORMATLOG_LEVELMYSQL_HOSTOPENSEARCH_HOSTPATHPHP_ERROR_REPORTINGREDIS_CACHE_HOSTREDIS_CONFIG_CACHE_HOSTREDIS_SESSION_HOSTTENANT_ID
The server validates against the current platform registry. If a submitted name becomes reserved, the change is rejected rather than silently overriding the platform value.
Environment variables
Section titled “Environment variables”Environment variables are app-level, non-secret strings. Use them for feature flags, hostnames, log levels, and other values that are safe to display in App settings.
Removing an environment variable removes it from the next applied runtime configuration. Application code must handle missing optional values.
The platform can’t identify every credential pasted into a plain-text field. Choosing the correct value class is part of the customer security boundary: never store a password, token, private key, or recovery code as an environment variable.
Secret-reference fields
Section titled “Secret-reference fields”A secret reference has these customer-visible parts:
| Part | Contract |
|---|---|
| Environment name | The canonical name exposed to the consuming process. |
| Secret key | The logical storage key for the write-only value. |
| Class | runtime for a running process or build for an image build. |
| Runtime targets | The containers that receive a runtime secret. Build secrets have no runtime target. |
The default secret key is the environment name converted to lowercase
snake-case. For example, PAYMENTS_API_TOKEN defaults to
payments_api_token.
Change the secret key only when an integration requires a different logical key. Changing the key retargets the reference, so the request must include the secret value again.
Each secret value must be 60 KiB or smaller.
Runtime-secret targets
Section titled “Runtime-secret targets”Runtime secrets default to all supported runtime containers. Advanced options can restrict a secret to the smallest required set.
| Portal target | Settings target | Typical consumer |
|---|---|---|
| PHP runtime | php_fpm | WordPress, Magento, or custom PHP code |
| Web server | nginx | Validated Nginx runtime behavior |
| Scheduled jobs | cron | Cron PHP and scheduled commands |
| Managed shell | shell | Commands run in the App shell |
One stored runtime value can be delivered under the same environment name to multiple selected targets. A secret isn’t broadcast to containers that don’t declare the reference.
Write-only behavior
Section titled “Write-only behavior”Runtime secret values are write-only. After a secret is saved, the portal shows that a value exists but can’t display the original value. The value field is masked while you type it.
This applies to customer-supplied secrets. Platform-generated credentials are a
separate class: synsmarts issues them, so it can show them back to you. The only
one today is DATABASE_PASSWORD in the Platform provided group, which Team
owners and admins can copy or reveal; both actions are rate limited and recorded
in Team activity. See
Manage Vars and secrets.
- Leave the value field empty when editing unrelated settings to preserve an existing value.
- Enter a replacement value to rotate a secret.
- A new reference, a reference whose key or class changed, or an existing reference added to another runtime target requires a value in the same request.
- Remove the reference to stop delivering the secret after the change applies.
If you don’t know the current value, retrieve it from the credential issuer or rotate it there and in synsmarts. Support can’t read it back for you.
Build secrets
Section titled “Build secrets”Build secrets are mounted only into an isolated image build. They aren’t added to the running environment. Build steps must not copy a mounted credential into the source tree, an image layer, a build artifact, or a cache; doing so can persist the value outside the protected secret mount.
Magento Apps provide an empty COMPOSER_AUTH slot with the default key
composer_auth. The value is the complete Composer authentication JSON
document. Leaving the empty default slot unchanged doesn’t create a secret
reference.
Saving or applying a build-secret change doesn’t rebuild the current image. The next image build uses the current build-secret value.
Desired and running state
Section titled “Desired and running state”The Vars page shows desired configuration. The running App can remain on the last successfully applied configuration while a newer revision is staged or being applied.
| Action | Desired settings file | Running containers | Build image |
|---|---|---|---|
| Save for next restart | Updated immediately | Unchanged until the next managed restart | Unchanged |
| Apply now | Updated immediately | Config deploy restarts containers | Unchanged |
| Later image build | Unchanged | Updated only if a runtime rollout also runs | Uses current build secrets |
Use Apply now for runtime-secret rotation or removal so an already-running process doesn’t continue using the previous credential. A later managed restart also promotes staged Vars.
Verify safely
Section titled “Verify safely”- For an environment variable, verify the App feature that consumes it.
- For a runtime secret, verify the authenticated integration without printing the value, dumping the environment, or exposing a diagnostic page.
- For a build secret, run a build that requires it and verify the build result.
- After removing or rotating a credential, verify that the replacement works and revoke the old credential at its issuer.
- If an apply fails or its final state is unknown, load the latest Vars configuration before entering a write-only value again.
Never place secret values in source control, the App settings file, support requests, screenshots, operation notes, command output, or customer documentation.
See Manage Vars and secrets for the portal workflow
and App settings file for the
authoritative env and secret_refs sections.