add environment variable information (#714)

Closes #707

---------

Co-authored-by: Jye Cusch <[email protected]>

Author: HomelessDinosaur

docs/reference/env.mdx

@@ -14,3 +14,33 @@ If you are running your project in the cloud, build, or the run environment, Nit
 | ------------------ | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
 | 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:
+
+```text label:.env
+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.
+
+```bash
+nitric start --env-file ./config/.env.local
+
+nitric 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](/guides?tags=CI/CD) 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.