GitHub Actions-lockfile legt uitvoercode vast, maar niet de volledige CI

Kun je GitHub Actions vertrouwen als een workflow verwijst naar een action met een tag zoals @v3? Een lockfile bepaalt welke commit van de action wordt uitgevoerd, zelfs als de tag later wordt verplaatst. Het team kan updates van afhankelijkheden in de diff bekijken en een controleerbare lijst bijhouden van de actions die CI gebruikt. De praktische grens: de lockfile omvat actions die door stappen worden aangeroepen, maar een herbruikbare workflow die op jobniveau wordt aangeroepen, moet afzonderlijk worden vastgezet. Het beschreven mechanisme is beschikbaar in GitHub Enterprise Cloud.

Wat legt de lockfile precies vast?

Verwijzingen naar branches en tags zijn handig, maar de versie waarnaar ze verwijzen kan veranderen. Een vermelding als uses: octo-org/deploy-action@v3 verwijst naar een tagnaam; GitHub vertaalt die verwijzing bij het uitvoeren naar een commit. Als de eigenaar van het project de tag verplaatst, kan een volgende uitvoering zonder vastgezette afhankelijkheid andere code ophalen.

Volgens de documentatie van GitHub over lockfiles bevat het bestand .github/workflows/actions.lock verwijzingen naar afhankelijkheden en de bijbehorende commit-SHA’s, inclusief transitieve afhankelijkheden — actions die door andere actions worden gebruikt. Het bestand wordt aangemaakt met de GitHub CLI-extensie gh actions-lock en wordt niet handmatig bewerkt.

De generator kan ook de uses-verwijzingen in workflowbestanden aanscherpen: een verwijzing naar een bewegende tag kan bijvoorbeeld specifieker worden gemaakt, met behoud van de commit waarnaar die verwees toen de lockfile werd aangemaakt. Bekijk daarom bij de invoering de volledige diff — zowel de wijzigingen in de workflow als die in de lockfile — en controleer of de vastgezette versie daadwerkelijk de versie is die het team wil uitvoeren.

Daarna is een update van een afhankelijkheid zichtbaar als wijziging in de repository: het team kan de commitwijziging controleren, bespreken en via de gebruikelijke review goedkeuren. De lockfile helpt de code van actions te auditen en afhankelijkheden consistent te houden; op zichzelf bevestigt hij niet dat de gekozen code veilig is.

Waar houdt het vastzetten op?

Een herbruikbare workflow die wordt aangeroepen via jobs.<job_id>.uses wordt niet vastgezet door de lockfile in de aanroepende repository. De afhankelijkheden van de herbruikbare workflow horen bij de repository waarin die workflow is gedefinieerd. Zet de aanroep zelf vast met een volledige commit-SHA; voor het vastzetten van de bijbehorende actions in de bronrepository is een eigen lockfile nodig.

De lockfile controleert de code van actions, maar niet andere buildinputs, zoals parameters die aan een action worden doorgegeven, secrets of de runner-image. De lockfile beantwoordt een specifieke vraag: welke commit van de action-code wordt uitgevoerd? Voor die andere onderdelen zijn eigen beheersregels nodig.

Een bijzonder geval is een lokale action die wordt aangeroepen via een pad als uses: ./. Volgens de instructies van GitHub zet de extensie gh actions-lock een lokaal action-pad niet vast en analyseert die het evenmin. Als zo’n action andere actions gebruikt, moeten de afhankelijkheden afzonderlijk worden beheerd; de documentatie beschrijft een mogelijkheid om verwijzingen naar lokale actions om te zetten naar de notatie $/.

Een vermelding in de lockfile kan dus onderdeel zijn van een afhankelijkheidsketen, maar vervangt niet de controle van alle schakels. Controleer bij een externe herbruikbare workflow of de aanroep is vastgezet en wat de status is van de bronrepository; controleer bij lokale actions hoe hun afhankelijkheden zijn meegenomen.

Hoe voer je de controle in zonder dat CI onverwacht stilvalt?

GitHub raadt aan eerst een pilot uit te voeren met geselecteerde repositories en workflows. Het beleid Require lockfile blokkeert de uitvoering van doelworkflows zonder een geldige lockfile, ook als de workflow geen uses:-afhankelijkheden bevat. De modus Evaluate voor beleidsregels is alleen beschikbaar in GitHub Enterprise Cloud. Bereid daarom eerst de scope en automatische updates voor en schakel daarna pas de verplichte regel in.

1. Controleer de oorspronkelijke verwijzingen. Controleer voordat je de lockfile aanmaakt of de actions verwijzen naar versies die het team daadwerkelijk wil vastzetten. De generator legt de commit vast waarnaar de huidige verwijzing wordt vertaald.
2. Maak de lockfile aan en beoordeel die. Installeer de extensie gh-actions-lock, voer gh actions-lock uit vanuit de hoofdmap van de repository en bekijk de volledige diff, inclusief herschreven uses-verwijzingen.
3. Stel updates en controles in. Dependabot kan de bijbehorende vermeldingen bijwerken voor workflows die al zijn aangesloten. In CI kun je een controletaak voor pull requests instellen met gh actions-lock --verify, zodat een verouderde lockfile wordt opgespoord voordat de hoofd-build start.
4. Wijs reviewers aan. Voeg .github/workflows/actions.lock toe aan CODEOWNERS en vereis dat verantwoordelijken voor buildbeveiliging wijzigingen beoordelen.
5. Voer een beleidspilot uit. Begin met de aangesloten repositories en workflows. Analyseer de resultaten in Evaluate; controleer voordat je overschakelt naar Active of alle doelworkflows zijn voorbereid en de lockfiles actueel blijven.

Require lockfile en het afzonderlijke beleid Require actions to be pinned to a full-length commit SHA zijn verschillende regels; GitHub geeft aan dat je ze allebei kunt handhaven. Een CI-controle en een verplicht beleid vervullen eveneens verschillende functies: de eerste spoort tijdens het werk aan een pull request een verouderd bestand op, terwijl het tweede de uitvoering blokkeert van workflows die niet aan de eis voldoen.

Voorbeeld: een deployment-action bijwerken

Stel dat een workflow een applicatie publiceert via octo-org/deploy-action@v3. Eerst controleert het team naar welke versie die verwijzing wordt vertaald. Vervolgens voert het gh actions-lock uit en beoordeelt het de diff van de workflow samen met de commitvermelding in de lockfile. Bij een update van de action ziet de reviewer wijzigingen in de verwijzingen en de vastgelegde commit. Zo kan die een concrete update beoordelen in plaats van erop te vertrouwen dat een verplaatsbare tag altijd naar dezelfde code blijft verwijzen.

Als de deployment wordt uitgevoerd door een herbruikbare workflow uit een andere repository, omvat de lokale lockfile de afhankelijkheden daarvan niet. Zet de verwijzing naar de herbruikbare workflow vast met een volledige SHA en controleer of de bronrepository de eigen action-afhankelijkheden beheert. In grote organisaties maakt dit van losse regels een controleerbaar proces, terwijl parameters, secrets en runners afzonderlijk onder controle blijven.

Een lockfile is een nuttige controlelaag voor de code van actions: versies en updates worden inzichtelijk, inclusief transitieve afhankelijkheden. Controleer voor een betrouwbare dekking ook herbruikbare workflows en lokale actions, automatiseer updates en voer verplicht beleid pas in na een pilot.