Skip to content

sops-aws-sync operator documentation

sops-aws-sync is a Go command-line tool paired with a supply-chain-verified Node 24 GitHub Action. It reconciles the SOPS-encrypted .sops.json, .sops.yaml, and .sops.yml documents committed at one exact Git commit into an explicitly owned namespace in AWS Secrets Manager, issuing create, update, restore, and scheduled-delete operations so that AWS matches what Git holds. plan is read-only and reports what would change; sync mutates and then always verifies that the scope converged.

The one sentence that governs everything else: the committed Git revision is the desired state — you change AWS by committing and pushing those documents, never by editing secrets directly. About the reconciliation model explains why.

Read before you run sync

Five invariants an operator must hold. Each is a pointer; the linked page owns the full explanation.

  • Commit is the source of truth. sync acts on the committed revision, not your working tree, index, or unpushed changes. → reconciliation model
  • Scope inputs are an identity, not a setting. Changing repository-id, source-root, or secret-prefix mints a new scope that owns nothing prior and silently abandons the old secrets. → ownership and scope
  • Emptying the source tree does not mass-delete. A desired state with no files and pending deletions is refused unless you explicitly authorize it. → decommission a scope
  • One writer per scope. AWS offers no cross-secret transaction, so correctness depends on exactly one active sync per scope. → consistency and recovery
  • Not everything in a source document is secret. SOPS encrypts values, not keys, paths, or metadata; those are plaintext in Git. → security and trust

Find your way

What this tool is not

  • Not a secret editor. It writes only what Git holds and reconciles AWS toward it. → reconciliation model
  • Not an AWS authenticator. Bring credentials through the standard AWS SDK chain; the tool accepts no credential inputs. → grant AWS access
  • Not a manager of special secrets. It refuses secrets that are under rotation, replicated, or AWS service-owned rather than touching them. → ownership and scope
  • No force delete. Every deletion is a scheduled deletion inside a recovery window. → reconciliation model
  • Three SOPS encodings, one stored form. It reads .sops.json, .sops.yaml, and .sops.yml documents, stores every one as canonical JSON, and ignores every other file. → reconciliation reference
  • Linux and macOS only, on amd64 and arm64. → configuration reference

Elsewhere

  • The repository README has the copy-paste Action snippet and build-from-source instructions.
  • SECURITY.md covers private vulnerability reporting.

These pages serve operators who deploy and run the tool. Contributor and release-pipeline internals are out of scope.