# Working with environment variables

MainPath writes the generated env files, your own values belong in the custom files, and the deployment to dev and prod is configured in the gitops-configuration repository.

> Source: https://www.mainpath.ai/en/docs/environment-setup/

## The files in the env/ directory

The `env/` directory in app and backend repositories contains files following the pattern `<environment>.<kind>.env` with the environments `local`, `dev`, `prod`, and `shared` (all environments) and the kind `generated` or `custom`.

| File | Maintained by | Contents |
|------|---------------|----------|
| `local.generated.env` | platform | URLs and values for local development |
| `local.custom.env` | you | your own values for local development |
| `dev.generated.env`, `prod.generated.env` | platform | values per environment, such as the backend URL on dev or prod |
| `dev.custom.env`, `prod.custom.env` | you | your own values per environment |
| `shared.generated.env` | platform | values for all environments, such as the Sentry DSN and bundle IDs |
| `shared.custom.env` | you | your own values for all environments |

MainPath overwrites the generated files whenever the configuration changes, so you do not edit them; in the custom files you add or override values. `mp run-local` loads both kinds for the matching environment, for Flutter apps via `--dart-define-from-file`; a new local variable goes into `env/local.custom.env` followed by a restart, a value for all environments into `shared.custom.env`. New generated values require a change to MainPath configuration; ask [support]({{< relref "/support" >}}).

## Deployment configuration for dev and prod

What runs on the servers is configured in your project's `gitops-configuration` repository with one folder per environment:

```
gitops-configuration/
└── configurations/
    ├── dev/
    │   ├── generated.yaml   # platform: hostnames, registry, secrets (SOPS)
    │   ├── custom.yaml      # you: your own environment variables
    │   └── versions.yaml    # pipeline: deployed image versions
    └── prod/                # same structure
```

MainPath writes `generated.yaml`, the pipeline maintains `versions.yaml`, and `custom.yaml` is yours and takes your own environment variables under `additional_env_variables`. A commit to `main` rolls the change out to the respective environment, as [Git workflow and deployment]({{< relref "git-workflow" >}}) describes; the overall picture is shown in [Architecture]({{< relref "architecture" >}}).

## Secrets

Passwords, tokens, and keys such as database credentials, JWT secrets, and registry credentials are generated and managed by MainPath; in `generated.yaml` they are encrypted with SOPS and edited with `mp secrets edit <file>`.

{{< docnote type="warning" >}}
The custom files in `env/` and `custom.yaml` are unencrypted text files in the repository. Passwords or API keys that need protection do not belong there, but in MainPath-managed secrets.
{{< /docnote >}}

Do not print env files in full, not even in a chat with an AI agent, and never commit secrets; the agent plugin already contains this rule.