Speichern von Workflowdaten als Artefakte

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 Server 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

Artefakte verbrauchen Speicherplatz in dem externen Blobspeicher, der für GitHub Actions auf Ihre GitHub Enterprise Server-Instance konfiguriert ist.

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 Server-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 Server bietet zwei Aktionen, über die du Build-Artefakte hoch- und herunterladen kannst. Weitere Informationen findest du bei den upload-artifact- und download-artifact-Aktionen auf Ihre GitHub Enterprise Server-Instance.

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 Informationen zur fortlaufenden Integration.

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-Aktion auf Ihre GitHub Enterprise Server-Instance.

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.

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@v3
        with:
          name: dist-without-markdown
          path: |
            dist
            !dist/**/*.md
      - name: Archive code coverage results
        uses: actions/upload-artifact@v3
        with:
          name: code-coverage-report
          path: output/test/code-coverage.html

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@v3
        with:
          name: dist-without-markdown
          path: |
            dist
            !dist/**/*.md
      - name: Archive code coverage results
        uses: actions/upload-artifact@v3
        with:
          name: code-coverage-report
          path: output/test/code-coverage.html

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:

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

  - name: 'Upload Artifact'
    uses: actions/upload-artifact@v3
    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.

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@v3
  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@v3

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 bei der actions/download-artifact-Aktion auf Ihre GitHub Enterprise Server-Instance.

Ü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 bei den actions/upload-artifact- und download-artifact-Aktionen auf Ihre GitHub Enterprise Server-Instance.

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.

Auftrag 2 verwendet das Ergebnis des vorherigen Auftrags:

• Lädt das homework 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. Dieser Upload überschreibt das zuvor hochgeladene Artefakt, da sie denselben Namen haben.

Auftrag 3 zeigt das im vorherigen Auftrag hochgeladene Ergebnis an:

• Lädt das homework-Artefakt.
• 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.

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@v3
        with:
          name: homework
          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@v3
        with:
          name: homework
      - 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@v3
        with:
          name: homework
          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@v3
        with:
          name: homework
      - name: Print the final result
        shell: bash
        run: |
          value=`cat math-homework.txt`
          echo The result is $value

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@v3
        with:
          name: homework
          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@v3
        with:
          name: homework
      - 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@v3
        with:
          name: homework
          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@v3
        with:
          name: homework
      - 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.