CI/CD, környezetek, migrációk, release-stratégia

8.1Az alap: version és deployment

Beanstalkon a „deploy" egyetlen esemény: az új kód felmegy, a régi eltűnik. A Workers ezt kettévágja, és minden más erre épül:

• Version — a kódod immutábilis, feltöltött pillanatképe (kód + konfig + assetek + bindings — ez utóbbi fontos lesz!). A feltöltés önmagában nem visz rá forgalmat. Minden versionnek saját ID-ja és saját preview URL-je van.
• Deployment — az a döntés, hogy melyik version(ök) kapják a forgalmat, milyen arányban. Lehet „100% v42", de lehet „90% v41 + 10% v42" is.

npx wrangler versions upload   # feltöltés forgalom nélkül → version ID + preview URL
npx wrangler versions deploy   # forgalom ráengedése / arányállítás
npx wrangler deploy            # a kettő egyben: upload + 100% promote
npx wrangler rollback          # vissza az előző deployolt versionre — másodpercek

Mivel a versionök már fent vannak a hálózaton, a kanári-emelés és a rollback csak metaadat-átállítás — nem újra-deploy. Ez az, amit a CodeDeploy blue/green környezet-duplázással közelített.

8.2Környezetek: pontosan mi különül el, és ki hozza létre?

Az első tisztázandó: a Cloudflare-nek nincs „environment" nevű platformfogalma úgy, ahogy az AWS-en egy külön account vagy egy Beanstalk environment létezik. Amit „staging"-nek hívsz, az három dolog konvenciója:

1. egy nevesített konfig-blokk a wrangler-fájlban (env.staging),
2. egy ebből születő külön Worker (my-app-staging) saját route-tal,
3. és külön erőforrás-példányok, amiket te hozol létre és kötsz be.

Ez a harmadik pont a kulcs, amit sokan elsőre félreértenek: az env.staging blokk megírása nem hoz létre semmit. A staging D1-et, R2 bucketet, queue-t, KV namespace-t neked kell megteremtened, névvel megkülönböztetve, majd a konfigban az adott env alá bekötnöd:

# a staging világ erőforrásai — egyszeri létrehozás
npx wrangler d1 create app-staging --location weur
npx wrangler r2 bucket create uploads-staging
npx wrangler queues create jobs-staging
npx wrangler kv namespace create CONFIG_STAGING

# és ugyanez -prod utótaggal a productionnek

{
  "name": "my-app",
  "main": "./.output/server/index.mjs",
  "compatibility_date": "2026-08-02",
  "compatibility_flags": ["nodejs_compat"],

  "env": {
    "staging": {
      "name": "my-app-staging",
      "route": { "pattern": "staging.example.com/*", "zone_name": "example.com" },
      "vars": { "APP_ENV": "staging" },
      "d1_databases": [{ "binding": "DB", "database_name": "app-staging", "database_id": "…" }],
      "r2_buckets":   [{ "binding": "UPLOADS", "bucket_name": "uploads-staging" }],
      "queues": { "producers": [{ "binding": "JOBS", "queue": "jobs-staging" }] }
    },
    "production": {
      "name": "my-app-production",
      "route": { "pattern": "app.example.com/*", "zone_name": "example.com" },
      "vars": { "APP_ENV": "production" },
      "d1_databases": [{ "binding": "DB", "database_name": "app-prod", "database_id": "…" }],
      "r2_buckets":   [{ "binding": "UPLOADS", "bucket_name": "uploads-prod" }],
      "queues": { "producers": [{ "binding": "JOBS", "queue": "jobs-prod" }] }
    }
  }
}

Hol van ez pontosan leírva? Mert jogos az igény, hogy ne az én szavamra kelljen hinni:

8.3Workers Builds és a PR-k: mi történik valójában?

A Builds branch-logikája két ágra bomlik, és mindkét ághoz saját parancsot rendelsz:

Most jön a rész, amit a marketingoldalak elmosnak, és amire a kérdésed pontosan rátapintott: mi a PR-preview valójában?

A helyes, biztonságos alapfelállás tehát ez a parancspár a Builds beállításaiban:

# Deploy command (production branch):
npx wrangler deploy --env production

# Non-production branch deploy command (minden PR):
npx wrangler versions upload --env staging

Ezzel minden PR-preview a staging erőforrásokon fut: staging DB, staging bucket, staging queue. A reviewer kattint a PR-kommentben lévő URL-re, és egy élő, de veszélytelen változatot néz. Ez a legtöbb csapatnak pontosan elég — és ez a berendezkedés kb. 20 perc munka.

