# ADR-010: Secrets Management Strategy

| Field        | Value          |
|---|---|
| **Status**       | `Accepted`     |
| **Date**         | 2026-05-19     |
| **Deciders**     | *Full Team*    |
| **Supersedes**   | –              |
| **Superseded by**| –              |

---

## Context

The system consists of multiple repositories and components (Spring Boot backend, AI/Retrieval
service, and frontend) deployed via GitHub Actions CI/CD pipelines. Each component requires
sensitive configuration values such as:

- Database credentials
- JWT signing secrets
- External API keys
- Service-to-service authentication tokens

This ADR defines the secrets management strategy **at the system level**, applying to all
repositories. Per-service implementation details (e.g. how each stack reads environment variables)
are documented in service-specific READMEs or ADRs.

Exposing sensitive values in source control introduces a high-risk security surface, including
credential leakage via Git history, accidental exposure in pull requests, and CI log artifacts
containing secrets. A consistent, enforceable strategy is required across local development,
CI/CD pipelines, and production environments.

## Decision Drivers

- No credentials must ever be stored in any repository
- Strategy must apply uniformly across all services regardless of tech stack
- Developer onboarding must remain straightforward
- Must be compatible with GitHub Actions-based CI/CD without additional infrastructure

## Considered Options

- **Option A** – GitHub Secrets + `.env` (untracked) + `.env.template` (tracked)
- **Option B** – Secrets stored in `application.yml` / config files per service
- **Option C** – Dedicated secret manager (HashiCorp Vault / AWS Secrets Manager)

## Decision

**Chosen option: Option A** – A hybrid approach using GitHub Secrets for CI/CD injection,
untracked local `.env` files for development, and a tracked `.env.template` as a configuration
contract shared across all repositories.

## Rationale

Option A provides the right balance of security and operational simplicity for the current
stage. GitHub Secrets are scoped per environment, injected only at workflow runtime, and never
persisted in build artifacts. The `.env` + `.env.template` pattern ensures local development
remains straightforward while the template file acts as a living contract that keeps all
developers and services aligned on required configuration. No additional infrastructure is
required.

Each service reads environment variables in an idiomatic way for its stack:

| Service       | Stack               | Env Resolution                          |
|---|---|---|
| Backend       | Spring Boot / Kotlin | `application.yml` variable placeholders |
| AI/Retrieval  | Python              | `os.environ` / `python-dotenv`          |
| Frontend      | React / TypeScript  | Build-time `VITE_*` / runtime config    |

## Pros and Cons of the Options

### Option A – GitHub Secrets + `.env` + `.env.template`

- ✅ No credentials stored in any repository
- ✅ Clear separation between local, CI, and production environments
- ✅ `.env.template` improves onboarding and acts as a cross-repo configuration contract
- ✅ Compatible with GitHub Actions without additional infrastructure
- ✅ Stack-agnostic — applies uniformly regardless of service language or framework
- ❌ Developers must manually manage local `.env` files
- ❌ Risk of local environments drifting if `.env` diverges from `.env.template`
- ❌ No centralised secret rotation mechanism at this stage

### Option B – Secrets in config files (`application.yml` / `.env` committed)

- ✅ Zero setup friction for developers
- ❌ High risk of credential leakage via Git history
- ❌ Violates baseline security practices
- ❌ Not compatible with CI/CD security requirements

### Option C – Dedicated Secret Manager (Vault / AWS Secrets Manager)

- ✅ Centralised rotation, auditing, and access control
- ✅ Strong production-grade secret lifecycle management
- ❌ Significant operational overhead and infrastructure complexity
- ❌ Requires deployment environment maturity not present at this stage
- ❌ Not justified for the current team size and project phase

## Consequences

**Positive:**
- No sensitive credentials are stored in version control across any repository
- Onboarding is straightforward via `.env.template` in every repo
- CI/CD pipelines remain simple — no external secret manager dependency

**Negative / Trade-offs:**
- No centralised secret rotation — secrets must be updated manually per GitHub environment
- Developer discipline required to avoid logging environment variables locally or in CI

**Follow-up actions:**
- Every repository must include `.env.template` and a `.gitignore` entry blocking `.env`
- CI pipelines must validate presence of required secrets before deployment steps
- Logging configurations in all services must redact environment variables

## Links