Speichern und Freigeben von Daten aus einem Workflow

Mit Artefakten kannst du Daten zwischen Aufträgen in einem Workflow freigeben und Daten nach Abschluss des Workflows speichern.

In diesem Artikel

Informationen zu Workflow-Artefakten

Artefakte erlauben es dir, Daten nach dem Job-Abschluss abzuspeichern und diese Daten an einen anderen Job im selben Workflow weiterzugeben. Ein Artefakt ist eine Datei oder eine Dateisammlung, die während einer Workflow-Ausführung erstellt wird. Zum Beispiel kannst du Artefakte verwenden, um deine Build- und Testausgabe zu speichern, nachdem ein Workflow-Lauf beendet ist. Alle Aktionen und Workflows, die innerhalb einer Ausführung aufgerufen werden, verfügen über Schreibzugriff für die Artefakte dieser Ausführung.

Standardmäßig speichert GitHub Enterprise Cloud Buildprotokolle und Artefakte 90 Tage lang, dieser Aufbewahrungszeitraum kann jedoch angepasst werden. Weitere Informationen findest du unter Nutzungseinschränkungen, Abrechnung und Verwaltung. Der Aufbewahrungszeitraum für einen Pull Request beginnt jedes Mal neu, wenn eine Person einen neuen Commit für den Pull Request durchführt.

Dies sind einige der gängigen Artefakte, die du hochladen kannst:

  • Protokolldateien und Coredumps
  • Testergebnisse, Fehler und Screenshots
  • Binäre oder komprimierte Dateien
  • Ergebnisse zur Stresstest-Leistungsausgabe und Codeabdeckung

Das Speichern von Artefakten verwendet Speicherplatz auf GitHub Enterprise Cloud. Die Nutzung von GitHub Actions ist für GitHub-gehostete Standardrunner in öffentlichen Repositorys und für selbstgehostete Runner kostenlos. Für private Repositorys erhält jedes GitHub-Konto eine bestimmte Menge an Freiminuten und kostenlosem Speicherplatz für die Nutzung mit von GitHub gehosteten Runnern – je nach Plan des Kontos. Jede Nutzung, die über die enthaltenen Kontingente hinausgeht, wird durch Ausgabenlimits gesteuert. Weitere Informationen findest du unter Abrechnung für GitHub Actions verwalten.

Artefakte werden während eines Workflow-Laufs hochgeladen und du kannst den Namen und die Größe eines Artefakts in der Benutzeroberfläche anzeigen. Wenn ein Artefakt mit der GitHub Enterprise Cloud-Oberfläche heruntergeladen wird, werden alle Dateien, die als Teil des Artefakts einzeln hochgeladen wurden, zusammen in eine einzige Datei gezippt. Die Abrechnung erfolgt anhand der Größe des hochgeladenen Artefakts und nicht der Größe der Zip-Datei erfolgt.

GitHub Enterprise Cloud bietet zwei Aktionen, über die du Build-Artefakte hoch- und herunterladen kannst. Weitere Informationen findest du bei den upload-artifact- und download-artifact-Aktionen .

Daten zwischen Aufträgen freigeben:

  • Hochladen von Dateien: Gib der hochgeladenen Datei einen Namen, und lade die Daten hoch, bevor der Auftrag beendet ist.
  • Herunterladen von Dateien: Du kannst nur Artefakte herunterladen, die während derselben Workflowausführung hochgeladen wurden. Wenn du eine Datei herunterlädst, kannst du sie mit Namen referenzieren.

Die Steps („Schritte“) eines Jobs teilen sich die selbe Umgebung auf der Runner-Maschine, laufen aber in ihren eigenen individuellen Prozessen. Mithilfe von Ein- und Ausgaben kannst du Daten zwischen den Schritten in einem Auftrag weitergeben. Weitere Informationen zu Ein- und Ausgaben findest du unter Metadatensyntax für GitHub Actions.

Vergleich: Artefakte v/s Zwischenspeicherung von Abhängigkeiten

