Alcala Chronicle

secretsjson

đź“… October 29, 2026đź“– Verified Publication
SecretsJSON: The Ultimate Playbook for Secure Secret Management

SecretsJSON: The Ultimate Playbook for Secure Secret Management

Key Takeaways

  • SecretsJSON is a lightweight, JSON‑based format for storing application secrets in a structured, version‑controlled way.
  • It integrates seamlessly with CI/CD pipelines, container orchestration, and cloud secret managers.
  • Follow the checklist below to create, secure, and rotate secrets.json files.
  • Compare SecretsJSON with other solutions to choose the right tool for your stack.
  • Answer common questions in the FAQ section to avoid pitfalls.

What Is SecretsJSON?

SecretsJSON is a conventionally structured JSON file that holds sensitive data—API keys, database credentials, certificates, and more. Unlike plain .env files, it supports nested objects, comments (via /* */ or //), and can be encrypted with tools like sops or age for added security.

Typical Structure

{
  "database": {
    "user": "db_user",
    "password": "••••••••"
  },
  "apiKeys": {
    "stripe": "sk_test_12345",
    "aws": "AKIAxxxxxx"
  }
}

Why Use SecretsJSON?

  • Version Control Friendly: JSON is machine‑readable and works well with Git, enabling diff and merge tracking.
  • Language Agnostic: Any language can parse JSON without additional dependencies.
  • Encryption Ready: Pair with sops or age to encrypt the file while keeping it in source control.
  • Structured: Nested objects reduce key collisions and improve readability.

Creating a Secure SecretsJSON File

Follow this step‑by‑step playbook to ensure your secrets.json is safe from accidental exposure.

Checklist: Initial Setup

  • âś“ Create a secrets.json file in a dedicated secrets/ directory.
  • âś“ Add a .gitignore rule to exclude secrets/*.json from commits.
  • âś“ Encrypt the file using sops or age before committing.
  • âś“ Store the encryption key in a secure key management service (KMS) or hardware security module (HSM).
  • âś“ Add an encryption.md note describing how to decrypt and rotate the file.

Checklist: Runtime Access

  • âś“ Decrypt secrets.json at container start or CI job using the same encryption tool.
  • âś“ Load the JSON into environment variables or a secret injection library.
  • âś“ Use the secrets.json only for short‑lived operations; purge from memory after use.
  • âś“ Validate JSON schema on deployment to catch missing or malformed secrets.
  • âś“ Log only non‑secret metadata (e.g., key names) to avoid accidental leaks.

Checklist: Secret Rotation

  • âś“ Schedule automated rotation scripts (e.g., via cron or GitHub Actions).
  • âś“ Update the secrets.json with new values and re‑encrypt.
  • âś“ Deploy the updated file to all environments (dev, staging, prod).
  • âś“ Verify application health after rotation.
  • âś“ Revoke old secrets in external systems (databases, third‑party APIs).

Integration with CI/CD and Cloud Secret Managers

  • GitHub Actions: Use actions/setup-sops to decrypt and inject secrets into workflow steps.
  • GitLab CI: Store encrypted secrets in CI_VARIABLES and decrypt on runners.
  • AWS: Use AWS Secrets Manager to retrieve secrets at runtime; store the manager ARN in secrets.json.
  • GCP: Store a reference to Secret Manager in secrets.json and pull via gcloud secrets.
  • Azure: Use Azure Key Vault URIs in secrets.json and fetch via SDK.

Comparison: SecretsJSON vs. Other Secret Stores

Feature SecretsJSON Vault AWS Secrets Manager GCP Secret Manager Azure Key Vault
Format JSON (encrypted) KV store (JSON) JSON API JSON API JSON API
Version Control Yes (encrypted) No (runtime) No (runtime) No (runtime) No (runtime)
Encryption Optional via sops/age Built‑in Built‑in Built‑in Built‑in
Granular Access Control File‑based ACLs Policies & roles IAM policies IAM policies RBAC & IAM
Ease of Use Simple JSON + tool CLI + SDK CLI + SDK CLI + SDK CLI + SDK
Cost Free (self‑hosted) Paid (self‑hosted) Pay‑as‑you‑go Pay‑as‑you‑go Pay‑as‑you‑go

FAQs

1. Can secrets.json be stored in the same repo as source code?

Yes, but it must be