Environment Variables
Nitric sets a number of environment variables to help you manage your project. These variables are available in the cloud, build, and run environments.
System Environment Variables
If you are running your project in the cloud, build, or the run environment, Nitric provides prefixed Environment Variables, which you can find in the table below.
| Name | Description |
|---|---|
| NITRIC_STACK_ID | The Stack ID of the project. Example: coolkat-gcp-4c0wg0hg |
| NITRIC_ENVIRONMENT | The Environment that the app is running on. The value can be either cloud (for deployed in the cloud), run (for stacks running in nitric run), or build (for stack code running during the deployment gathering phase). |
Application Environment Variables
To use environment variables locally and in your deployed projects, you can create a file named .env. When running your project locally using nitric start the environment variables will be made available to your application. When running your project using nitric run and nitric up, the service is built into an image with the environment variables added at build time. An .env file might look like this:
API_URL=http://this.is/a/test-url
If you wish to use an environment variable file that is in a different location, you can point to the file using the --env-file or -e flag.
nitric start --env-file ./config/.env.localnitric up -e ./config/.env.cloud
CI/CD Pipelines
Environment variables will also be pulled from a .env file when deploying your projects in a CI/CD environment, however, most CI/CD platforms provide options for using sensitive values. You can take a look at our CI/CD guides here to see individual recommendations for each platform's workflow configurations.
When should I use Secrets instead?
You should use cloud secrets over environment variables for services when you are using sensitive values and/or you require dynamic secret rotation or updates. Beyond this, you should be using Cloud Secrets when:
- Your secret needs to be rotated dynamically: Cloud secret managers support automatic rotation. This ensures your services always retrieve the latest secrets without redeployment.
- You need access control & audit logging: Cloud secret managers provide fine-grained access control (e.g., IAM policies) and track access logs, enhancing security and compliance.
- Your secret contains sensitive configuration values: Environment variables may be exposed in process lists, logs, or debugging tools. Secret managers keep values encrypted and only accessible at runtime.
- Your secret is shared across multiple services: If multiple services need access to the same credentials, cloud secrets prevent duplication and simplify management.
- You want to avoid redeployment for secret changes: Environment variables require redeployment to update secrets, whereas cloud secret managers allow dynamic retrieval and updates at runtime.