Artefakte und Caching sind ähnlich, da sie die Möglichkeit bieten, Dateien auf GitHub zu speichern, aber die beiden Funktionalitäten bieten verschiedene Anwendungsfälle und dürfen nicht miteinander verwechselt werden.

  • Verwende die Zwischenspeicherung, wenn du Dateien wiederverwenden möchtest, die sich zwischen Aufträgen oder Workflowausführungen nur selten verändern, zum Beispiel Buildabhängigkeiten aus einem Paketverwaltungssystem.
  • Verwende Artefakte, wenn du von einem Auftrag generierte Dateien speichern möchtest, um diese nach einer Workflowausführung zu öffnen, zum Beispiel Binärdateien oder Buildprotokolle.

Weitere Informationen zum Zwischenspeichern von Abhängigkeiten findest du unter Abhängigkeiten zwischenspeichern um Workflows zu beschleunigen.

Build- und Testartefakte hochladen

Du kannst einen Workflow für kontinuierliche Integration (CI) erstellen, um deinen Code zu bauen und zu testen. Weitere Informationen zur Verwendung von GitHub Actions für CI findest du unter Info zu Continuous Integration mit GitHub Actions.

Durch die Ergebnisse der Erstellung und des Tests deines Codes werden oft zum Debuggen von Testfehlern einsetzbare Dateien und bereitstellbarer Produktionscode erstellt. Du kannst einen Workflow konfigurieren, um den per Push-Vorgang an dein Repository übertragenen Code zu erstellen und zu testen und um einen erfolgreichen oder fehlerhaften Status zu melden. Du kannst die Build- und Testausgabe hochladen, um sie für Bereitstellungen, zum Debuggen fehlerhafter Tests oder von Abstürzen und zum Anzeigen der Testsuite-Abdeckung zu verwenden.

Du kannst die upload-artifact-Aktion verwenden, um Artefakte hochzuladen. Beim Hochladen eines Artefakts kannst du eine einzelne Datei oder ein einzelnes Verzeichnis oder mehrere Dateien oder Verzeichnisse angeben. Du kannst auch bestimmte Dateien oder Verzeichnisse ausschließen und Platzhaltermuster verwenden. Es wird empfohlen, einen Namen für ein Artefakt anzugeben, aber wenn kein Name angegeben wird, wird artifact als Standardname verwendet. Weitere Informationen zur Syntax findest du bei der actions/upload-artifact action.

Beispiel

Zum Beispiel kann dein Projektarchiv oder eine Webanwendung SASS- und TypeScript-Dateien enthalten, die du in CSS und JavaScript konvertieren musst. Wenn du davon ausgehst, dass deine Buildkonfiguration die kompilierten Dateien in das Verzeichnis dist ausgibt, würdest du die Dateien im Verzeichnis dist auf deinem Webanwendungsserver bereitstellen, wenn alle Tests erfolgreich abgeschlossen wurden.

|-- hello-world (repository)
|   └── dist
|   └── tests
|   └── src
|       └── sass/app.scss
|       └── app.ts
|   └── output
|       └── test
|

Dieses Beispiel zeigt dir, wie du einen Workflow für ein Node.js-Projekt erstellst, der den Code im Verzeichnis src erstellt und die Tests im Verzeichnis tests ausführt. Du kannst davon ausgehen, dass die Ausführung von npm test einen Code Coverage-Bericht namens code-coverage.html erstellt, der im Verzeichnis output/test/ gespeichert wird.

Der Workflow lädt die Produktionsartefakte im Verzeichnis dist hoch, schließt jedoch alle Markdowndateien aus. Außerdem wird der code-coverage.html-Bericht als weiteres Artefakt hochgeladen.

YAML
name: Node CI

on: [push]

jobs:
  build_and_test:
    runs-on: ubuntu-latest
    steps:
      - name: Checkout repository
        uses: actions/checkout@v4
      - name: npm install, build, and test
        run: |
          npm install
          npm run build --if-present
          npm test
      - name: Archive production artifacts
        uses: actions/upload-artifact@v4
        with:
          name: dist-without-markdown
          path: |
            dist
            !dist/**/*.md
      - name: Archive code coverage results
        uses: actions/upload-artifact@v4
        with:
          name: code-coverage-report
          path: output/test/code-coverage.html

