Architecture overview
The Secrets Blueprint keeps the secrets your people manage, such as third-party API keys and OAuth client secrets, in one Git repository, encrypted with SOPS under a separate KMS key for each stage. When a change merges, a GitHub Actions workflow decrypts the files and writes each value as a SecureString parameter in SSM Parameter Store in the matching workload account, where applications read it.
How it works
- An engineer edits a stage's file with SOPS. SOPS encrypts every value with that stage's KMS key before the file is committed, so Git only ever holds ciphertext.
- A pull request runs a check for each stage: it confirms no value is still a template placeholder and lists the parameters the change would write.
- Review follows the stage. Any developer can approve sandbox and dev files; staging and prod files need a platform lead or an infrastructure admin.
- On merge, the sync workflow signs in to AWS through GitHub OIDC with no stored keys, decrypts the files and writes each value to SSM Parameter Store in the stage's own account.
- Workloads read the parameters at run time. In the Web App Blueprint, the External Secrets Operator turns them into Kubernetes Secrets.
The parts
| Part | What it is | Where it comes from |
|---|---|---|
| Secrets repository | One folder per stage, one encrypted YAML file per application, two workflows | The Secrets Blueprint |
| SOPS keys | Four KMS keys in the security account: sandbox, dev, staging, prod | The AWS Baseline |
| Syncer role | The only identity the workflows use, trusted for this one repository through OIDC | The AWS Baseline |
| Parameter Store | SecureString parameters in each plat account, under one path convention | Written by the sync |
| Consumers | The External Secrets Operator and any workload with read access to its stage prefix | The workloads |
The Baseline creates the keys and the syncer role; the blueprint brings the repository, the scripts and the workflows that use them. Read the AWS Baseline overview for the accounts these pieces live in.
Who can touch which secrets
Access is enforced by AWS, not only by GitHub. The key policy on each stage's key decides who can decrypt that stage's file:
| Who | sandbox and dev | staging and prod |
|---|---|---|
| Platform leads and DevOps leads | Read and write | Read and write |
| Engineers and developers | Read and write | None |
| The sync workflow | Decrypt only | Decrypt only |
A developer with write access to the repository still cannot read or change a production secret, because AWS KMS refuses the request. This is least privilege applied at the key.
Design choices
- Git is the record. Every change to a secret is a reviewed commit with an author, a date and an approver. Nothing is edited by hand in the console.
- One key per stage. Splitting by stage turns "who may see production secrets" into a key policy, checked on every decrypt.
- Parameter Store is what workloads read. Applications never read the Git repository; each account holds only its own stage's values.
- No long-lived credentials. Both workflows authenticate through OIDC and hold temporary credentials for the length of a job.
- Each stage stays in its account. The sync runs one job per stage, and each job writes only into that stage's account.
Where to go next
What you receive lists the repository contents and the Baseline pieces the blueprint relies on. Versions lists the pinned tools and actions.