Conventions

Repo layout

bree-z-ansible/
├── ansible.cfg                  → vault_password_file = bin/ansible-vault-pass.sh
├── bin/
│   └── ansible-vault-pass.sh    → reads from macOS Keychain
├── inventories/release/
│   ├── group_vars/all/
│   │   ├── main.yml             → public vars, references vault_*
│   │   └── vault.yml            → ansible-vault encrypted secrets
│   ├── host_vars/<host>.yml
│   └── hosts.yml
├── playbooks/
│   ├── local/                   → $HOME-touching, dev only
│   ├── ci/                      → cloud-only, GH Actions friendly
│   ├── codedoc.yml              → shared
│   ├── ping.yml
│   └── site.yml
├── roles/
│   ├── obsidian-vault/          → vault structure, templates, Bases
│   └── codedoc/                 → per-app reference docs into 80-Docs/
├── docs/                        → this site
├── mkdocs.yml
└── .github/workflows/
    ├── validate.yml             → PR/push gate
    └── pages.yml                → builds + deploys this site

Vault password handling

Where	How
Local laptop	bin/ansible-vault-pass.sh → macOS Keychain (security find-generic-password -a ansible-vault -s bree-z-ansible -w)
GitHub Actions	secrets.ANSIBLE_VAULT_PASSWORD on the release environment, written to a tmpfile via ANSIBLE_VAULT_PASSWORD_FILE env var (overrides ansible.cfg)

Provisioning a new dev machine

security add-generic-password -a ansible-vault -s bree-z-ansible -w '<paste vault pw>'

Get the password from another team member or from the ANSIBLE_VAULT_PASSWORD secret value (only visible at create time).

Secret naming

• Encrypted vars in vault.yml use vault_* prefix.
• Adjacent public vars in main.yml reference them under their public name:

  obsidian_rest_token: "{{ vault_obsidian_rest_token }}"
  

• Roles never see the vault_ prefix.

Adding secrets

1. Decrypt: ansible-vault edit inventories/release/group_vars/all/vault.yml
2. Add a vault_<name>: key.
3. Wire a public alias in inventories/release/group_vars/all/main.yml.
4. If CI needs it, add the same value to the release GitHub environment.

Adding a runnable workflow

See Actions → Adding a workflow.