CI BIBLIJA — v7¶

Sve što ti treba da ne pitaš "kako ko gdje zasto kuda" — na jednom mjestu, sa četiri različita ulaza, organizovano oko pitanja koja zaista imaš.

Verzija biblije: v7 — prati git rev-parse --short HEAD ovog fajla. Verzija projekta: vidi ci-state.json → pipeline.project_version Ažurirana: 2026-06-17 (regeneriše se kad god se ci/ mtime promijeni)

📖 Kako čitati ovu bibliu Ovo NIJE referenca po fajlovima (ci/coolify/CLAUDE.md, ci/verbs/CLAUDE.md...). To je već u repo-u i tamo i pripada. Ovdje je sadržaj presložen po pitanjima. Ako znaš ŠTA tražiš — koristi Indeks pitanja (§2). Ako znaš KO SI — koristi Indeks uloge (§1). Ako znaš O ČEMU je riječ — koristi Indeks sistema (§3). Ako nešto GORI — idi pravo na §4.

§1 · Indeks po ulozi — "JA SAM..."¶

Ako si...	Idi pravo na	Pročitaj i...
🆕 Novi član tima	`01-onboarding/`	30 minuta konteksta, redom
🛠️ Dev koji dodaje novi servis	`02-add-service/`	Checklist + šabloni za `services.json`
🛠️ Dev koji dodaje novog vendora	`02-add-service/03-add-vendor/`	`api/api.py` + `config.py` obaveze
🚀 Onaj ko radi release	`03-release/`	Oba sanctioned patterna, ne miješaj ih
🌙 Oncall 2am, nešto je puklo	`04-incidents/`	Triage stabla: build / deploy / lock / state
👀 Reviewer na PR-u	`05-review/`	Cross-product tabele, anti-patterns, "šta moraš vidjeti"
🧪 QA / tester	`06-test/`	Lokalni gate, Playwright, kako pokrenuti jedan servis
📦 Onaj ko diže verziju biblije	`07-meta/`	Kako se ovo regeneriše, kako se bump-uje

§2 · Indeks po pitanju — "PITANJE JE..."¶

Svaki red je link na JEDAN članak. Članak odgovara na JEDNO pitanje, ne više. Ako te zanima samo jedna stvar — ne moraš čitati susjedne.

Kako radi (mehanizam)¶

Zašto (obrazloženje + historijat)¶

Gdje da promijenim (mjesto + procedura)¶

Gdje se mijenja services.json polje X?
Gdje se mijenja ci-state.json polje X?
Gdje se dodaje novi ci/* env var? → docs/ci-env-vars.md
Gdje se dodaje novi Make target?
Gdje se dodaje novi schema $defs?

Šta ako ne radi (debug playbook)¶

Šta ako želim (procedura + guardrails)¶

Želim bump verzije sheme
Želim dodati novog vendora
Želim promijeniti deploy failure_policy
Želim lokalno pokrenuti CI
Želim deprecate stari env var (deprecation policy)

§3 · Indeks po sistemu — "SISTEM JE..."¶

Ako već znaš u kom sistemu je problem, idi ovdje.

02-systems/01-two-schemas.md — services.json vs ci-state.json, ko čita, ko piše, kada
02-systems/02-services-json-map.md — svako polje, sa primjerom i cross-ref na shemu
02-systems/03-ci-state-map.md — isto za state
02-systems/04-env-vars.md — CI_* / BITBUCKET_* / vendor prefiksi (vanjski link na docs/ci-env-vars.md)
02-systems/05-lock-overview.md — distributed lock: backend, F35/F38/F40, dvofazno
02-systems/07-fingerprint-gate.md — Expo fingerprint, tri backenda, per-platform
02-systems/08-sentry-stamp.md — Sentry release + bundle-id
02-systems/09-architecture-graphs.md — .arch/<subsystem>/graph.json, drift gate
02-systems/10-consumer-make.md — ci/make/consumer.mk + Makefile.generated.mk

Verbs (cross-product tabela)¶

02-verbs/00-cross-product.md — za svaki verb: ulaz · izlaz · side-effect · fail-mode · ci-state zapis · pipeline-exit

Vendor API contract¶

02-vendors/00-api-contract.md — User-Agent · timeout · auth header · VendorAuthError · izuzeci (5 njih)

Schemas¶

02-schemas/ — $schema URL · migrator lanac · breaking vs additive · refusa pravila

§4 · Hitna pomoć — "GORI"¶

Imaš 2 minuta? Skini ovo:

Pogledaj pipeline log na fail prozoru.
Ako je 401/403 + bilo koji *.infopuls.app → VendorAuthError je već logovao, NE retry — token je loš.
Provjeri da li je pipeline.release_commit postavljen: ci/state.py pipeline.release_commit
Ako jeste, a tvoj step radi na commit-u prije njega → nisi pozvao ci-checkout-release. Pogledaj §3 release invariant.
Provjeri arch drift: bin/check_arch_reminder.py --dry-run
Ništa ne pomaže? → otvori incident ticket, ne debug-uj 2am.

§5 · Anti-pitanja (ovo NISI, ne pitaj)¶

Stvari koje zvuče kao pitanja ali nisu — i na šta da odeš umjesto toga:

❌ "Kako se koristi X?" → idi u odgovarajući ci/X/CLAUDE.md, ne u bibliu.
❌ "Šta radi skripta Y?" → ci/Y/CLAUDE.md + --help.
❌ "Koja je razlika između stare i nove verzije?" → docs/history/.
❌ "Zašto baš ovako, a ne drugačije?" → §2 "Zašto" + ADR (docs/history/adr-*.md ako postoji).
❌ "Mogu li dodati X u services.json?" → 02-schemas/01-where-in-schema.md prvo.

§6 · Ažuriranje biblije¶

Ova biblija nije referenca — to su ci/*/CLAUDE.md i docs/. Ova biblija je kompas.

Kada se mijenja:

ci/<vendor>/** → provjeri da li opis u §3 važi još; ako ne, ažuriraj.
Nova verb → dodaj red u §2 "Kako radi" + cross-product u §3.
Nova shema / breaking bump → dodaj u 02-schemas/.
Novi uobičajeni bug → dodaj u 04-incidents/.

Regeneracija: 07-meta/regenerate.md opisuje skriptu koja indeksira sadržaj iz ci/*/CLAUDE.md i gradi TOCs automatski — ručno pisati samo članke, indeksi se generišu.

§7 · Indeks autoriteta — "KO JE ODLUČIO"¶

Ako se pitaš "čija je ovo bila odluka i zašto je zapisana":

CLAUDE.md (root + svaki ci/) → operativna pravila, ne referenca
docs/ci-env-vars.md → jedini inventar CI_* varijabli
docs/history/adr-*.md → arhitekturne odluke (kad postoje)
docs/plans/YYYY-MM-DD-*.md → design docs za velike promjene
.planning/ → radni planovi, ne commituju se
Jira CI board, label followup → odloženi follow-up