How Ota Prevents Environment Variable Drift in Repo Setup

Undocumented environment variables are not a small onboarding inconvenience.

They are setup drift.

That drift shows up in familiar ways:

• one maintainer has a required secret only in their shell profile
• .env.example is stale
• local development wants localhost, but Docker Compose wants service hostnames
• CI injects values the repo never actually declares
• a new teammate can see the code, but still cannot tell which missing value is the real blocker

That is exactly the class of problem Ota is meant to make explicit.

Ota does not treat environment handling as an afterthought around a task command. It gives the repo a contract for:

• which env names are part of repo truth
• where ota is allowed to read them from
• which values are required, secret, or constrained
• when one setup path should deterministically materialize an env file
• when different workflows need different env lanes

The goal is simple: stop asking humans and AI agents to guess why the repo is not ready.

Most repos start with file names.

That is backwards.

The first truth is not that a repo has a .env.local file. The first truth is that the repo needs specific values.

In Ota, that belongs in env.vars.

env:  vars:    DATABASE_URL:      required: true      secret: true    REDIS_HOST:      default: localhost      allowed:        - localhost        - redis    APP_ENV:      default: local      allowed:        - local        - ci

That gives the repo a real contract:

• required: true means readiness or execution fails if the value never resolves
• secret: true means ota redacts the value in output and receipts
• default gives a controlled fallback for non-secret settings
• allowed stops drift from quietly becoming accepted truth

This is stronger than “we usually keep that in .env.”

It tells the repo, contributors, CI, and agents which names matter before any process starts.

It also means simple non-secret defaults do not always need a starter dotenv file at all. If the repo standardizes on ota run or ota up, a contract default can often replace shallow .env boilerplate.

Once the repo knows which env names matter, the next question is:

where may those values come from?

That belongs in env.sources.

env:  vars:    DATABASE_URL:      required: true      secret: true    LOG_LEVEL:      default: info  sources:    - kind: dotenv      path: .env.local    - kind: dotenv      path: .env      must_exist: true

This matters for trust.

Ota does not auto-scan every env-like file it can find at runtime. It only loads the source files the contract explicitly declares.

That means:

• the repo can review which files are part of env truth
• must_exist: true turns a missing file into a clear readiness problem
• ota doctor, ota env, ota run, and ota up all operate from the same declared source list

That is governance, not convenience theater.

If a repo depends on .env.local, it should say so.

If a repo does not want runtime truth to depend on some stray local file, ota should not quietly invent that dependency on the repo's behalf.

This is where the difference becomes operational.

When env truth is declared, Ota can fail for the right reason instead of leaving the operator to guess.

A simplified missing-env diagnosis looks like this:

DOCTOR ./ota.yaml

NOT READY

Why:
  required environment variable `DATABASE_URL` did not resolve from task env,
  policy env, shell env, declared sources, or contract default

Next:
  ota env
  inspect declared env sources and precedence
  then supply `DATABASE_URL` through the right owned layer

That is a much better failure mode than:

• a framework boot error with no source provenance
• a generic "config missing" exception
• a new teammate grepping through README snippets and old shell history

The repo is now saying exactly what is missing and where to inspect the winning precedence path.

Sometimes the repo really does own one local env-file bootstrap step.

Maybe the real path is:

• copy .env.example
• replace a few keys
• generate a local secret
• remove one stale flag

That should not live in shell copy-plus-sed glue.

In Ota, that path can be modeled directly with action.kind: ensure_env_file.

tasks:  setup:env:    action:      kind: ensure_env_file      path: .env.local      template: .env.example      vars:        APP_ENV:          value: local          mode: replace        DATABASE_URL:          from_env: DATABASE_URL          mode: replace        APP_SECRET:          random:            bytes: 24            encoding: hex        LEGACY_FLAG:          mode: remove

That is a better setup contract for a few reasons:

• the mutation is inspectable in ota.yaml
• the repo is no longer hiding env truth in helper shell scripts
• the setup lane can be previewed, validated, and reused through one named task

If setup needs several deterministic host-side actions, Ota can move up to action.kind: ensure_bundle rather than collapsing back into shell orchestration.

A lot of setup drift happens because teams flatten unlike runtime paths into one .env story.

That is not always true.

A repo may honestly need:

• one local-development env shape where the app talks to localhost
• one CI or test-isolation env shape
• one Docker Compose self-host env shape where the app talks to service hostnames like redis

Ota models that with env.profiles and workflow selection.

env:  vars:    DATABASE_URL:      required: true    REDIS_HOST:      required: true  profiles:    local:      env:        REDIS_HOST: localhost    selfhost:      sources:        - kind: dotenv          path: .env.selfhost      env:        REDIS_HOST: redis      render:        dotenv:          path: .env.selfhost.rendered          template: .env.selfhost.example          include:            - DATABASE_URL            - REDIS_HOST workflows:  default: local  local:    env:      profile: local  selfhost:    env:      profile: selfhost

This is the maturity move.

The repo is no longer pretending one copied file can truthfully describe every path.

Instead:

• root env.vars still says which names are real repo requirements
• the local workflow can truthfully keep REDIS_HOST=localhost
• the selfhost workflow can truthfully switch that same name to REDIS_HOST=redis
• ota can render one workflow-owned dotenv artifact deterministically when the runtime path needs one

That is exactly the class of problem pressure-testing on Langfuse exposed. Serious repos often have multiple real runtime lanes. Ota should keep those lanes visible, not blur them together just to keep the contract shorter.

One of the most common env mistakes in containerized repos is treating Docker Compose interpolation as if it were the same thing as process env injection.

It is not.

If one task path truthfully owns Compose env-file input, keep that on the adapter-owned surface:

tasks:  selfhost:compose:    adapter_inputs:      overlays:        compose:          env_files:            - .env.selfhost    launch:      kind: command      exe: docker      args:        - compose        - up

That is stronger than hiding --env-file .env.selfhost in a shell body.

It keeps the contract honest about the runtime adapter input the task actually needs.

This is not docs-only structure.

Once the repo declares env truth, ota uses it operationally:

• ota doctor can surface missing required env, missing declared source files, or incompatible values
• ota env can show the declared model and resolved view
• ota run and ota up resolve declared env in deterministic order and inject the winning values into the started process
• receipts and JSON output keep that execution path explainable

Just as importantly, ota does not do a few dangerous things:

• it does not invent secret values
• it does not silently load undeclared env files
• it does not permanently mutate your shell session
• it does not pretend every env problem is a code problem

That last point matters.

Many failed local runs are not application bugs. They are missing configuration truth. A serious readiness layer should help separate those failures instead of forcing contributors to debug the wrong layer first.

If a new teammate spends hours figuring out which secret is missing, the repo's env model is still weak.

The stronger standard is:

• declare the env names the repo actually needs
• declare the files ota may read
• make local env bootstrap deterministic when the repo owns it
• keep workflow-specific env paths explicit when different runtime lanes need different values
• keep Compose env input on the Compose surface instead of shell flags

That is how environment handling stops being setup folklore and becomes declared repo truth.

• Environment Model
• Environment Values Reference
• Contract Reference
• Deterministic env bootstrap example