chemenu/docs/how-to/use-1password-for-settings.md

Use 1Password for settings

Keep secrets and private values (host names, internal URLs) out of the working tree by storing them in 1Password and leaving only an op:// reference in the settings. The committed wikitool.json then works on every machine signed in to the same 1Password account, and in CI. What the files and references are: configuration reference. Why, and what this does not protect against: configuration-tiers.md.

On a desktop

1. Install the 1Password CLI (op) and turn on its integration with the 1Password desktop app, so op asks the app instead of keeping a session of its own. 1Password's own documentation describes both steps for each platform.

2. Run the preflight again - tools/preflight.sh, or in PowerShell 7 pwsh -NoProfile -ExecutionPolicy Bypass -File tools/preflight.ps1. It records op in .wikitool-tools.json and shows it as OK; without op the line reads ABSENT, which is no problem until a reference needs it.

3. Make a vault of its own for this instance, and put each secret or private value into an item there. A vault of its own limits what an unlocked op can reach.

4. Copy each value's reference (op://<vault>/<item>/<field>) - the 1Password app offers it on the field - and tell the agent which setting it belongs to:

   Set <section>.<field> to the reference op://<vault>/<item>/<field>.

   The agent runs tools/wikitool config set <section>.<field> --ref op://<vault>/<item>/<field>, which writes the reference into wikitool.json. Never paste the value itself into the chat: the agent should never see it.

5. Check it: tools/wikitool doctor. The settings-secrets line says how many references resolve. When the desktop app asks to approve access, that is the prompt doing its job - a locked app makes the line a WARN, and a command that needs the value stops with exit 42 until you unlock it.

Without 1Password

A reference by name works the same way without op:

• set the reference: tools/wikitool config set <section>.<field> --ref <name>;
• put the value into WIKITOOL_SECRET_<NAME> (the name upper-cased) in the environment, or into the secrets file ~/.config/chemenu/<instance_id>/secrets.json as {"<name>": "<value>"}, readable by you only (chmod 600). The instance_id is in wikitool.json.

In CI

There are two ways, and which one fits depends on the form of the references:

• op itself, with a service-account token - for settings that hold op:// references. Install op in the job, run the preflight so it records it, and set OP_SERVICE_ACCOUNT_TOKEN; the references then resolve exactly as on a desktop.
• 1Password's action resolves the values first - for settings that hold references by name. 1password/load-secrets-action with a service-account token reads an op:// reference into a variable before wikitool starts; name the variable WIKITOOL_SECRET_<NAME> and use {"ref": "<name>"} in the settings. This repository's own CI does this, in .gitea/workflows/ci.yml. An op:// reference in the settings is not resolved this way: it still needs op.

Give the service account access to the instance's own vault only.