Munkafolyamat-sablonok

Ez a dokumentum elmagyarázza, hogyan állíts be folyamatos integrációs (CI) munkafolyamatokat egy Exercism nyelvi kurzushoz GitHub Actions (GHA) segítségével. Bevált gyakorlatokat és példákat kínál, amelyeket felhasználva gyors, megbízható és robusztus CI-munkafolyamatokat készíthetsz magadnak. Az ebben a mappában található GHA-munkafolyamatok bármilyen CI-rendszerhez igazíthatók, mert az alapstruktúra ugyanaz marad.

Ez a következőket teszi:

  • Felvázolja az ideális CI-munkafolyamatot
  • Megvitatja a szempontokat és az ajánlásokat
  • Néhány használható sablont ad a kezedbe
  • Végül egy útmutatóval maradsz, amely a Travisról való átállást segíti

Ezen munkafolyamat-fájlok példaimplementációja megtalálható az exercism/javascript repóban.

SEGÍTS: ez sok munkának tűnik 😓

A dokumentum hátralévő része azt hivatott elmagyarázni, hogyan működnek a munkafolyamatok. Ha sietsz, és csak át szeretnél állni a Travisről vagy a Circle-ről GHA-ra anélkül, hogy optimalizálnád a PR-szkripteket, nézd meg a ~10 perces útmutatónkat a Travisról való átállásról.

A kurzushoz tartozó CI-műveletek

A következő műveleteket ajánljuk annak ellenőrzésére, hogy a repód tartalma sértetlen-e:

  1. configlet lintelés a config.json ellenőrzéséhez
  2. a csonkok meglétének ellenőrzése
  3. a dokumentáció ellenőrzése (a v3 új fájlokat igényel; ez lehet, hogy átkerül a configlet-be)
  4. a feladatok lintelése egy „karbantartói” konfigurációval
  5. a feladatok tesztelése a példa- vagy exemplarfájlokkal (tartalmazhat build lépést)

Lehetnek kurzusspecifikus műveletek is. Például:

  1. a feladatkonfigurációk integritásának ellenőrzése
  2. a feladatfájlok formázásának ellenőrzése

És talán szeretnél még néhány kényelmi ellenőrzést, például:

  1. győződj meg róla, hogy létezik a CONTRIBUTING
  2. győződj meg róla, hogy van egy rendes lockfile a függőségekhez
  3. győződj meg róla, hogy a markdown fájlokban lévő hivatkozások érvényesek
  4. ...

Ajánlások

Az ellenőrzések futtatásának gyakorisága

Minden műveletnél gondold át, milyen gyakran kell lefutnia.

  • A configlet lintelés annyira fontos (mert egy kurzus eltörhet, ha a config.json eltörik), hogy valószínűleg mindig le kell futnia, de csak egyszer kell lefutnia commitonként.
  • A fájlok meglétét vagy integritását csak egyszer kell ellenőrizni commitonként.
  • Ha egy kurzusnak több futtatókörnyezet- vagy fordítóverzió alatt kell futnia, a feladatok buildelését és tesztelését minden támogatott verzióval le kell futtatni.
  • A PR-eknél valószínűleg csak a hozzáadott vagy módosított fájlokon kell futtatni a műveleteket, de mivel egy fájl befolyásolhat egy feladatot, biztonságosabb a feladatra futtatni a műveleteket, ha annak valamelyik fájlja megváltozik.

Nagyon hasznos lehet, ha a lefuttatandó műveleteket helyben is elérhetővé teszed. Ez azt jelenti, hogy a tényleges munkát végző szkripteket kézzel is futtathatod. Ehhez ne ágyazd be a műveletet a munkafolyamat-fájlokba, hanem hozz létre egy önálló szkriptet. Például a csonkok ellenőrzése teljesen megoldható bashben a munkafolyamat-fájlon belül, de itt az a javaslat, hogy inkább hozz létre egy új futtatható szkriptet scripts/ci-check néven.

„De a parancs nagyon rövid, pl. eslint . --ext ts --ext tsx”.

Amikor ezt a parancsot frissíteni kell, most minden helyen frissíteni kell: a dokumentációban, a munkafolyamat-fájlokban és a karbantartók fejében. Ha ezt egy szkriptbe emeled ki, mindez megoldódik. Egy munkafolyamat-fájl elolvasása is nagyon ijesztő tud lenni.

Ellenőrzések azoknál a PR-eknél, ahol feladatok változnak

A scripts/pr és scripts/pr-check szkriptek (lásd sablonok) több argumentummal futnak, eggyel minden olyan fájlhoz, amelyet ebben a PR-ben módosítottak vagy hozzáadtak. Például ha a two-fer frissült, a hívás így nézhet ki:

scripts/pr exercises/two-fer/README.md exercises/two-fer/.meta/example.ext

Ajánlott minden műveletet a megváltozott feladatra futtatni, nem a megváltozott fájlra. Ez azért van, mert egy fájl módosítása valószínűleg az egész feladat változásait kiváltja (gondolj a konfigurációra, a csomagokra).

Nem áll készen? / Bonyolult?

Mielőtt bevezetnéd ezt az optimalizálást, nyugodtan figyelmen kívül hagyhatod! Az átállási útmutató utal rá, hogy későbbi szakaszban érdemes hozzáadni. Ha a bemeneti argumentumokat figyelmen kívül hagyod, minden ellenőrzés lefut az összes feladatra. Ez teljesen rendben van. Csak tovább tart.

Integritásellenőrzések