Generieren von Artefaktnachweisen für Builds

Mit Artefaktbescheinigungen können Sie fälschungssichere Herkunfts- und Integritätsgarantien für die von Ihnen entwickelte Software erstellen. Personen, die Ihre Software nutzen, können wiederum überprüfen, wo und wie Ihre Software erstellt wurde.

Wenn Sie Artefaktenachweise mit Ihrer Software generieren, erstellen Sie kryptografisch signierte Ansprüche, die die Provenienz Ihres Builds einrichten und die folgenden Informationen enthalten:

  • Eine Verknüpfung mit dem Workflow, der dem Artefakt zugeordnet ist.
  • Das Repository, die Organisation, die Umgebung, die SHA-Übertragung und das auslösende Ereignis für das Artefakt.
  • Andere Informationen aus dem OIDC-Token, die zur Feststellung der Herkunft verwendet werden. Weitere Informationen findest du unter Informationen zur Sicherheitshärtung mit OpenID Connect.

Sie können auch Artefaktnachweise generieren, die eine zugeordnete Software-Stückliste (SBOM) enthalten. Das Zuordnen Ihrer Builds zu einer Liste der darin verwendeten Open Source-Abhängigkeiten bietet Transparenz und ermöglicht es Verbrauchern, Datenschutzstandards einzuhalten.

Nach der Ausführung eines Builds können Sie unterhalb der Liste der Artefakte, die der Build erzeugt hat, auf die Bescheinigungen zugreifen.

Weitere Informationen findest du unter Verwenden von Artefaktnachweisen zur Ermittlung der Herkunft von Builds.

Konfigurieren eines benutzerdefinierten Aufbewahrungszeitraums für Artefakte

Du kannst einen benutzerdefinierten Aufbewahrungszeitraum für einzelne Artefakte definieren, die von einem Workflow erstellt wurden. Wenn du einen Workflow zum Erstellen eines neuen Artefakts verwendest, kannst du retention-days mit der upload-artifact-Aktion verwenden. In diesem Beispiel wird veranschaulicht, wie du einen benutzerdefinierten Aufbewahrungszeitraum von 5 Tagen für das Artefakt namens my-artifact festlegst:

YAML
  - name: 'Upload Artifact'
    uses: actions/upload-artifact@v4
    with:
      name: my-artifact
      path: my_file.txt
      retention-days: 5

Der retention-days-Wert darf den vom Repository, der Organisation oder dem Unternehmen festgelegten Aufbewahrungsgrenzwert nicht überschreiten.

Artefakte herunterladen oder löschen

Während einer Workflowausführung kannst du die download-artifact-Aktion verwenden, um Artefakte herunterzuladen, die zuvor in derselben Workflowausführung hochgeladen wurden.

Nach Abschluss einer Workflowausführung kannst du Artefakte auf GitHub oder mithilfe der REST-API herunterladen oder löschen. Weitere Informationen findest du unter Herunterladen von Workflowartefakten, Entfernen von Workflowartefakten und REST-API-Endpunkte für GitHub-Actions-Artefakte.

Herunterladen von Artefakten während einer Workflowausführung

Die actions/download-artifact-Aktion kann verwendet werden, um zuvor hochgeladene Artefakte während einer Workflowausführung herunterzuladen.

Hinweis: Du kannst nur Artefakte in einem Workflow herunterladen, die während derselben Workflowausführung hochgeladen wurden.

Gib den Namen eines Artefaktes an, um ein einzelnes Artefakt herunterzuladen. Wenn du ein Artefakt hochgeladen hast, ohne einen Namen anzugeben, lautet der Standardname artifact.

- name: Download a single artifact
  uses: actions/download-artifact@v4
  with:
    name: my-artifact

Du kannst auch alle Artefakte in einer Workflowausführung herunterladen, indem du keinen Namen angibst. Dies kann nützlich sein, wenn du mit zahlreichen Artefakten arbeitest.

