Verwenden von benutzerdefinierten Bildern

Benutzerdefinierte Images

Sie können ein benutzerdefiniertes Image erstellen, um die genaue Umgebung zu definieren, die Sie GitHub-gehostete große Runner verwenden. Mit benutzerdefinierten Images können Sie Tools, Abhängigkeiten und Konfigurationen vorinstallieren, um Workflows zu beschleunigen und die Konsistenz bei allen Aufträgen zu verbessern.

Wenn Ihr Runner ein benutzerdefiniertes Image verwendet, fungiert es als vorgewärmte Umgebung, wodurch Workflows schneller abgeschlossen werden können. Dies geschieht, indem Pakete und Binärdateien einmal während der Erstellung des Images heruntergeladen werden, anstatt jedes Mal, wenn ein Workflow ausgeführt wird. Weitere Informationen zu benutzerdefinierten Bildern finden Sie unter Runner-Bilder.

Der Prozess der Verwendung eines benutzerdefinierten Images umfasst drei Hauptschritte: 1. Einrichten eines Image-Generation-Läufers: Erstellen Sie einen größerer Runner zum Erstellen und Speichern Ihres benutzerdefinierten Images. 1. Generieren eines benutzerdefinierten Bilds: Generieren Sie Ihr benutzerdefiniertes Bild, indem Sie einen Workflow mithilfe des Läufers der Imagegenerierung ausführen. 1. Installieren von benutzerdefinierten Images: Erstellen Sie einen Läufer, der Ihr benutzerdefiniertes Image verwendet.

Voraussetzungen

Bevor Sie benutzerdefinierte Bilder erstellen können, stellen Sie sicher, dass die folgenden Anforderungen erfüllt sind.

Richtlinie: Benutzerdefinierte Images müssen für Ihre Organisation oder Ihr Unternehmen aktiviert sein. Unternehmensbesitzer können den Zugriff auf benutzerdefinierte Bilder verwalten und Aufbewahrungsrichtlinien in den Richtlinieneinstellungen für Aktionen festlegen. Weitere Informationen finden Sie unter Erzwingen von Richtlinien für GitHub Actions in Ihrem Unternehmen.
Berechtigungen: Zum Erstellen und Verwalten von benutzerdefinierten Images müssen Sie ein Organisations- oder Unternehmensinhaber sein oder über die CI/CD Admin Rolle verfügen oder über eine Rolle mit den folgenden fein abgestimmten Berechtigungen verfügen.
- Angepasste Images von gehosteten Runnern der Organisation anzeigen
- Verwaltung von benutzerdefinierten Runner-Images, die von der Organisation gehostet werden
- Runner und Runner-Gruppen der Organisation verwalten
Weitere Informationen finden Sie unter Berechtigungen von benutzerdefinierten Organisationsrollen.

Einrichten eines Bildgenerierungs-Läufers

Um ein angepasstes Image zu erstellen, musst du zunächst einen Image-generierenden Runner einrichten. Wenn Sie den Läufer erstellen, muss die Plattform, die Sie für Ihren Läufer auswählen, mit der Plattform des Images übereinstimmen, das Sie erstellen möchten. Die Plattform des Läufers kann Linux x64, Linux ARM64 oder Windows x64 sein.

Erstellen von größerer Runner:
- Für Organisationen, siehe Hinzufügen eines größeren Runners zu einer Organisation.
- Für Unternehmen, siehe Hinzufügen eines größeren Runners zu einem Unternehmen.
Wähle bei der Konfiguration des Runners die folgenden Konfigurationen für deinen Image-generierenden Runner:
- Plattform: Wählen Sie eine unterstützte Plattform aus, die der Plattform des Images entspricht, das Sie erstellen möchten (Linux x64, Linux ARM64 oder Windows x64).
- Bild: Wählen Sie ein Bild aus, auf dem Sie aufbauen möchten, und aktivieren Sie dann das Kontrollkästchen Aktivieren Sie diesen Läufer, um benutzerdefinierte Bilder zu generieren.
  - Sie können mit einem GitHubeigenen Image beginnen oder ein Basisimage auswählen, um mit einem sauberen Betriebssystem zu beginnen.
  - Für ARM64-Plattformen können Sie auch ein ARM-verwaltetes Image mit vorinstallierten Tools auswählen.
- Runner-Gruppe: Wählen Sie die Gruppe für Ihren Läufer aus, der Mitglied sein soll. Nachdem das benutzerdefinierte Bild erstellt wurde, können nur Läufer in dieser Läufergruppe neue Versionen dieses Bilds generieren.

Generieren eines benutzerdefinierten Bilds

Nachdem Sie einen Läufer der Imagegenerierung erstellt haben, führen Sie einen Workflow aus, der das snapshot Schlüsselwort enthält, um ein benutzerdefiniertes Image zu generieren.

So konfigurieren Sie einen Workflow für die Bildgenerierung:

Legen Sie den runs-on Wert auf den Namen des von Ihnen erstellten Bildgenerierungsläufers fest.
Füge dem Job das Schlüsselwort snapshot hinzu, indem du entweder die Zeichenfolge oder die Zuordnung wie unten gezeigt verwendest.
- Jeder Auftrag, der das snapshot Schlüsselwort enthält, erstellt ein separates Bild. Um nur eine Bild- oder Bildversion zu generieren, fügen Sie alle Workflowschritte in einen einzigen Auftrag ein.
- Jede erfolgreiche Ausführung eines Auftrags, der das snapshot Schlüsselwort enthält, erstellt eine neue Version dieses Images.

Hinweis

          GitHub empfiehlt, die Bildgenerierung wöchentlich als geplanten Workflow zu konfigurieren. Durch diesen Ansatz wird sichergestellt, dass Abhängigkeiten up-to-datum bleiben und über die neuesten Sicherheitspatches verfügen. Weitere Informationen finden Sie unter [AUTOTITLE](/actions/using-workflows/events-that-trigger-workflows#schedule).

Es kann einige Zeit dauern, bis Ihr Bild vollständig generiert und nach Abschluss des Workflows verwendet werden kann. Die Bereitstellungszeit variiert je nach Läufergröße und -konfiguration und kann mehrere Stunden für größere Läufer dauern.

Das Bild wird nur generiert, wenn der Auftrag erfolgreich abgeschlossen wird. Dadurch wird verhindert, dass neue Bildversionen erstellt werden, wenn ein Workflow fehlschlägt oder in einem unvollständigen Zustand endet.

Sobald das Bild generiert wurde, steht es für die Verwendung in Ihren Workflows zur Verfügung. Weitere Informationen zum Verwalten von benutzerdefinierten Bildern finden Sie unter Verwalten von benutzerdefinierten Bildern.

String-Syntax

Sie können die Zeichenfolgensyntax snapshot verwenden, um den Bildnamen zu definieren. Diese Methode erstellt ein neues Bild oder fügt einer bestehenden Bilddatei mit demselben Namen eine neue Version hinzu. Sie können mit dieser Syntax keine Versionsnummer angeben.

jobs: 
  build:
    runs-on: my-image-generation-runner
    snapshot: my-custom-image
    steps:
      # Add any steps to download and setup any dependencies here

Syntax der Zuordnung

Sie können die Zuordnungssyntax snapshot verwenden, um sowohl die image-name als auch die optionale versionzu definieren. Wenn du eine Hauptversion angibst, wird die Versionsverwaltung automatisch erhöht, wenn diese Hauptversion bereits existiert. Patchversionen werden nicht unterstützt.

jobs: 
  build:
    runs-on: my-image-generation-runner
    snapshot: 
        image-name: my-custom-image
        version: 2.*
    steps:
      # Add any steps to download and setup any dependencies here

Versionsverwaltung

Wenn Sie benutzerdefinierte Bilder generieren, weist GitHub automatisch Versionsnummern zu, um Updates zu verwalten und den Bildverlauf nachzuverfolgen.

Standardverhalten

Wenn ein Bild mit dem angegebenen Namen in Ihrer Organisation oder Ihrem Unternehmen nicht vorhanden ist, GitHub wird es mit der ersten Versionsnummer 1.0.0 erstellt. Wenn bereits ein Bild mit demselben Namen vorhanden ist, erstellt GitHub eine neue Version, indem die Nebenversionsnummer erhöht wird (z. B. 1.1.0, 1.2.0 usw.).

Wenn Sie keine Version in Ihrer YAML-Datei angeben, verwendet die Bildgenerierung dieses Standardverhalten.

Angeben einer Version in Ihrem Workflow

Wenn Sie eine Version in die YAML-Zuordnung einschließen, GitHub wird zuerst die Hauptversionsnummer überprüft.

Wenn die angegebene Hauptversion bereits vorhanden ist, verwendet das neue Image die nächste Nebenversion (z. B. 1.0 wird 1.1).
Wenn die Hauptversion nicht vorhanden ist, GitHub wird eine neue Hauptversion erstellt (z. B. 2.0).

Patchversionen werden nicht unterstützt.

Neuestes Tag

Der letzte Workflow, der für ein Bild ausgeführt wird, wird immer als neueste markiert. Wenn Sie eine ältere Hauptversion im YAML angeben (z. B. Version: 1.* wenn eine 2.0-Version vorhanden ist), GitHub wird eine neue Nebenversion unter der älteren Hauptversion generiert und als neueste gekennzeichnet.

Hinweis

          GitHub-gehostet großer Runner Die Erstellung unterstützt keine Wildcards in der Bildversionsauswahl.

Abrechnung und Speicher für benutzerdefinierte Bilder

Aufträge, die benutzerdefinierte Bilder verwenden, werden mit derselben Rate pro Minute abgerechnet wie diejenigen, die das Bild verwenden. Der Speicher für benutzerdefinierte Bilder wird separat über den GitHub Actions-Speicherdienst abgerechnet.

Wenn Sie Bilder häufig neu erstellen und ältere Versionen beibehalten, kann die Speicherauslastung schnell zunehmen, da jeder erfolgreiche Workflowauftrag, der das snapshot Schlüsselwort enthält, eine neue Imageversion erstellt. Weitere Informationen findest du unter Abrechnung für GitHub Actions und Erzwingen von Richtlinien für GitHub Actions in Ihrem Unternehmen.

Verwalten von benutzerdefinierten Bildern

Sie können detaillierte Informationen zu jedem Bild anzeigen, nicht verwendete Bilder oder bestimmte Versionen löschen und Bildversionen im Laufe der Zeit nachverfolgen.

Navigieren Sie auf GitHub zur Hauptseite der Organisation.
Klicke unter dem Organisationsnamen auf Settings. Wenn die Registerkarte „Einstellungen“ nicht angezeigt wird, wähle im Dropdownmenü die Option Einstellungen aus.
Klicken Sie in der linken Randleiste auf Aktionen, und klicken Sie dann auf "Benutzerdefinierte Bilder".
Auf der Seite "Benutzerdefinierte Bilder" können Sie alle benutzerdefinierten Bilder anzeigen, die in Ihrer Organisation oder Ihrem Unternehmen erstellt wurden.
Wenn Sie Details zu einem bestimmten Bild anzeigen möchten, klicken Sie auf den Bildnamen.

Installieren von benutzerdefinierten Images

Sobald Ihr benutzerdefiniertes Image fertig ist, können Sie es auf einem neuen GitHub-gehostet großer Runner installieren.

Folgen Sie den Schritten zum Erstellen eines größerer Runner:
- Für Organisationen, siehe Hinzufügen eines größeren Runners zu einer Organisation.
- Für Unternehmen, siehe Hinzufügen eines größeren Runners zu einem Unternehmen.
Beim Konfigurieren des Läufers:
- Plattform: Wählen Sie dieselbe Plattform aus, die Sie zum Generieren des Images verwendet haben (Linux x64, Linux ARM64 oder Windows x64).
- Bild: Wählen Sie die Registerkarte "Benutzerdefiniert " und dann ihr benutzerdefiniertes Bild aus der Liste aus.
  - Wenn Ihr Bild nicht angezeigt wird, stellen Sie sicher, dass Sie die richtige Plattform ausgewählt haben und dass Sie den Läufer auf derselben Ebene (Organisation oder Unternehmen) erstellen, auf der das Image generiert wurde.
- Bildversion: Wählen Sie "Neueste Version" aus, um die neueste Version automatisch zu verwenden, oder wählen Sie eine bestimmte Versionsnummer aus, um den Läufer an diese Version anzuheften.
  - Wenn du Latest auswählst, wird dein Runner automatisch aktualisiert, wenn eine neue Version des Images verfügbar ist. Wenn Sie den Runner auf eine bestimmte Version festlegen, müssen Sie ihn manuell bearbeiten, um ihn später zu aktualisieren.
- Größe: Wähle eine Runner-Größe mit gleichem oder größerem Storage als die Größe deines Images. Wenn das Image zum Beispiel auf einem 8-Core Runner generiert wurde, wähle einen 8-Core oder größer, um das Image auszuführen.
- Runner group: Ordnen Sie den Runner einer Runner-Gruppe zu, die mit den Repositories geteilt wird, die dieses Image verwenden müssen.

Legen Sie in Ihrem GitHub Actions Workflowauftrag den runs-on Schlüssel auf den Namen Ihres Runners fest.

jobs: 
  build:
    runs-on: my-custom-runner
    steps:
    # Add any steps for your workflow here

Führen Sie Ihren Workflow aus, um zu überprüfen, ob er erfolgreich abgeschlossen wurde. Die Auftragsprotokolle zeigen den Bildnamen und die Version im Abschnitt "Auftrag einrichten" an.

Bewährte Methoden für sicherheit für benutzerdefinierte Bilder

Um nicht autorisierte Änderungen an Ihren Bildern zu verhindern, befolgen Sie diese bewährten Methoden.

Verwenden Sie dedizierte Läufergruppen für die Bildgenerierung. Runner, die Produktionsimages generieren, müssen innerhalb einer speziellen Runner-Gruppe verbleiben. Teilen Sie Runner-Gruppen nicht zwischen Produktions- und Entwicklungs- oder Testrepositorys, da jeder, der Zugriff auf eine Entwicklung oder ein Testrepository hat, schädlichen Code in ein Produktionsimage einfügen könnte.
Öffentliche Repositorien dürfen keinen Zugriff auf Image-Generierungsrunner haben. Beschränke die Repositorys, die Runner zu Imagegenerierung verwenden können, auf diejenigen, für die sie benötigt werden, und überprüfe regelmäßig den Zugriff.
Wenden Sie die geringsten Berechtigungen auf Repositorys an. Vermeide organisationsweiten write Zugriff auf Repositorys, die Zugang zu Runnern für die Imagegenerierung haben. Da Bilder aus jeder Verzweigung generiert werden können, kann jeder mit Schreibzugriff eine Verzweigung mit beliebigem Code erstellen und die Bildgenerierung auslösen.

Wer kann dieses Feature verwenden?

In diesem Artikel