Ha a kurzusnak egyetlen „legfelső szintű” függőségi fájlja és/vagy más konfigurációs fájljai vannak, adj hozzá egy integritás lépést (amely a scripts/sync vagy bin/sync mellett létezik, és amely az összes konfigurációs fájlt átmásolná az összes feladatba), amely biztosítja, hogy a legfelső szintű vagy alapfájlok ugyanazok legyenek, mint amit a feladatkönyvtárakba másoltak. Így a függőségek frissíthetők, szinkronizálhatók a repóban, és biztosíthatjuk, hogy minden feladat ugyanazzal a konfigurációval rendelkezik.

Ennek gyakori módja egy ellenőrzőösszeg használata. Az Ubuntu (és több más Linux-disztribúció) tartalmaz egy sha1sum nevű eszközt, de bármelyik módszer működik, amellyel a konfigurációs fájlt hashelted vagy ellenőrzőösszeg-értékké alakítod (md5, sha1, crc32):

$ sha1sum README.md
cd58091c5043bf21f00d39ff1740d8b2976deeff *README.md

Biztonsági ellenőrzések

Ha a kurzus olyan további munkafolyamatokat használ, amelyek hozzáférést igényelnek a GitHub tokenhez vagy más titkokhoz, ajánlott a munkafolyamatban használt összes műveletet egy adott commithez rögzíteni. Részletekért lásd a GitHub biztonsági megerősítési útmutatóját.

Például:

- uses: julia-actions/setup-julia@v1
+ uses: julia-actions/setup-julia@d26d1111976eae5f00db04f0515ab744ec9cd79e # 1.3.1

Ha a tooling rendelkezik lockfile-okkal a függőségek kezeléséhez, fontold meg, hogy beleteszed a repóba, és „frozen lockfile”-t használsz a munkafolyamat-fájlokban. Például: npm ci, yarn install --frozen-lockfile és bundle install --frozen. Ez biztosítja, hogy a lockfile naprakész legyen a függőségek módosításakor, és megakadályozza, hogy rosszindulatú csomagok kerüljenek be.

Sablonok

Ebben a könyvtárban legalább a következő sablonok találhatók:

  • configlet.yml: Ez a munkafolyamat letölti a legfrissebb configlet binárist, és linteli ezt a repót. Minden commiton lefut. PR-eknél a tényleges commiton és egy „merge utáni” fán fut.
  • ci.yml: Ez a munkafolyamat csak a main ágon fut, minden commiton egyszer.
    1. Lefuttat egy „előellenőrző” parancsot (csonkok, lint, dokumentáció stb. ellenőrzése) az összes feladatra
    2. Lefuttat egy „ci” parancsot (build és tesztelés) több verzióra, az összes feladatra
  • pr.ci.yml: Ez a munkafolyamat csak PR-eken fut, minden commiton egyszer.
    1. Lefuttat egy „előellenőrző” parancsot (csonkok, lint, dokumentáció stb. ellenőrzése) a megváltozott fájlokra
    2. Lefuttat egy „ci” parancsot (build és tesztelés) több verzióra, a megváltozott feladatokra

A nem PR-hez tartozó munkafolyamatok workflow_dispatch segítségével is elindíthatók.

Minden fájl tetején fel van sorolva, hogy mely „szkripteknek” kell elérhetőnek lenniük. Ha ezeket binárisokként szeretnéd, cseréld le a scripts/xxx-et bin/xxx-re. Néhány tooling megköveteli, hogy a binárisok egy bin mappában legyenek.

  • scripts/ci: egy szkript, amelynek az összes feladatot buildelnie és tesztelnie kell a példamegoldásokkal a tesztek ellenében
  • scripts/ci-check: egy szkript, amelynek az összes feladatot lintelnie kell, és opcionálisan ellenőriznie kell a csonkokat, a konfiguráció integritását és egyebeket
  • scripts/pr: ugyanaz, mint a scripts/ci, de csak azokat a feladatokat futtatja, amelyeket a bemenetként megadott útvonalakból felold
  • scripts/pr-check: ugyanaz, mint a scripts/ci-check, de csak azokra a fájlokra vagy feladatokra fut, amelyeket a bemenetként megadott útvonalakból felold

Hibaelhárítás

Ha bármilyen problémába ütközöl, vagy szeretnéd, hogy valaki átnézze a munkafolyamataidat, pingeld meg a @exercism/github-actions csapatot.

Módosítottál egy legfelső szintű fájlt, amelynek CI-futtatást kellene kiváltania az összes feladatra

A jelen írás pillanatában a pr.ci.yml csak „kiterjesztés” szerinti tesztelést tesz lehetővé. Ideális esetben ezt frissítenék, hogy mindig elinduljon, amikor bizonyos fájlok megváltoznak (például a tesztek futtatásához használt bináris). Ezek a változtatások azonban gyakran ritkák, és karbantartók végzik őket, így valószínűleg elég biztonságos, hogy a ci.yml a main ágon mindig, mindenre lefut.

Létrehoztál egy scripts/xxx fájlt Windowson, és most nem működik {other OS} alatt

Alapértelmezés szerint a Windowson létrehozott fájlok git-index bejegyzésében nem szerepel metaadat a futtathatóságukról, mert a Windows jogosultsági modellje más. A Git alapértelmezés szerint a git-index metaadatait használja annak meghatározására, hogy a fájlnak futtathatónak kell-e lennie a POSIX-alapú rendszereken, és így a scripts/xxx fájlt NEM teszi futtathatóvá.

git update-index --chmod=+x scripts/xxx
git commit -m "Make scripts/xxx executable"