tl;dr
Deployment configuration should remain reviewable in git when it describes auditable application shape or policy. One diff should show the code and the system it intends to run. A dashboard and CLI should not become competing writers for the same desired state.
- Git makes intent inspectable. Reviewers can see services, routes, policy, resources, and schedules change with the code that depends on them.
- One writer prevents drift. A dashboard edit that a later deploy silently reverts creates two incompatible truths.
- Agents work naturally through diffs. They can propose, validate, review, and revise repository state without hidden dashboard context.
- Not everything belongs in git. Secret values, external account linkage, and destructive stateful lifecycle actions need separate controlled surfaces.
- Reconciliation must be complete. Applying additions while ignoring removals or changed existing resources does not make the file authoritative.
Deployment configuration is easy to scatter.
A route lives in a repository file. CPU lives in a dashboard. Access policy lives behind an API. Cron lives in another page. A CLI changes one value directly. The application still runs, until a deploy re-applies older state or an agent reads the repository and reaches the wrong conclusion.
The problem is not that dashboards or CLIs exist. The problem is two durable writers for one auditable fact.
desired state needs one authority
Consider a service's memory limit.
If the repository says 512 MB and the dashboard says 1 GB, which value describes the intended application? If the dashboard wins now but the repository wins on the next deploy, the platform has created a delayed rollback no reviewer can see.
The invariant is simple:
One auditable property has one authoritative writer.
For application shape and policy, git is usually the strongest writer because the change can travel with the code, receive review, produce a stable history, and reconstruct the same desired state later.
This includes properties such as:
- service topology and roles;
- build and start behavior;
- routes and public exposure;
- access and edge policy;
- resource sizing and scaling posture;
- cron schedules;
- preview policy;
- declarations of managed dependencies.
The dashboard can remain the best window into observed state. It can show what deployed, what failed, what drifted, and what needs attention. A window does not need to become a second source of truth.
agents make hidden state more expensive
A human operator can remember that staging needs a dashboard override. An agent working from a fresh checkout cannot.
Agents are good at repository work because the substrate is explicit:
- read the current files;
- propose a diff;
- run validation;
- ask for review;
- revise the same artifact;
- connect the merged commit to the runtime result.
Hidden dashboard state breaks that chain. The agent may generate a correct configuration that is ignored by a stronger dashboard value, or it may omit a required setting that only exists out of band. Either way, repository review no longer describes the proposed system.
This is why deployment infrastructure for agents needs provenance from repository state to the running environment. The platform should report which source produced each applied value, but the cleaner architecture is to avoid competing writers in the first place.
precedence is not the same as authority
Platforms often resolve dual writers with precedence: file beats dashboard, environment override beats project default, command-line flag beats both.
Precedence makes the result deterministic. It does not make intent legible.
Railway, for example, supports railway.toml and railway.json for build and deploy configuration. It documents that file-defined values override dashboard settings for a deployment without updating the dashboard settings. Its deployment view shows where a value originated. That is an explicit and inspectable precedence model.
The stronger config-as-code model removes the dashboard mutation for properties the repository owns. There is then no dormant value waiting to reappear when the file key disappears.
a config file is authoritative only if reconciliation is complete
Many systems apply configuration additively:
- create declared resources that do not exist;
- update a subset of declared values;
- leave undeclared live resources untouched;
- skip changes to resources that already exist.
That may be the correct safety posture for stateful infrastructure. It is not a full reconcile.
For a config-only surface, authoritative reconciliation means:
add declared, update to declared, remove undeclared.
If removing an undeclared item would destroy state, the platform should not pretend ordinary reconciliation is safe. It should separate declaration from destructive lifecycle and require an explicit, reviewed operation.
This distinction prevents two bad outcomes. Automatic deletion does not surprise the user, and omitted resources do not silently remain while the file claims to describe the whole system.
what should not live in git
Git is excellent for auditable intent. It is the wrong place for several categories of state.
secret values
The repository can declare that a service needs a secret key. The value stays write-only in a secret store and is injected at runtime. Review should never require exposing the credential.
external account linkage
GitHub App installations, OAuth grants, provider account bindings, and similar credentials are external relationships. Their identifiers and status may be visible, but their secret material and consent lifecycle do not belong in repository configuration.
operational data
Alert acknowledgements, user membership, current feature-flag values, and similar runtime operations often need an API or dashboard as the authoritative surface. Not every changing value is deployment configuration.
destructive stateful lifecycle
Declaring that an application uses a database can be reviewable in git. Destroying the database should require an exact plan, evidence, and human approval. A missing line should not silently erase durable state.
The classification matters more than ideological purity. Put auditable shape in git. Put opaque secrets, external consent, operational data, and irreversible state transitions behind purpose-built controls.
review needs the merged system, not isolated fragments
Configuration review becomes most valuable when a change crosses code and infrastructure.
A new worker may require a queue, environment variable, cron schedule, route change, and database migration. If those changes live in one reviewable diff, a human or agent can ask whether the system is complete before it runs.
If half of the change lives in dashboards, the pull request cannot prove completeness. The reviewer approves code that depends on invisible preparation. The environment becomes a snowflake.
A software factory needs the opposite. The repository holds intent. A production-shaped preview executes it. Structured runtime evidence reports what happened. Human gates stop consequential transitions.
where floo fits
floo treats auditable application configuration as repository authority. Service shape, routes, access policy, edge policy, resource sizing, cron, and preview posture are applied from git-backed configuration where those surfaces are supported. The dashboard reads and explains the result rather than offering an unguarded second writer.
There are deliberate exceptions. Secret values remain off-repo. GitHub connection state is an external authorization. Custom domains and managed services have stateful lifecycle concerns. Destructive managed-service removal is reviewed and gated rather than inferred as ordinary config cleanup.
The rule is enforced as product architecture, not only documentation. floo maintains a registry of customer-facing configuration surfaces and tests that new mutation routes are classified. A new dual-write path is treated as a drift bug.
This restraint matters for agents. They can inspect one proposed system, change it through one reviewable artifact, and rely on deployment to execute that intent. When the platform needs a different authority for secrets or irreversible state, it names the exception instead of hiding it behind precedence.
Configuration in git is not valuable because text files are fashionable. It is valuable because software teams need one durable answer to “what are we trying to run?” When agents can change systems quickly, that answer needs to remain reviewable.