- name: Download all workflow run artifacts
  uses: actions/download-artifact@v4

Wenn du die Artefakte aller Workflowausführungen herunterlädst, wird ein Verzeichnis für jedes Artefakt unter Verwendung seines Namens erstellt.

Weitere Informationen zur Syntax findest du in der actions/download-artifact action.

Übergeben von Daten zwischen Aufträgen in einem Workflow

Du kannst die Aktionen upload-artifact und download-artifact verwenden, um Daten zwischen Aufträgen in einem Workflow freizugeben. In diesem Beispiel-Workflow wird veranschaulicht, wie Daten zwischen Aufträgen im selben Workflow weitergegeben werden. Weitere Informationen findest du unter actions/upload-artifact- und download-artifact-Aktionen .

Von den Artefakten eines vorherigen Auftrags abhängige Aufträge müssen auf den erfolgreichen Abschluss des abhängigen Auftrags warten. Dieser Workflow verwendet das needs-Schlüsselwort, um sicherzustellen, dass job_1, job_2 und job_3 sequenziell ausgeführt werden. job_2 erfordert z. B. job_1 mit der needs: job_1-Syntax.

Auftrag 1 führt die folgenden Schritte durch:

  • Führt eine mathematische Berechnung aus und speichert das Ergebnis in einer Textdatei namens math-homework.txt.
  • Verwendet die upload-artifact-Aktion zum Hochladen der math-homework.txt-Datei mit dem Artefaktnamen homework_pre.

Auftrag 2 verwendet das Ergebnis des vorherigen Auftrags:

  • Lädt das homework_pre endif %}-Artefakt herunter, das im vorherigen Auftrag hochgeladen wurde. Die Aktion download-artifact lädt die Artefakte standardmäßig in das Arbeitsbereichverzeichnis herunter, in dem der Schritt ausgeführt wird. Du kannst den Eingabeparameter path verwenden, um ein anderes Downloadverzeichnis anzugeben.
  • Liest den Wert in der Datei math-homework.txt, führt eine mathematische Berechnung aus, und speichert das Ergebnis erneut in math-homework.txt, wobei der Inhalt überschrieben wird.
  • Lädt die Datei math-homework.txt hoch. Da Artefakte in v4 als unveränderlich gelten, wird dem Artefakt ein anderer Input, homework_final, als Name übergeben.

Auftrag 3 zeigt das im vorherigen Auftrag hochgeladene Ergebnis an:

  • Lädt das homework_final-Artefakt von Job 2.
  • Gibt das Ergebnis der mathematischen Gleichung im Protokoll aus.

Die vollständige, in diesem Workflow-Beispiel durchgeführte mathematische Operation lautet (3 + 7) x 9 = 90.

YAML
name: Share data between jobs

on: [push]

jobs:
  job_1:
    name: Add 3 and 7
    runs-on: ubuntu-latest
    steps:
      - shell: bash
        run: |
          expr 3 + 7 > math-homework.txt
      - name: Upload math result for job 1
        uses: actions/upload-artifact@v4
        with:
          name: homework_pre
          path: math-homework.txt

  job_2:
    name: Multiply by 9
    needs: job_1
    runs-on: windows-latest
    steps:
      - name: Download math result for job 1
        uses: actions/download-artifact@v4
        with:
          name: homework_pre
      - shell: bash
        run: |
          value=`cat math-homework.txt`
          expr $value \* 9 > math-homework.txt
      - name: Upload math result for job 2
        uses: actions/upload-artifact@v4
        with:
          name: homework_final
          path: math-homework.txt

  job_3:
    name: Display results
    needs: job_2
    runs-on: macOS-latest
    steps:
      - name: Download math result for job 2
        uses: actions/download-artifact@v4
        with:
          name: homework_final
      - name: Print the final result
        shell: bash
        run: |
          value=`cat math-homework.txt`
          echo The result is $value

Die Workflowausführung archiviert alle von ihr generierten Artefakte. Weitere Informationen zum Herunterladen archivierter Artefakte findest du unter Herunterladen von Workflowartefakten.

Weiterführende Themen