# Working with environment variables

The platform 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.application-platform.com/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 |

The platform overwrites the generated files whenever the configuration changes, so you do not edit them; in the custom files you add or override values. `ap 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 the platform 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
```

The platform 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 the platform; in `generated.yaml` they are encrypted with SOPS and edited with `ap 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 the platform-managed secrets.
{{< /docnote >}}

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