Secrets providers
Secrets providers resolve ref URIs into runtime values for Loom jobs. Each provider handles a specific URI scheme. This page helps you choose a provider and find the setup documentation.
Choosing a provider
| Need | Recommended provider | Why |
|---|---|---|
| Quick migration from existing env-based secret delivery | Environment (env://) | Zero setup — reads values already in the host environment |
| Local encrypted storage without external services | KeePass (keepass://) | Offline .kdbx vaults with alias-driven configuration |
| Team/shared vault with access control and audit logging | 1Password (op://) | Centralized vaults via service account tokens and the 1Password Go SDK |
Provider matrix
| Provider | URI scheme | Auth requirement | Status |
|---|---|---|---|
| Environment passthrough | env://<VAR_NAME> | None (reads host process env) | Implemented |
| KeePass | keepass://<alias>/<db>#<path>:<field> | Alias-based runtime config (LOOM_KEEPASS_DB_<ALIAS>_*) | Implemented |
| 1Password | op://<vault>/<item>/<field> | OP_SERVICE_ACCOUNT_TOKEN in runtime env | Implemented |
Provider contract
All providers follow the same behavioral contract:
- Resolve only declared job secrets — providers receive only the refs declared on the current job, not the full workflow.
- In-memory value flow — resolved bytes are returned to the injection pipeline and never written to intermediate files, logs, or artifacts.
- Deterministic error codes — failures produce
SECRETS_*error codes with non-sensitive diagnostic messages. - Redaction participation — resolved values are registered with the redaction engine before any output is written.
- Fail closed — invalid or unavailable auth produces a hard failure, never a silent fallback.
Environment (env://)
The environment provider reads a value from the Loom runtime process environment. No additional setup or auth is required.
URI format:
env://<VARIABLE_NAME>
Example:
deploy:
secrets:
DEPLOY_TOKEN:
ref: env://DEPLOY_TOKEN_VALUE
When to use: Migrating from existing CI systems that inject secrets as environment variables, or wrapping secrets already managed by your runner infrastructure.
Limitation: The host environment may be broadly scoped. Values are visible to child processes and unrelated tooling running in the same session.
KeePass (keepass://)
The KeePass provider resolves secrets from local encrypted .kdbx databases using alias-driven runtime configuration.
URI format:
keepass://<database-alias>/<database-name>#<entry-path>:<field>
Setup and usage:
- Overview — URI format, resolution flow, and failure codes
- Install and setup — prerequisites and database configuration
- CLI commands — manage databases, entries, and fields
- Workflows — use KeePass secrets in workflow files
1Password (op://)
The 1Password provider resolves secrets from 1Password vaults using the Go SDK. No op CLI binary is required.
URI format:
op://<vault>/<item>/<field>
Setup and usage:
- Overview — URI format, resolution flow, and failure codes
- Install and setup — prerequisites, service account auth, and validation
- CLI commands — list vaults and items, create and rotate fields
Security considerations
Before enabling any provider in production workflows:
- Review the Secrets security page for the full threat model and provider-specific risk profiles.
- Follow the operational guardrails for production configuration.
- See the Secrets overview for injection modes, error codes, and scoping rules.