Deployment and CI

ramenv is a native executable that runs your application as a child process. Install it in the runtime environment and add it to PATH.

Provision before deployment

Initialize the workspace and configure values before deployment. init, set, and onboarding require interactive input, so keep them out of unattended startup scripts.

A cloud provisioning identity needs create and update permissions. A runtime identity reading existing keys can use read-only secret permissions. Rotation and environment removal need additional write or delete access.

rotate --yes and remove-env --yes confirm workspace-wide changes without a prompt. Other interactive commands still require input.

Ship the right files

Include:

• .ramenv.workspace.toml at the workspace root.
• The service’s .ramenv.vault.toml in the directory from which ramenv runs.
• .ramenv.keyrefs.toml at the root for cloud ingredients.
• The matching .ramenv.keys supplied securely at the root for the local ingredient.

Do not put local keys, personal CLI credentials, or service-account private keys in a public container image or repository. For local storage, deliver the key file through your deployment platform’s secret mechanism and restrict file access.

Runtime cloud key loading reads all recorded encryption and signing key references, including those for environments and services other than the one being run. The runtime identity must be able to read those pinned versions. If you need a stricter access boundary, use separate workspaces rather than assuming run production limits key loading to production.

For monorepos, preserve the service’s location relative to the workspace root. Run from that service’s vault directory. Workspace-wide maintenance additionally needs the registered vault files it will update.

Use a workload identity

Choose the setup matching your ingredient:

Provider	Deployment approach
AWS	Attached instance, task, or workload role; remove higher-priority personal profiles and access-key variables.
Azure	Managed identity or federated workload identity; select it explicitly when discovery must not choose developer tools.
Google	Attached service account or supported federation; omit local ADC files when metadata identity is intended.

Configure the identity on your hosting platform and grant it read access in the workspace’s saved region, vault, or project. A platform login alone grants no secret-store permissions.

Use the AWS, Azure, or Google Cloud guide for credential precedence and permission names. Keep credential contents and token-file contents out of ramenv’s workspace metadata and refs.

Validate before starting

Example for a POSIX shell:

ramenv validate production && ramenv run production -- ./my-server

run does not validate on its own. Configure CI to fail when validation fails. In a monorepo, validate each required service from its own directory.

ramenv overrides matching inherited environment variables and retains other inherited variables. It propagates the child process’s exit code. The application still needs its normal runtime, files, and dependencies.

Keep logs and recovery safe

Avoid list --reveal and diff --reveal in CI. Even default masking can expose portions of values. Applications can also log secrets or include them in crash dumps.

Back up local keys or retain the required cloud key versions alongside corresponding vault versions. Version-pinned refs do not make a deleted or disabled remote key readable. Coordinate rotation with deployments; removal can delete the entire provider secret and its versions.

Consult the security and recovery and troubleshooting guides before deleting keys needed by a deployment.