GitHub-acties voor Next.js: cache, lint, typecheck, tests en hoofdbescherming
Doel
Er komt geen commit in main tenzij de linter, typecontrole en tests slagen. Controles gaan snel dankzij de cache en verspillen geen minuten aan verouderde pushmeldingen. Hieronder vindt u de workflow- en repository-instellingen die ervoor zorgen dat dit van een aanbeveling een verplichte vereiste wordt.
Werkstroom
# .github/workflows/ci.yml
name: CI
on:
pull_request:
push:
branches: [main]
concurrency:
group: ci-${{ github.ref }}
cancel-in-progress: true
permissions:
contents: read
jobs:
quality:
name: lint-typecheck-test
runs-on: ubuntu-latest
timeout-minutes: 15
steps:
- uses: actions/checkout@v4
- uses: actions/setup-node@v4
with:
node-version-file: .nvmrc
cache: npm
- run: npm ci
- name: Lint
run: npm run lint
- name: Typecheck
run: npx tsc --noEmit
- name: Unit tests
run: npm test -- --run
build:
name: build
runs-on: ubuntu-latest
needs: quality
timeout-minutes: 20
steps:
- uses: actions/checkout@v4
- uses: actions/setup-node@v4
with:
node-version-file: .nvmrc
cache: npm
- run: npm ci
- uses: actions/cache@v4
with:
path: .next/cache
key: nextjs-${{ runner.os }}-${{ hashFiles('package-lock.json') }}-${{ hashFiles('**/*.ts', '**/*.tsx') }}
restore-keys: |
nextjs-${{ runner.os }}-${{ hashFiles('package-lock.json') }}-
- run: npm run buildWat is hier belangrijk
`concurrency` met `cancel-in-progress`. Drie keer achter elkaar in één vertakking zorgen voor drie runs, alleen de laatste is nodig. Groeperen op github.ref zet eerdere voor dezelfde branch of PR terug, maar heeft geen invloed op anderen.
`permissions: contents: read`. Standaard kan GITHUB_TOKEN schrijfrechten verkrijgen. Ze zijn niet nodig voor controles, en als een afhankelijkheid die in CI draait in gevaar komt, beperkt het minst bevoorrechte token de schade.
npm cache. setup-node met cache: npm slaat de globale pakketcache op in de cache met behulp van de hash van het vergrendelingsbestand. npm ci installeert node_modules nog steeds helemaal opnieuw, maar zonder te downloaden van het netwerk. U mag node_modules zelf niet in de cache opslaan: als u de Node-versie wijzigt, worden de native modules incompatibel.
Cache `.next/cache`. Next.js gebruikt de resultaten van de vorige build opnieuw. De sleutel bevat de bronhash en met restore-keys kunt u de nieuwste cache met hetzelfde vergrendelingsbestand gebruiken als er geen exacte overeenkomst is. Zonder deze cache geeft next build in CI een waarschuwing weer over de afwezigheid ervan.
`.nvmrc`. Eén versie van Node lokaal en in CI. Versieverschillen zijn een veelvoorkomende oorzaak van ‘werkt voor mij’.
Scripts in package.json
{
"scripts": {
"lint": "eslint .",
"typecheck": "tsc --noEmit",
"test": "vitest",
"build": "next build"
}
}De opdracht next lint is verouderd in nieuwe versies van Next.js, dus de linter wordt rechtstreeks aangeroepen. next build controleert zelf typen, maar de afzonderlijke stap tsc --noEmit in de eerste taak mislukt eerder en verspilt geen tijd aan de build.
Bescherm hoofd
Workflow zonder repositoryregels is slechts een indicator. Regelset instellen (Instellingen → Regels → Regelsets) of klassieke vertakkingsbescherming:
- 1.Vereist een pull-verzoek vóór het samenvoegen - directe pushes zijn verboden in
main. - 2.Vereisen dat statuscontroles slagen - voeg controles
lint-typecheck-testenbuildtoe. De namen worden overgenomen uit het veldnamevan de taak; als je de taak een andere naam geeft, wacht de regel op een controle die nooit meer zal plaatsvinden, en loopt de PR vast. - 3.Vereisen dat vertakkingen up-to-date zijn - PR wordt gecontroleerd met de laatste status
main, en niet met de status waarvan deze ooit is overgenomen. - 4.Blokkeer force push en verbied het verwijderen van vertakkingen.
- 5.Voeg jezelf niet toe aan bypass-regels “voor het geval dat”: bypass wordt juist toegepast op de avond dat tests mislukken.
Werkstroombeveiliging
- De gebeurtenis
pull_requestvoor PR's van forks wordt geactiveerd zonder toegang tot geheimen - dit is correct. Verander het niet inpull_request_targetomwille van het geheim: daar wordt de workflow uitgevoerd in de context van de basisbranch met rechten, en het uitchecken van code van PR geeft de code van anderen toegang tot deze. - Voeg acties van derden toe aan de volledige SHA van de commit, en niet aan de tag: de tag kan zwaarder wegen. De officiële
actions/*voor de hoofdversie is een redelijk compromis. - Bewaar geheimen voor implementatie in omgevingen met verplichte bevestiging, en niet in de algemene geheimen van de repository.
Diagnostiek
- PR wordt niet samengevoegd, de controle is "Verwacht - Wachten op status". De naam van de vereiste controle komt niet overeen met de naam van de taak, of de workflow is niet gestart vanwege het filter
paths. Als de workflow met het padfilter niet is gestart, blijft de verplichte controle in behandeling. - De cache wordt niet hersteld. Caches worden geïsoleerd door vertakkingen: een PR ziet de cache van zijn vertakking en de basis, maar niet van aangrenzende PR's. De eerste run in een nieuwe vestiging is altijd koud.
- Tests blijven hangen tot time-out. Vitest wacht in observatiemodus op wijzigingen. In CI wordt de variabele
CI=trueautomatisch ingesteld en Vitest houdt hier rekening mee, maar een expliciete--runis betrouwbaarder.
Wanneer is het genoeg en wanneer niet
Voor een team van een paar personen omvat deze set de basis. E2E-tests op Playwright worden als aparte taak toegevoegd met needs: build wanneer kritische gebruikersscenario's verschijnen. Als CI meer dan tien minuten duurt, splitst u de tests in scherven door de matrix in plaats van ze uit te schakelen.