pinact: GitHub Actions und wiederverwendbare Workflows auf Commit-SHAs festlegen

Aktionsreferenzen auf vollständige Commit-SHAs umschreiben

pinact ist ein Kommandozeilenwerkzeug, das GitHub-Workflow- und Composite-Action-Dateien bearbeitet, um Versions-Tags oder kurze SHAs durch vollständige Commit-SHAs zu ersetzen. Das README zeigt einen Diff, in dem `actions/checkout@v3` zu `actions/checkout@83b7061638ee4956cf7545a6f7efe594e5ad0247 # v3.5.1` wird, und wiederverwendbare Workflow-Referenzen werden ähnlich umgeschrieben. pinact fügt nach dem SHA auch einen Versionskommentar hinzu, wie `# v3.5.1`. Laut den Repository-Metadaten ist das Tool in Go geschrieben. Neben Workflow-Dateien kann pinact beliebige Textdateien verarbeiten, was laut README nützlich ist, um Aktionsbeispiele in Dokumenten wie README.md zu fixen.

Ausführungsmodi: Bearbeiten, Prüfen und Aktualisieren

Standardmäßig bearbeitet `pinact run` Dateien direkt. Wenn keine Dateiargumente angegeben werden, sucht es nach `.github/workflows/*.yml` und `.yaml` sowie nach action.yml- und action.yaml-Dateien im Stammverzeichnis und in bis zu drei Ebenen verschachtelten Verzeichnissen. Die Übergabe von `-check` oder `-fix=false` bewirkt, dass pinact nur meldet, ob Aktionen gepinnt sind, ohne Dateien zu ändern. Das `-no-api`-Flag führt eine Offline-Prüfung durch, die nur die 40-Zeichen-SHA-Syntax überprüft; da es die GitHub-API nicht abfragen kann, kann es keine Aktionen pinnen, sondern nur vorhandene Pins prüfen. Das `-update`-Flag ändert das Verhalten, um die neuesten Versionen von Aktionen abzurufen und die Referenzen entsprechend zu aktualisieren. Diese Modi können mit anderen Optionen wie der Filterung nach minimalem Veröffentlichungsalter kombiniert werden.

Versionskommentare und minimales Veröffentlichungsalter verifizieren

pinact kann verifizieren, dass Versionskommentare, die an SHA-Pins angehängt sind, mit der tatsächlichen Version übereinstimmen, die aus dem SHA aufgelöst wird. Das README verweist für die genauen Regeln auf ein separates Dokument, aber das `-verify-comment`-Flag aktiviert diese Prüfung. Das Tool unterstützt außerdem ein minimales Veröffentlichungsalter ("Cooldown"), um die Verwendung sehr neuer Releases zu vermeiden. Es gibt zwei Arten von Prüfungen: die Verifizierung aktueller Versionen und das Filtern neuer Versionen während eines Updates. Das `-min-age`-Flag setzt das Alter in Tagen, und die Konfiguration kann über `.min_age` und `.rules[].min_age` einen Standardwert oder einen regel spezifischen Wert festlegen. Das README weist darauf hin, dass die Verifizierung aktueller Versionen nur ausgeführt wird, wenn `-verify-min-age` gesetzt ist oder `.min_age.always` true ist, um redundante API-Aufrufe zu vermeiden. Bei Tags wird das Committer-Datum des Commits geprüft, was einen zusätzlichen API-Aufruf erfordert.

Branches pinnen und bestimmte Aktionen auswählen

Standardmäßig pinnt pinact keine Branch-Referenzen wie `main` oder `master`. Die seit v3.10.0 verfügbare Option `--branch-to-tag` ermöglicht es Benutzern, bestimmte Branches durch Angabe eines regulären Ausdrucks zu pinnen. Der Branch wird in das neueste stabile Tag der Aktion umgewandelt, wobei Vorabversionen nur verwendet werden, wenn kein stabiles Tag existiert. Die Option kann wiederholt angegeben werden und respektiert `--min-age`, sodass Tags, die innerhalb des Cooldown-Fensters veröffentlicht wurden, übersprungen werden. Zur Auswahl der zu verarbeitenden Aktionen akzeptieren `-include` und `-exclude` (oder `-i` und `-e`) reguläre Ausdrücke und können mehrfach verwendet werden, um das Pinnen auf eine Teilmenge von Aktionsreferenzen zu beschränken.

