Wie das Versionierungssystem von GitHub Actions funktioniert

TL;DR

• Der Läufer lädt nur das herunter, was Sie angegeben haben, indem er es aus dem Tag
• Der Läufer führt SemVer überhaupt nicht aus. Das ist Sache des Maintainers
• Selbst GitHub aktualisiert (oder erstellt) nicht alle SemVer-Versionen, so dass @v3 nicht unbedingt das Neueste für v3 ist!
• Der Marktplatz zeigt Veröffentlichungen an, nicht Tags. Wenn der Betreuer nicht wirklich veröffentlicht, ist es nicht sichtbar.
• Es ist sicherer, einen SHA-Hash anstelle eines Tags zu verwenden: Lesen Siehier weitere Informationen

Semantische Versionierung

Wenn Sie GitHub-Aktionen verwenden, werden standardmäßig die semantischen Versionen verwendet, für die die Aktionen freigegeben wurden. Semantische Versionierung (SemVer) ist ein branchenweiter Standard, um der Versionsnummer eine Bedeutung zu geben. SemVer folgt immer diesem Aufbau:

MAJOR.MINOR.PATCH

Wenn Sie eine Versionsnummer angeben, erhöhen Sie die:

• MAJOR-Version, wenn Sie inkompatible API-Änderungen vornehmen
• MINOR-Version, wenn Sie Funktionen auf abwärtskompatible Weise hinzufügen
• PATCH-Version, wenn Sie rückwärtskompatible Fehlerkorrekturen vornehmen Optional können Sie jede beliebige Endung verwenden, um spezielle Versionen wie Alpha, Beta, Release Candidate usw. anzugeben:
• 1.2.5-alpha.1
• 1.2.5-RC.1

Das Ziel der Verwendung von SemVer ist es, dass Sie dann angeben können, was Sie als Benutzer einer Bibliothek verwenden möchten. Sie können sehr spezifisch sein und sagen, Sie möchten die Version 9.1.4, aber seien Sie auch weniger spezifisch und sagen Sie, dass Sie die Version 9.1. In Anlehnung an SemVer bedeutet dies, dass Sie eine beliebige Version verwenden möchten, die mit dem 9.1 MAYOR.MINOR Version. Das bedeutet, dass Sie die neueste Version von 9.1 die verfügbar ist. Dies ist sehr nützlich, wenn Sie die neueste Version einer Bibliothek verwenden möchten, aber nicht jedes Mal Ihren Code aktualisieren wollen, wenn eine neue Version veröffentlicht wird. Sie können einfach die Version MAYOR.MINOR angeben und Sie erhalten die neueste Version dieser Version. Effektiv bedeutet das, dass Sie sagen 9.1.*.

Wenn Version 9.1.3 die aktuellste PATCH-Version ist, wird Ihr Paketmanager diese Version herunterladen. Wenn Version 9.1.4 veröffentlicht wird, lädt Ihre Paketverwaltung diese Version herunter. Wenn die Version 9.2.0 veröffentlicht wird, wird Ihr Paketmanager nicht diese Version herunterladen, da sie nicht mit der von Ihnen angegebenen MAYOR.MINOR-Version übereinstimmt.

Das gleiche gilt für die MINOR-Version. Wenn Sie die Version 9wählen, erhalten Sie die neueste Version dieser MAYOR Version. Das bedeutet, dass Sie die aktuellste Version von 9.1 und 9.2 und 9.3 und so weiter. Effektiv bedeutet das, dass Sie sagen 9...

Was der Runner mit der semantischen Versionierung bei der Verwendung von GitHub-Aktionen macht

Der Runner, der die GitHub-Aktionen für uns ausführt, ist Open Source. Sie können den Quellcode dafür einsehen hier. Wenn Sie sich damit befassen, können Sie feststellen, dass der Runner versucht, die Version von der von Ihnen angegebenen Aktion herunterzuladen:

- uses: actions/checkout@v2     --> will download the repo with TAG = v2
- uses: actions/checkout@v3.1.0 --> will download the repo with TAG = v3.1.0
- uses: actions/checkout@main   --> will download the repo with BRANCH = main
- uses: actions/checkout@e2f20e631ae6d7dd3b768f56a5d2af784dd54791 --> will download the repo with COMMIT = e2f20e631ae6d7dd3b768f56a5d2af784dd54791 (SHA hash)

Den Code dazu finden Sie über den Download-Link hier. Der Läufer ruft dann die REST-API auf, um eine Tarball des Repo (oder auf einem Nicht-Windows-Host die Zip-Datei des Repo).

