← Back to PRs

#22765: docs(gateway): add secrets providers guide (env/keyring/1Password/cloud)

by alexmelges open 2026-02-21 16:54 View on GitHub →
docs gateway size: XS
## 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