Ausgabeformate und inkrementelles Pinnen

pinact kann mit `--format sarif` eine SARIF-Ausgabe erzeugen. Dieses Format ist nützlich für die Integration mit reviewdog und GitHub SARIF-Code-Scanning. Wenn die SARIF-Ausgabe ausgewählt wird, ist `-fix=false` impliziert, sodass Dateien nur geändert werden, wenn auch `-fix` übergeben wird. Das README zeigt, wie die SARIF-Ausgabe an reviewdog mit dem Reporter `github-pr-review` weitergeleitet und die erzeugte sarif.json mit der Aktion `github/codeql-action/upload-sarif` hochgeladen wird. Für die schrittweise Einführung akzeptiert `-diff-file` eine Unified-Diff-Datei und beschränkt das Pinnen auf die in diesem Diff geänderten Zeilen. Der Diff kann mit `-diff-file -` von der Standardeingabe gelesen werden, und das README schlägt vor, den Diff mit `pr-unified-diff-action` zu erzeugen.

Konfiguration und Zugriffstoken-Verwaltung

pinact unterstützt Konfigurationsdateien mit den Namen `.pinact.yaml`, `.github/pinact.yaml`, `.pinact.yml` oder `.github/pinact.yml`. Die Datei ist optional; zusätzlich kann eine globale Konfigurationsdatei für benutzerweite Standardwerte verwendet werden. Befehlszeilenoptionen haben Vorrang vor Umgebungsvariablen, die wiederum Vorrang vor der lokalen Konfiguration haben, die Vorrang vor der globalen Konfiguration hat. Der Befehl `pinact init` erzeugt eine Konfigurationsdatei. Für den GitHub-API-Zugriff liest pinact die Umgebungsvariable `PINACT_GITHUB_TOKEN` oder `GITHUB_TOKEN`. Es kann Token auch über einen Schlüsselbund (Windows Credential Manager, macOS Keychain oder GNOME Keyring) verwalten, wenn `PINACT_KEYRING_ENABLED` gesetzt ist, oder über die Integration mit `ghtkn` GitHub-App-Benutzerzugriffstoken erstellen.

Exit-Codes und die Begründung für das Pinnen

Das README definiert vier Exit-Codes: 0 bedeutet, alles ist gepinnt oder pinact hat es repariert; 1 bedeutet, dass `-fix=false` gesetzt wurde und etwas gepinnt werden muss; 2 zeigt an, dass eine Aktion nicht automatisch repariert werden kann, z. B. eine Branch-Referenz, fehlender Versionskommentar, `-verify-comment`-Missmatch oder `-min-age`-Verletzung; 3 umfasst GitHub-API-Fehler, ungültige CLI-Flag-Kombinationen oder andere unerwartete Fehler. Der Abschnitt zur Motivation zitiert die GitHub-Dokumentation zur Sicherheitshärtung, die besagt, dass das Pinnen einer Aktion an einen vollständigen Commit-SHA der einzige Weg ist, eine Aktion als unveränderliches Release zu verwenden, wodurch das Risiko verringert wird, dass ein Angreifer eine Hintertür einbaut. pinact pinnt standardmäßig keine Branches, und das README erklärt den Grund in einem separaten Dokument.

Redaktionelles Fazit

pinacts Design konzentriert sich darauf, SHA-Fixing zur Routine zu machen: Es bearbeitet standardmäßig Dateien, bietet einen Validierungsmodus für CI und einen separaten Aktualisierungsmodus. Die Exit-Codes sind für die Automatisierung definiert, und die Option für das minimale Veröffentlichungsalter gibt Teams die Möglichkeit, nicht sofort sehr neue Releases zu übernehmen. Das Projekt ist unter MIT lizenziert, aber die Lizenz gewährt nur die Erlaubnis, die Software zu verwenden und zu modifizieren; sie macht keine Zusagen zu Sicherheit, Support oder Garantie.

Offizielle Quellen

1. Official README
2. Project repository
3. Release notes