# 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](../reference/configuration.md#tiered-settings).
Why, and what this does not protect against: [configuration-tiers.md](../explanation/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 as `{"<name>": "<value>"}`: `~/.config/chemenu/<instance_id>/secrets.json`
  (`$XDG_CONFIG_HOME` instead of `~/.config` when it is set), readable by you only
  (`chmod 600`) - on Windows `%APPDATA%\chemenu\<instance_id>\secrets.json`. 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.