Sync .env.example from master to every repo
Sync .env.example from master to every repo
One-page procedure to add / remove / rename a family-wide env var
across every repo in the family. Implements
rules/security/env-example-synced-from-master.md
and the Track A half of
security/env-and-secrets-single-source.md.
Prerequisites
- Working tree of master
chirag127/orizis clean (or has only the intendedtemplates/.env.examplechange in flight). - Every submodule is initialised (
git submodule update --init --recursive). - The new key (if adding) has a value already written at
Doppler — the runbook
set-github-org-level-secrets.mdis run AFTER this one to push the value into thechirag127-org-level GH Actions secrets.
Steps
1. Edit the master template
Open on
master and add / remove / rename the key. One KEY= line per
addition. No comments. Order is append-at-end for additions; for
renames, edit the existing line in place.
# example: adding WAKATIME_API_KEY for the lifestream pipeline
$EDITOR templates/.env.example
2. Dry-run the sync
bash scripts/sync-env-example.sh --dry-run
Prints, for every submodule, the path it WOULD overwrite and the
diff. Confirm the list matches the family inventory (every site,
every package, oriz-omnipost, oriz-lifestream when present,
every extension and worker submodule).
3. Run the sync
bash scripts/sync-env-example.sh
The script:
- Resolves
MASTER="$REPO_ROOT/templates/.env.example". - Reads every submodule path from
.gitmodules. - For each submodule path (and the master repo itself's
.env.exampleat the root if you choose to keep one), copiesMASTERover the existing file, overwriting. - Prints a one-line summary per repo.
4. Commit + push each touched submodule
git submodule foreach is the safe loop. From master:
git submodule foreach --recursive '
if ! git diff --quiet -- .env.example; then
git add .env.example
git commit -m "chore: sync .env.example from master"
git push origin main
else
echo "no .env.example change in $sm_path"
fi
'
(Per rules/development/push-by-default.md,
push immediately after commit. No feature branches per
rules/development/one-branch-only.md.)
5. Bump the master pointers
git -C "$REPO_ROOT" status # confirms every touched submodule shows as a pointer bump
git add sites/* packages/* .gitmodules templates/.env.example
git commit -m "chore(env): add <KEY> to templates/.env.example + sync to every submodule"
git push origin main
For more detail on the pointer-bump mechanic, see
bump-submodule-pointer.md.
6. Verify
bash scripts/verify-env-example-sync.sh
The script diffs every submodule's .env.example against
templates/.env.example. Exits 0 on full match, non-zero with a
list of drifting paths otherwise. Verify must exit 0 before this
runbook is considered complete.
7. (If adding a key) push the value to org-level GH secrets
The .env.example change adds the key surface; the value still
needs to land at the chirag127-org-level GitHub Actions secrets
list. Run
set-github-org-level-secrets.md
for the new key.
8. Update the log
Append a one-liner to
:- 2026-06-20 — added <KEY> to templates/.env.example + synced to every repo + pushed value to chirag127 org secrets
Don'ts
- Don't hand-edit a child repo's
.env.example. It will be overwritten on the next sync, and the CI drift check will fail the PR until you re-sync. - Don't skip
verify-env-example-sync.sh. Master CI runs the same script — a green local run prevents a red PR. - Don't combine multiple key changes in one commit-and-push if any of them touches a key the other repos' CI immediately references — it can stampede if the org-secret value isn't in place yet. Add the value to Doppler + GH org first, then sync the example.