Repository navigation
Apply One Naming Convention to Every Env and Secret File, Host-Side Files Included #3503
Description
Summary
Env and secret file names follow no single pattern across the fleet today, mixing underscores, dots, and dashes. The maintainer decided that every env and secret file a fleet repository names follows one convention, wherever the file lives. That includes a tracked template, a host-side file the repository's docs or scripts name (an ENV_FILE path, a compose env_file), and a secret file mounted into a container.
CODESTYLE.md "Script and Utility File Names" says only "Env and secret files | lowercase snake_case stem". It says nothing about host-side files or a multi-field stem. ptr727/Blog's resync for its issue 540 surfaced the gap, because Blog's host-side env files use a dotted multi-field stem.
The Rule
- Scope. Every env and secret file a repository names, tracked or not.
- Fields are joined by
_, and each field keeps its own valid form. A host name field stays verbatim, hyphens included:<project>_web-01_prod.env, never<project>_web_01_prod.envor<project>.web-01.prod.env. - The separator is unambiguous. A DNS host name can carry
-and never_, so every_in the stem is a separator, and the name splits back into its fields. - Lowercase. No dot except the extension. Start and end with a letter or digit. A secret with no extension takes the same form, as
db_root_passworddoes now. - Variable names convert separately. Where a field becomes an env variable or CI secret name, which allow only
A-Z,0-9, and_, the hyphen becomes_there, as inPROJECT_WEB_01_PROD_TOKEN, and never in the file name. The UPPER_SNAKE_CASE row for variable names is unchanged. - Limits that come from consumers. A name used as a Docker secret stays within 64 characters. A name that maps to a variable or CI secret does not start with a digit.
- Tool-fixed names are exempt.
.env,.env.local, and.env.productionstay under the existing "externally fixed names" bullet. - Script file names are unchanged. Python stays snake_case, and shell, PowerShell, and batch stay hyphenated.
The research behind each limit, with its source per consumer, is in this comment.
Plan
- Hub rule, one pull request. Write the rule above into
CODESTYLE.md"Script and Utility File Names", the row and a bullet under the table. - A check where one is mechanical. Tracked env and secret file names are a path check in the hub's gate tooling. A host-side name is checkable only where a repository's docs or scripts spell it out, so the audit reads those references rather than the hosts.
- Audit and per-repository resync.
AUDIT.mdgains the item. Each repository's resync renames its tracked files and updates the docs and scripts that name the others. Renaming a file on a maintainer host is the maintainer's step, listed in that repository's resync pull request rather than performed by an agent.
Done When
CODESTYLE.md states the rule, the gate checks tracked names, and AUDIT.md carries the item. Each fleet repository's own rename is tracked in its resync rather than here.
🤖 Generated with Claude Code
Activity
ptr727 commentedon Oct 26, 2026
Decision
The maintainer answered at the round-60 close of #2361. Env and secret file names follow no single pattern today, mixing underscores, dots, and dashes. The maintainer wants one consistent convention for every file and env name in every fleet repository, and left the rollout design to the implementing session.
Read as it applies here, the row reaches every env and secret file a repository names, wherever the file lives. That covers a tracked template, a host-side file the repository's docs or scripts name (an
ENV_FILEpath, a composeenv_file), and a CI secret's file form. Neither option above matches exactly. The answer is option 2's scope with a single stem form.Plan
CODESTYLE.md"Script and Utility File Names"). The env and secret row states its scope: tracked or not, a file a repository names is covered. The whole stem before the extension is lowercase snake_case, so fields join with_. For example,<project>_<server>_<environment>.env, with a hyphen or a dot inside a field value, such as a hostname, also written as_. A file with no extension keeps the same stem form, asdb_root_passworddoes now. The env variable row (UPPER_SNAKE_CASE) is unchanged.AUDIT.mdgains the item, and each repository's resync renames its tracked files and updates the docs and scripts that name the others. Renaming the files on a maintainer host is the maintainer's step, listed in each repository's resync pull request rather than performed by an agent.Script file names keep their per-language rules, PEP 8 snake_case for Python and hyphenated for shell, PowerShell, and batch, since those are deliberate and the table already gives each type one rule. If "all file names" was meant to override that split too, say so here before step 1 starts.
The
decisionlabel is removed, and this issue stays open as the work.ptr727 commentedon Oct 26, 2026
Correction and research, agreed with the maintainer
Correction to plan step 1 above. The plan said a hyphen or a dot inside a field value is also written as
_. That is withdrawn. The maintainer has removed underscores from DNS names, since a host name may carry-and never_, and agreed the rule below:_separates fields, and each field keeps its own valid form. A host name field stays verbatim, hyphens included:<project>_web-01_prod.env, never<project>_web_01_prod.env._, so an_in the stem is always a separator, and the name splits back into its fields.A-Z,0-9, and_, the hyphen becomes_there, as inPROJECT_WEB_01_PROD_TOKEN, and never in the file name.Research: what each consumer accepts
_, not starting with a digit^[a-zA-Z0-9]+(?:[a-zA-Z0-9-_.]*[a-zA-Z0-9])?$, at most 64 characterscontrolapi/common.godb_password.txtanddb_root_password, mounted at/run/secrets/<name>env_file/--env-file_only. No leading digit, and noGITHUB_prefixLoadCredential=-,_, or.. A Secret object's own name is a DNS subdomain and cannot carry_run-parts,/etc/cron.d_, and-only. A dotted name is silently skipped<project>_web-01_prod.envpasses every row. The edge rules each come from a row: start and end alphanumeric and stay within 64 characters (Docker), and no leading digit where a name maps to a variable or CI secret (POSIX, GitHub). Tool-fixed names such as.env,.env.local, and.env.productionstay under the existing "externally fixed names" exemption.[-]Say Whether the Env and Secret File Naming Row Reaches Host-Side Files[/-][+]Apply One Naming Convention to Every Env and Secret File, Host-Side Files Included[/+]ptr727 commentedon Oct 26, 2026
Host field answer
The maintainer answered while #3506 was open. A local review asked how a fully qualified host name is written in a field, since "each field keeps its own valid form" and "no dot but the extension" disagreed for one.
A host field is a short name, either the host's first DNS label (
web-01) or a logical role name (vps-staging), and never the fully qualified name. The domain distinguishes nothing across the fleet. A dotted name is skipped byrun-partsandcron.d, it makes the extension ambiguous, and it uses up Docker's 64-character secret limit. #3506 writes this intoCODESTYLE.md, and the check already rejects the dots.Name a Host Field by Its Short Name, Never Its FQDN
Give a Host Field the DNS Label Form, Role Names Included
Scope the Hyphen to a Host Field and Name the Check's Dot Gap
Name the Tool-Fixed Env Exemption in the Runtime Secrets Assert
Apply One Naming Convention to Every Env and Secret File (#3506)
Keep the Tool-Fixed Env Exemption Out of a Secrets Directory (#3508)
Promote the Env and Secret File Naming Rule to Main (#3507)