Encrypted secrets in Git is a design where secret values are committed as ciphertext, encrypted with a cloud-managed key, and synchronized into parameter storage when a change is merged. Nothing readable is ever in the repository. The permission to decrypt lives in the key policy, not in the version control system, which means write access to the code and access to the production secret become two separate decisions.
That separation is the whole idea, and it is worth stating in its strongest form: a developer with full write access to the repository still cannot read a production secret, because the decrypt call goes to the key service and the key service says no.
The shape of the design
#Four moving parts, and none of them is a server you run.
Encrypted files in the repository. One file per application per stage — sandbox, development, staging, production. Values are encrypted individually, so a diff still shows you which key changed even though it cannot show you the value. The file is otherwise ordinary source code: reviewed, versioned, branched, and subject to the same code ownership rules as everything else.
A key per stage, in the security account. Each stage has its own customer-managed encryption key, and the key policy names who may decrypt with it. This is the access control. It lives in an account most engineers have no administrative rights in, and it is applied by the cloud provider at the moment of the call.
A sync on merge. When a change is merged, a pipeline role decrypts the file and writes the values into parameter storage as encrypted strings. That role is the only identity that performs the write, and no human uses it interactively.
Delivery to workloads. Applications do not read the repository. They read parameter storage through their own workload identity — in Kubernetes, through an operator that projects parameters into the objects a pod consumes. The application never holds a long-lived credential to a secret store; it holds an identity, and the identity is what the policy grants.
Why repository access is not secret access
#The claim deserves its mechanism spelled out, because it sounds like a slogan.
When someone runs the decrypt, the ciphertext contains a reference to the key that encrypted it. The tooling calls the cloud key service and asks it to decrypt a small data key. That call is authenticated as whoever made it, and it is authorized by the key policy — a document in the security account that lists the principals allowed to decrypt with that key. A developer’s role is on that list for the development key. It is not on the list for the production key.
So the sequence is: clone succeeds, file opens, decrypt call goes out, refusal comes back. The developer holds a file they cannot read. And because the call was made, there is now a record of it in the audit trail — an access denial with a principal, a time and a key, which is one of the more useful signals a security team can have.
Three consequences follow that are easy to miss:
- Compromising the repository is not compromising production. A leaked personal access token, a malicious dependency in the build, a contractor who keeps their laptop: all of them yield ciphertext.
- The blast radius of a key is one stage. Key compromise is a serious incident, but it is a serious incident about one environment rather than all of them.
- The control is testable. You can prove the property by trying it, which is a better assurance than reading a policy document.
The separation-of-duties flow
#For non-production stages, the flow should be short: edit, review, merge. Friction there buys nothing and teaches people to route around the process.
For staging and production, five steps, each doing a distinct job:
- A lead writes the change. They can encrypt with the production key — writing is a different permission from reading, and in many setups the author does not need decrypt rights at all.
- A second code owner approves the pull request. Code ownership on the secrets path is what makes this automatic rather than remembered.
- An environment reviewer approves the deployment. This is a separate gate from the code review and usually a different person, which is the part that makes it separation of duties rather than two reviews.
- The syncer role writes the value. A pipeline identity, federated per job, with permission to decrypt and to write parameters and nothing else. No human holds it.
- A read-only role consumes it. The workload’s identity can read the parameter and decrypt it at read time; it cannot write.
A useful check on any secrets process: name the person who can change a production secret without anyone else being involved. If that name exists, the process has a gap, and it is the same gap regardless of which tool is underneath.
What you give up, honestly
#No design here is free. The comparison that matters is not “which is most secure” but “which capabilities do you actually need”.
| Encrypted files in Git | Managed secret storage alone | A vault cluster you run | CI provider’s secret store | |
|---|---|---|---|---|
| Where the value lives | Ciphertext in Git, plaintext only in parameter storage | Managed store | The cluster’s own storage | The CI system |
| Who can read production | Whoever the key policy names, which is testable | Whoever holds the read permission | Whoever the policy engine allows | Anyone who can edit a pipeline definition |
| Change control | A pull request with a diff, review and history | An API call, usually unreviewed | Policy-dependent; often an API call | An edit in a settings page |
| Rotation | A reviewed change; manual | Automatic for supported resource types | Dynamic credentials per request | Manual |
| Dynamic credentials | No | For supported databases | Yes, its core strength | No |
| Cross-cloud and on-premises | No | No | Yes | No |
| Infrastructure to operate | None | None | A highly available cluster with its own unseal, backup and upgrade story | None |
| Failure mode on outage | Values already in parameter storage keep serving | Store outage affects reads | Cluster outage can block workloads | Pipeline outage blocks deployments |
Read the last two rows together. A vault cluster is genuinely the most capable option on this list, and it is also a distributed system with an availability requirement equal to production, an unseal procedure, a backup story and an upgrade path. Teams who need dynamic credentials or a policy engine spanning clouds should pay that cost with open eyes. Teams whose actual requirement is “applications get their configuration secrets and changes are reviewed” are buying an operational burden for a capability they will not use.
The bottom-right cell is worth noting too, because it is where most real-world secret sprawl lives: secrets pasted into the CI provider’s settings, readable by anyone who can edit a pipeline, with no diff and no history. That is the status quo this design most often replaces, and the comparison is not close.
Rotation is a reviewed change, not a cron job
#This is the limitation to state plainly rather than bury: in this design, rotation is manual. There is no automated rotation loop. Changing a secret means rotating the value at its provider, updating the encrypted file, opening a pull request, getting it approved, merging, and confirming that the old value no longer works.
Three things make that acceptable in practice, and one thing makes it a genuine constraint.
It is acceptable because the procedure is written down and rehearsable, because the change is reviewed like any other and therefore visible, and because most configuration secrets do not benefit much from frequent scheduled rotation compared with the things that actually reduce risk — removing long-lived credentials, scoping permissions, and detecting misuse.
It is a genuine constraint because rotation you have to remember is rotation that slips. If your obligations require demonstrated rotation on a schedule, put the dates on a calendar with an owner, or use a managed rotation capability for the resource types that support it — database credentials being the obvious case. That is a sensible hybrid, not a contradiction.
One rule is absolute: a secret that was ever committed in plaintext must be rotated at its source. Git history is permanent, forks and clones are everywhere, and re-encrypting a value that was once readable changes nothing at all.
The other limits worth knowing
#- Key names are visible. Values are encrypted; the structure of the file is not. That is deliberate, because it is what makes diffs reviewable, and it does mean the names of your integrations are in the repository.
- The syncer role is a high-value target. It can decrypt and write. Federate it per job, scope it to one stage, and watch its usage — the same argument as removing long-lived credentials from CI entirely.
- Placeholders are a real failure mode. A file merged with a placeholder still in it produces a confusing outage. Fail the pull request on the pattern rather than trusting review to catch it.
- Plaintext still gets committed by accident. A pre-commit hook that detects private keys and obvious secret material is cheap and catches the common cases before they reach history.
- No dynamic secrets. Every value is static until someone changes it. If you need credentials that exist for an hour, this is the wrong layer.
What ships in the Secrets Blueprint
#The Secrets Blueprint — one of the BuiltForProd Blueprints — implements exactly this design on AWS: SOPS with AWS KMS encrypting files in Git, one file per application per stage across sandbox, development, staging and production, per-stage keys held in the security account, and a sync into SSM Parameter Store as encrypted strings on merge. External Secrets Operator delivers them into workloads. The five-step separation of duties above is the staging and production flow; a pull request check fails on any remaining placeholder. It ships with an incident playbook covering five scenarios, including plaintext committed to history and key compromise, and a seven-step rotation procedure.
The characteristic worth pointing at is what it does not add: no cluster, no new service to run, no additional availability dependency. It is a workflow and a key policy on top of services the foundation already has. The property underneath — that no person holds standing access to a production secret — belongs to the BuiltForProd Standard rather than to any one cloud, and the security page sets out where it sits among the other controls.
Where to start this week
#- Find the plaintext. Search your repositories and your CI configuration for the obvious patterns. Whatever you find must be rotated at the source, not deleted from a file.
- Name who can read production secrets today. If the list is “anyone with repository access” or “anyone who can edit a pipeline”, that is the gap.
- Split the keys by stage. One key per environment is the change that makes every other control in this design mean something.
- Put a second approval on the production path. A code owner on the secrets directory plus an environment reviewer is two settings and it is the whole separation of duties.
- Write the rotation procedure and put a date on it. Since it is not automated, it needs an owner and a calendar entry, and pretending otherwise is how it fails.
If you would rather inherit the whole flow than assemble it, the BuiltForProd Blueprints are deployed into your own accounts with the repositories handed over. And if the wider question is who can reach production at all rather than which values they can read, that is zero trust access for engineers.