Introduction
Laravel Cloud’s Secrets Manager allows you to define encrypted secrets at the organization level and link them to one or more environments. This is useful for values that are shared across environments, such as third-party API tokens, GitHub tokens, Cloudflare credentials, or other sensitive configuration.
Unlike custom environment variables, secrets are managed centrally. When a shared value changes, you update it once rather than copying it into each environment individually.
Laravel Cloud injects secrets into your application as environment variables during deployment.
Creating secrets
To create a secret, navigate to your organization’s dashboard and click Settings > Secrets. Then, click New secret.
Each secret has a key, value, and optional notes. Secret keys must start with a letter or underscore and may only contain letters, numbers, and underscores. For example:
You may create multiple secrets at once by clicking Add another. This is useful when adding a group of related credentials, such as AWS or Cloudflare credentials.
When creating a secret, you may optionally select the environments where it should be used. You can also link secrets to environments later from either the organization settings page or the environment’s general settings.
Secret keys do not need to be unique. For example, you may create a separate STRIPE_SECRET for each of your applications, using the notes field to distinguish them.
Managing secrets
To edit a secret, navigate to Settings > Secrets and select the secret from the list. You may update its value, notes, or linked environments.
Secret values are write once, read never. When editing a secret, Laravel Cloud does not show the existing value. To rotate a secret, enter a new value and save your changes.
Linking secrets to environments
A secret affects an environment only after you link it. To link secrets from an environment, open the environment’s general settings, scroll to the injected variables section, and click Link secrets.
From the link secrets dialog, you may select one or more organization secrets to attach to the environment. Environments have a hard limit of 30 linked secrets.
Deploying changes
Laravel Cloud decrypts and injects secrets during deployment. After creating, updating, linking, unlinking, or deleting a secret, redeploy each affected environment for the change to take effect. When you link or unlink secrets, the change is staged on the environment, and you can deploy it from the staged changes banner.
Variable precedence
Laravel Cloud merges secrets into the environment variables generated for a deployment. If a custom environment variable and a linked secret use the same key, the custom environment variable takes priority. Custom environment variables also take priority over Laravel Cloud’s automatically injected variables.
This allows you to use shared secrets for common configuration while still overriding a value in a specific environment when needed.
Security
Your browser encrypts secret values before submitting them to Laravel Cloud. Your browser does not send the plaintext value to Laravel Cloud’s servers when you create or rotate a secret.
Laravel Cloud stores the encrypted value and decrypts it only when creating a deployment for an environment that uses the secret. Laravel Cloud protects organization key material with AWS Key Management Service (KMS).
Permissions
Access to Secrets Manager depends on your organization role and permissions. Creating, editing, and deleting secrets are organization-level permissions, while linking secrets to an environment is controlled by a dedicated environment-level permission.
For more information about organization access, see Role-based access control.
