#22765: docs(gateway): add secrets providers guide (env/keyring/1Password/cloud)
docs
gateway
size: XS
Cluster:
Model Authentication Enhancements
## Summary
Adds a focused, user-facing secrets providers documentation page to unblock Issue #17311 item 6 (docs).
### What this PR adds
- New Gateway docs page: `docs/gateway/secrets-providers.md`
- `${env:NAME}` provider usage
- `${keyring:NAME}` provider usage
- macOS `security` examples for keychain storage/read/unlock
- 1Password `op://vault/item/field` usage
- CI/service account notes for 1Password
- concise cloud provider setup links (GCP/AWS/Azure/Vault)
- plaintext-to-provider migration playbook
- troubleshooting + security notes (missing vars, keychain access, rotation)
- Navigation + cross-links
- Added page to `docs/docs.json` (Gateway & Ops → Configuration and operations)
- Linked from `docs/gateway/configuration.md`
- Linked from `docs/gateway/index.md`
## Scope
- Docs-only
- No runtime/code behavior changes
## Validation
- `pnpm format:docs`
- `pnpm check:docs`
Closes #17311
<!-- greptile_comment -->
<h3>Greptile Summary</h3>
Adds a new `docs/gateway/secrets-providers.md` page documenting the currently implemented `${VAR_NAME}` environment variable substitution in config values. The page includes a migration playbook for moving from plaintext secrets to env var references, troubleshooting guidance, security notes, and a roadmap note clarifying that provider-specific backends (keyring, 1Password, cloud secret managers) are not yet implemented. Navigation and cross-links are added in `docs.json`, `configuration.md`, and `index.md`.
- The second commit (40339d2d) corrected the initial version to accurately reflect only the implemented `${VAR_NAME}` syntax, removing previously documented but unimplemented `${env:NAME}`, `${keyring:NAME}`, and `op://` syntax
- Documentation is consistent with the actual implementation in `src/config/env-substitution.ts`
- No runtime or code changes; docs-only PR
<h3>Confidence Score: 5/5</h3>
- This docs-only PR is safe to merge with no risk to runtime behavior.
- This is a documentation-only change with no code modifications. The corrected version (second commit) accurately reflects the implemented `${VAR_NAME}` env substitution behavior, as verified against `src/config/env-substitution.ts`. Unimplemented features are explicitly called out as roadmap items. Navigation links and cross-references are valid.
- No files require special attention.
<sub>Last reviewed commit: 40339d2</sub>
<!-- greptile_other_comments_section -->
<!-- /greptile_comment -->
Most Similar PRs
#16663: feat: GCP Secret Manager integration for external secrets management
by amor71 · 2026-02-15
74.2%
#22858: Gateway: add eager secrets runtime snapshot activation
by joshavant · 2026-02-21
72.9%
#19307: docs: add Google (Gemini) provider documentation
by manueltarouca · 2026-02-17
72.4%
#16961: docs: warn against storing secrets in injected workspace files
by soumikbhatta · 2026-02-15
72.1%
#21173: fix(config): support envFiles option in resolveConfigEnvVars for ga...
by Mellowambience · 2026-02-19
71.6%
#17098: docs: add xCloud hosting guide
by mosabbirrakib · 2026-02-15
71.5%
#12834: docs(gateway): clarify there is no standalone clawrouter binary
by JBrady · 2026-02-09
71.4%
#16362: Update session-pruning.md - updated agents.defaults config std
by elliottb · 2026-02-14
71.1%
#23096: feat(secrets): add Bitwarden/Vaultwarden secret provider
by ihsanmokhlisse · 2026-02-22
70.7%
#22632: docs: fix redirects and small reorg
by gianpaj · 2026-02-21
70.7%