És a „minden PR-nak saját, izolált környezete" álom?

Őszintén: ezt a platform nem adja készen. Nincs beépített „ephemeral environment per PR" — a PR-ek a közös staging erőforrásokon osztoznak. Ebből három következmény és három szintű megoldás adódik:

8.4A séma-migráció helye a pipeline-ban

Ez a modul legfontosabb szakasza, mert itt találkozik minden korábbi szál: a kanári (két kódverzió fut egyszerre!), a rollback (kódot vált, sémát nem!) és a DB-fegyelem. Előbb a három elv, aztán a konkrét workflow.

A három elv

1. A migráció a repo része és verziózott. Sorszámozott fájlok (migrations/0007_add_invoice_status.sql), a PR-ban együtt utaznak a kódváltozással — a reviewer egyszerre látja a séma- és kódváltozást. Az állapotkönyvelést a wrangler d1 migrations apply végzi (meta-tábla a DB-ben: mi futott már le).
2. A migráció külön pipeline-lépés, a kód-deploy ELŐTT fut. Soha nem a Worker kódjából, soha nem „majd az első kérés migrál" — hanem explicit lépésként: előbb a séma, aztán a kód.
3. Minden migráció expand–contract. Mivel kanári alatt a régi és az új kód egyszerre fut ugyanazon a sémán, és mivel a rollback bármikor visszahozhatja a régi kódot, a séma minden pillanatban mindkét szomszédos kódverziót ki kell szolgálja. Gyakorlatban: expand fázis (új oszlop/tábla hozzáadása — a régi kód nem tud róla, nem is zavarja), majd külön, későbbi release-ben a contract (a régi oszlop törlése, amikor már biztosan senki nem használja).

A konkrét workflow — auto és manuális határvonallal

Hova építed ezt? Két működő elrendezés van, és a válasz a prod-gate igényedtől függ:

A) Workers Builds egyedül — a deploy command lánccá fűzhető: npx wrangler d1 migrations apply app-db --env production --remote && npx wrangler deploy --env production. Ez működik, de auto-migrál minden main-pushnál, emberi kapu nélkül — kis csapatnak, alacsony kockázatú sémáknál vállalható, éles multitenant SaaS-nál nem ezt ajánlom.

B) GitHub Actions a prod-úthoz (ajánlott) — a PR-preview-t és a staginget viheti a Builds, a production-release viszont Actions-workflow, amelyben a production GitHub environmentre required reviewers van beállítva — a migráció és a kanári csak jóváhagyás után indul:

jobs:
  migrate-and-canary:
    environment: production        # ← itt áll meg, amíg valaki jóvá nem hagyja
    steps:
      - run: npx wrangler d1 migrations apply app-db --env production --remote
      - run: npx wrangler versions upload --env production   # → version ID
      - run: npx wrangler versions deploy … # 10% kanári a friss versionre
  promote:
    needs: migrate-and-canary
    environment: production-promote  # második kapu: 100%-ra emelés
    steps:
      - run: npx wrangler versions deploy … # 100%

Multitenant, DB-per-tenant felállásnál (5b. modul) a prod-migráció lépés nem egy apply, hanem a Workflow-alapú flotta-runner elindítása — canary tenantokkal, verziókönyveléssel; az elve ugyanez: gated indítás, automatizált végrehajtás.

8.5Amikor a migráció élesben elhasal

És most a kérdésed legkeményebb része: mi van, ha a prod-adat olyan állapotban van, amit a teszt nem fedett le? Vegyük sorra a klasszikus hibamódokat — mindhez a megelőzés ÉS a mentés.

a) Adat-függő hiba: a NULL, amire senki nem gondolt

Tünet: a ALTER TABLE … ADD COLUMN x TEXT NOT NULL vagy egy CREATE UNIQUE INDEX elszáll, mert a prod-ban vannak NULL-ok/duplikátumok, amik a staging játékadatában nem voltak.

• Megelőzés 1 — prod-szerű adat a stagingen. D1-nél: wrangler d1 export app-prod --remote → import a stagingbe (rendszeresen, akár heti cron-nal; érzékeny mezőket maszkolva). Postgresnél ugyanez dump/restore-ral. A staging értéke pontosan annyi, amennyire az adata hasonlít az élesre.
• Megelőzés 2 — pre-flight ellenőrzés. A migrációs lépés első parancsa egy ellenőrző query: SELECT COUNT(*) FROM orders WHERE customer_email IS NULL — ha nem 0, a pipeline megáll a migráció előtt, nem közben. Ez pár sor a release-workflow-ban, és a hibák nagy részét deploy előtti, nyugodt problémává szelídíti.
• Megelőzés 3 — a szabály maga: új NOT NULL oszlop mindig DEFAULT-tal vagy két lépésben (nullable-ként fel + backfill + majd NOT NULL constraint) megy fel. Unique index előtt mindig dedup-lépés.