Wenn der TAG (oder Zweig oder SHA-Hash), den Sie angegeben haben, nicht im Repository verfügbar ist, gibt der Runner eine Fehlermeldung aus, dass er diese Version nicht finden kann.

SemVer für Aktionen verwenden

Interessant ist nun, was passiert, wenn Sie ein semantisches Versionsmuster für eine Aktion angeben. Zum Beispiel:

- uses: actions/checkout@v3.1

Nach der semantischen Versionierung würden Sie erwarten, dass dieses Beispiel funktioniert. Die Konfiguration von Aktionen mit einer Version (oder einem Tag oder einem Hash) ist heutzutage erforderlich, damit der Runner die richtige Referenz zum Herunterladen finden kann. Das bedeutet, dass der Betreuer der Aktion SemVer folgen MUSS, wenn er seine Aktionen freigibt, wie auch in der GitHub Actions Dokumentation. Wenn der Maintainer SemVer nicht folgt, kann der Runner nicht die richtige Version zum Herunterladen finden.

Und jetzt raten Sie mal, was passiert, wenn Sie die Version v3.1 für die Checkout-Aktion. Der Runner wird versuchen, das Repository mit TAG = herunterzuladen. v3.1. Aber dieses Tag existiert nicht! Der Runner gibt dann eine Fehlermeldung aus, dass er diese Version nicht finden kann. Der Runner sucht also nicht von sich aus nach passenden Versionen!

- uses: actions/checkout@v3.1 <-- this will fail!

Sie können die Tags für diese Aktion finden hier und sehen, dass v3.1 fehlt! Selbst die meistgenutzte Aktion folgt also nicht den Best Practices von GitHub!!!

Noch besser, die Marktplatz für GitHub-Aktionen zeigt die Version der Tags nicht an: Es werden nur die Informationen aus den Releases im Repo angezeigt! Das bedeutet, dass Sie möglicherweise Tags übersehen, die nicht als GitHub Release veröffentlicht wurden.

Vergleichen Sie die Tag-Liste mit der auf dem Marktplatz angezeigten Veröffentlichungsliste:

Machen Sie die Nutzung von GitHub Actions sicherer

Ich habe den Leuten immer wieder gesagt, dass Tags nicht sicher sind: Der Betreuer der Aktion kann das Tag aktualisieren, so dass es auf einen anderen Commit verweist. Das bedeutet, dass Ihr Workflow einen Commit verwenden könnte, den Sie überprüft haben (das sollte immer Schritt 1 sein!), aber plötzlich aktualisiert der Betreuer der Aktion das Tag, um auf einen anderen Commit zu verweisen. Das bedeutet, dass Ihr Arbeitsablauf jetzt einen anderen Code verwendet, den Sie nicht überprüft haben! Lesen Sie mehr darüber, wie Sie bei der Verwendung von Actions sicherer werden, in diesen Blogpost.

Der Weg, dies zu beheben und Ihre Einrichtung sicherer zu machen, besteht darin, den SHA-Hash des Commits zu verwenden, den Sie verwenden möchten. Auf diese Weise können Sie den Code selbst verifizieren und wissen, dass der Code, den Sie verwenden, auch der verifizierte Code ist. Eingehende Änderungen können als Benachrichtigungen gesendet werden, indem Sie Dependabot für die github-actions Ökosystem.

Zusammenfassung

Wir sagen den Leuten nicht ohne Grund, dass sie sich an SemVer halten sollen, aber bei GitHub-Aktionen ist es die Aufgabe des Betreibers der Aktion, alle übereinstimmenden Versionen ihrer Aktion mit der korrekten SemVer-Version neu zu kennzeichnen. Und anscheinend hält sich nicht einmal GitHub an diese Vorgabe.

Wenn Sie also eine aktuelle Version haben v4.2.5müssen Sie diese Übergabe auch mit der Option v4.2 Tag, sowie das v4 Tag. Auf diese Weise kann der Läufer die richtige Version zum Herunterladen finden.

Beispiel:

jobs:
  job1:
    runs-on: ubuntu-latest
    steps:
    # works, as this is an actual tag in the repo
    - uses: actions/checkout@v3

  job2:
    runs-on: ubuntu-latest
    steps:
    # works, as this is an actual tag in the repo
    - uses: actions/checkout@v3.1.0

  job3:
    runs-on: ubuntu-latest
    steps:
    # does not work, as this is NOT an actual tag in the repo
    - uses: actions/checkout@v3.1