Home

Keyseal

Keyseal is a CLI tool for managing encrypted secrets in Git repositories. It provides a workflow layer over SOPS and age, giving you logical names, structured validation, multi-format rendering, and health checks - without replacing the underlying encryption.

If you already use SOPS directly, Keyseal adds:

• A naming convention that maps production/platform/app to production/platform/app.enc.yaml
• Structured secret documents with validation (kind: env, required fields, key format rules)
• Git-aware status, diff, history, commit, and rollback flows for the encrypted files already in the repo
• updatekeys - sync SOPS recipients from .sops.yaml across one or more encrypted files
• render - decrypt one or more secrets and write a merged dotenv/JSON/YAML file in one step
• exec - inject secrets as environment variables into a subprocess without writing files
• doctor - pre-flight checks that catch placeholder recipients, plaintext files at encrypted paths, SOPS misconfiguration, and more
• verify - strict CI checks that fail on doctor warnings as well as failures

What it is not

Keyseal is not a secret server. It does not manage access, audit logs, dynamic credentials, or secret rotation. It does not implement encryption itself. Keyseal uses the official SOPS Go decrypt library for read-only decryption in render, exec, and validation paths. The external SOPS binary is still required for commands that create, edit, or rotate encrypted files. It is not a replacement for Vault, AWS Secrets Manager, or similar systems.

It is a structured, opinionated workflow for teams that keep encrypted secrets in Git and need something more reliable than raw SOPS invocations.

How it fits

Git repo  →  keyseal.yaml  →  Keyseal workflow  →  SOPS-compatible crypto  →  age keys
                                    ↓
                            .enc.yaml files (ciphertext in repo)
                                    ↓
                            keyseal render / keyseal exec
                                    ↓
                          dotenv / JSON / YAML / subprocess env

Your encrypted files live in the repository. Keyseal knows how to find them (by logical name), how to validate their structure (via schema), and how to produce usable output from them. Read-only decrypt uses the SOPS Go library; mutating encryption/edit/updatekeys operations still use the external SOPS CLI.

Git is also the source of truth for change review and rollback. status, diff, and history stay focused on Keyseal-managed files, commit stages only those files, and rollback restores one encrypted file from a previous Git commit.

Current status

Keyseal is production-ready for Barkway's Git-backed SOPS secret workflow. The v1 keyseal.yaml configuration contract and kind: env secret document shape are stable. The profiles configuration section is parsed and validated but not yet executed by any command. Only kind: env is supported.

Navigation

Where to start
Installation	Prerequisites, build from source, release binaries
Quick Start	End-to-end example from init to render
Concepts	Mental model, how the pieces fit

Reference
Configuration Reference	keyseal.yaml field-by-field
Command Reference	Every command, every flag
Secret File Format	Document schema, validation rules
Repository Layout	Expected directory structure

Operations
Doctor	Health checks: what they test and how to fix failures
Templates	Built-in starter templates
Troubleshooting	Common problems and fixes
Security Notes	What Keyseal protects (and does not protect)

Development
Build and Release	Makefile, cross-platform dist, release workflow
Contributing	Project layout, tests, how to contribute
FAQ	Common questions