b) Timeout: a nagy tábla, amit egyben akartál átírni

Tünet: az UPDATE orders SET status_v2 = … egy 40 milliós táblán túllépi az időkorlátot (D1-nél a query-korlátokat, Postgresnél lock-vihart okoz).

• A szabály: a migrációs fájlban csak séma-DDL utazik, adat-átalakítás soha. A backfill külön, batchelt folyamat — és erre már van eszközöd a 7. modulból: egy Workflow, ami UPDATE … WHERE id IN (SELECT id FROM orders WHERE status_v2 IS NULL LIMIT 1000) lépéseket futtat step.do-ban, amíg el nem fogy — megszakadás után onnan folytatja, ahol tartott, a DB-t sosem fogja percekre.
• Az expand–contract itt is véd: amíg a backfill fut (órákig? napokig? mindegy!), a régi oszlop él, a kód mindkettőt kezeli — nincs időnyomás.

c) Félbeszakadt migráció: mi az állapot most?

• Kis, egy-célú migrációs fájlok. Egy fájl = egy logikai változás. Ha az 0007-es elhasal, pontosan tudod, mi maradt félbe — nem egy 14 lépéses monstrum közepén állsz.
• Idempotens írásmód (IF NOT EXISTS, OR IGNORE), hogy az újrafuttatás mindig biztonságos legyen — a javítás utáni út szinte mindig a fix-forward: kijavítod a migrációt/adatot, és újra futtatod.
• A vésztartalék D1-en a Time Travel — de értsd a hatókörét: az egész adatbázist állítja vissza egy időpontra, tehát a migráció óta beérkezett éles írásokat is elveszti. Ezért ez az utolsó eszköz, nem az első: akkor nyúlsz hozzá, ha a migráció adatot rontott (nem csak félbemaradt), és a rontás óta kevés írás történt. Forgalmas rendszeren a helyes sorrend: azonnali rollback a kódra (az expand-séma a régi kódnak nem árt!), majd nyugodt tempóban adat-javító szkript.

d) A playbook — mi a teendők sorrendje élesben

1. Állj. A pipeline ne lépjen tovább (ezért kell a kanári-emelés elé is kapu) — félkész séma + új kód 100%-on a legrosszabb kombó.
2. Mérd fel: a migráció el sem indult (pre-flight fogta meg — nincs kár), félbeszakadt (séma részleges — mi ment át?), vagy lefutott, de rossz (adat sérült)?
3. A futó szolgáltatást védd először: ha az új kód már kanárin van, wrangler rollback — az expand-jellegű séma a régi kódot nem zavarja, tehát a userek szempontjából a tűz el van oltva másodpercek alatt. Ez az igazi hozadéka az egész fegyelemnek.
4. Aztán a séma: fix-forward (javított migráció újrafuttatása) az alapeset; Time Travel/restore csak adatsérülésnél, a friss írások mérlegelésével; multitenant flottánál a runner a hibás tenantnál állt meg — a többiek vagy érintetlenek, vagy már készen vannak, a registry mutatja.
5. Utólag: ami élesben bukott, az a stagingen hiányzó adat-eset volt → kerüljön be a prod-export-frissítésbe vagy a pre-flight query-k közé. A playbook így öngyógyító.

8.6Secrets: röviden, de pontosan

• vars = nyílt szöveg a repóban — csak nem-érzékeny konfignak. Minden más: secret.
• Élesben: wrangler secret put STRIPE_KEY --env production (írás után visszaolvashatatlan); tömegesen: wrangler secret bulk. Lokálisan: .dev.vars / .dev.vars.staging — gitignore-ban. A kód mindig ugyanúgy látja: env.STRIPE_KEY.
• A secrets.required konfiglistával deklarálod az elvárt kulcsokat — hiányra figyelmeztetést kapsz, nem éles 500-ast.
• Rotáció-sorrend: a secret-csere új deploymentet jelent, és rollbacknél a secretek nem állnak vissza — előbb legyen az új kulcs érvényes a külső rendszerben, csak aztán cseréld itt.
• A CI-nak egyetlen Cloudflare API token kell (a CI secret store-jában) — nem IAM-szerepkör-erdő.

8.7A teljes kép: az ajánlott pipeline

8.8Ellenőrizd magad