5.2 KiB
Generated 2026-05-12 at base-sha d6708eca4236. Type: concept. 10 sources.
Architecture Decision Records — Index
devops-lib's ADRs capture the "why" behind the library's design — the decisions that would otherwise be tribal knowledge. All 9 ADRs were retroactively documented on 2026-05-12 from codebase analysis and developer interviews. All are Status: Accepted and assessed as still appropriate.
Why ADRs matter here
devops-lib has several decisions whose rationale is non-obvious: why does the whitelist get re-cloned on every build (not cached)? Why is the 4-step ArgoCD sequence non-interchangeable? Why must all builds go through Ringmaster? Without ADRs, engineers modifying the library break load-bearing constraints without realising it.
Decision inventory
| # | Decision | Category | Key insight |
|---|---|---|---|
| ADR-0001 | Single shared library for all services | PATTERN | Policy enforcement must be uniform; per-team Jenkinsfiles produce drift |
| ADR-0002 | Branch name as sole environment selector | PATTERN | Branch IS the environment contract; per-service env config creates misconfiguration risk |
| ADR-0003 | Policy exceptions in Meesho/whitelists repo | PATTERN | Service teams cannot self-grant bypasses; all exceptions require DevOps review |
| ADR-0004 | Fresh whitelist clone per build | PATTERN | Policy changes must take effect on the very next build without a library release |
| ADR-0005 | Config-only change detection — skip build | PATTERN | No source change → no new binary; reuse the latest image tag from GAR |
| ADR-0006 | Ringmaster mandatory trigger gate | PATTERN | Every deployment must be tracked; direct Jenkins triggers bypass Ringmaster's ledger |
| ADR-0007 | GitOps via 4-step ArgoCD sync sequence | INFRA | Steps 2 and 4 are non-interchangeable; swapping them causes silent sync failures |
| ADR-0008 | Canary mandatory for Tier-1 (sp0/up0) in prd | RELIABILITY | Incident-driven: non-canary prd deploys for critical services caused outages |
| ADR-0009 | JVM heap auto-derived from pod memory_request | RELIABILITY | OOM incident remediation: auto-calc prevents under-sizing; jvm_memory_override: true escapes it |
Decisions that are load-bearing constraints
These three decisions have "never change without understanding this" consequences:
ADR-0004 (fresh whitelist clone) — getWhitelistedRepos in src/com/meesho/utilities/constructParam.groovy:getWhitelistedRepos re-clones Meesho/whitelists on every call by design. Never add a cache — it would prevent immediate policy enforcement.
ADR-0006 (Ringmaster gate) — The string "ringmaster-bot" at vars/eksCICD.groovy:call is the sole routing signal between Ringmaster and Turbo-Turtle callbacks. Never rename it without coordinating with both teams.
ADR-0007 (4-step ArgoCD sequence) — Steps 2 (refresh_app_of_apps) and 4 (refresh_and_sync) in src/com/meesho/stages/deployArgoCD.groovy:run are non-interchangeable. For a first-deploy, step 2 must create the Application object before step 4 can sync it.
When to read which ADR
- Debugging a build not triggering: ADR-0006 (Ringmaster gate)
- Debugging a deploy that failed on ArgoCD sync: ADR-0007 (4-step sequence)
- Understanding why policy changes take effect immediately: ADR-0004 (fresh clone)
- Service team asking for a sonar bypass: ADR-0003 (whitelist repo)
- Canary enforcement failing for a prd deploy: ADR-0008
- OOM in a Java service pod: ADR-0009
Related concepts
- Whitelist system — runtime whitelist enforcement (ADR-0003, ADR-0004)
- ArgoCD sync — step-by-step walkthrough (ADR-0007)
- Ringmaster integration — callback flow (ADR-0006)
- Environment mapping — branch → environment (ADR-0002)