github pages deploy action
v4.7.2
Bereiten Sie Ihr Projekt automatisch mit GitHub -Aktionen auf Github -Seiten ein. Diese Aktion kann so konfiguriert werden, dass Sie Ihren produktionsbereiten Code in eine beliebige Filiale drücken, einschließlich GH-Seiten und Dokumenten . Es kann auch Cross -Repository -Bereitstellungen verarbeiten und funktioniert auch mit Github Enterprise.
Die Wartung dieses Projekts wird von allen Mitwirkenden und Sponsoren ermöglicht. Wenn Sie dieses Projekt sponsern möchten und Ihr Avatar- oder Firmenlogo unten erscheinen lassen möchten, klicken Sie hier. ?
Sie können die Aktion in Ihren Workflow aufnehmen, um jedes Ereignis auszulösen, das GitHub -Aktionen unterstützt. Wenn die Remote -Zweigstelle, die Sie bereitstellen möchten, nicht vorhanden ist, erstellt die Aktion sie für Sie. Ihr Workflow muss auch den actions/checkout Kasse einbeziehen, bevor dieser Workflow ausgeführt wird, damit die Bereitstellung funktioniert. Wenn Sie beabsichtigen, mehrere Bereitstellungen in schneller Folge vorzunehmen, müssen Sie möglicherweise den Parameter Parallelität in Ihrem Workflow nutzen, um Überlappungen zu verhindern.
Sie können unten ein Beispiel dafür anzeigen.
name : Build and Deploy
on : [push]
permissions :
contents : write
jobs :
build-and-deploy :
concurrency : ci-${{ github.ref }} # Recommended if you intend to make multiple deployments in quick succession.
runs-on : ubuntu-latest
steps :
- name : Checkout ?️
uses : actions/checkout@v4
- name : Install and Build ? # This example project is built using npm and outputs the result to the 'build' folder. Replace with the commands required to build your project, or remove this step entirely if your site is pre-built.
run : |
npm ci
npm run build
- name : Deploy
uses : JamesIves/github-pages-deploy-action@v4
with :
folder : build # The folder the action should deploy. Notiz
Sie müssen Ihr Repository so konfigurieren, dass Sie aus dem Zweig bereitstellen, auf den Sie drücken. Gehen Sie dazu zu Ihren Repository -Einstellungen, klicken Sie auf Pages und wählen Sie Deploy from a Branch über die Dropdown Source aus. Wählen Sie von dort die Filiale aus, die Sie der Aktion zur Verfügung gestellt haben. In den meisten Fällen sind dies gh-pages , da dies der Standard ist.
Wenn Sie es schaffen möchten, dass der Workflow nur für Push -Ereignisse in bestimmte Zweige auslöst, können Sie den on ändern.
on :
push :
branches :
- main Warnung
Wenn Sie die Aktion nicht mit einem Zugriffstoken oder einem SSH -Schlüssel angeben, müssen Sie auf die Einstellungen auf Ihre Repositories zugreifen und Read and Write Permissions an das bereitgestellte GITHUB_TOKEN bereitstellen, ansonsten werden Sie möglicherweise auf Erlaubnisprobleme stoßen. Alternativ können Sie Folgendes in Ihrer Workflow -Datei festlegen, um der Aktion die Berechtigungen zu erteilen, die sie benötigt.
permissions :
contents : write Der with einem Teil des Workflows muss konfiguriert werden, bevor die Aktion funktioniert. Sie können diese in den in den obigen Beispielen gefundenen with hinzufügen. Auf die secrets müssen mit der Klammersyntax verwiesen und im Menü Settings/Secrets des Github -Repositorys" gespeichert werden. Weitere Informationen zum Festlegen von Umgebungsvariablen mit GitHub -Aktionen finden Sie hier.
Die folgenden Optionen müssen konfiguriert werden, um eine Bereitstellung vorzunehmen.
| Schlüssel | Wertinformationen | Typ | Erforderlich |
|---|---|---|---|
folder | Der Ordner in Ihrem Repository, den Sie bereitstellen möchten. Wenn Ihr Build -Skript in ein Verzeichnis namens build zusammenfasst, würden Sie es hier einstellen. Wenn Sie das Root -Verzeichnis bereitstellen möchten, können Sie a platzieren . Hier. Sie können auch absolute Dateipfade verwenden, indem Sie ~ auf Ihren Ordnerpfad vorbereiten. Beachten Sie, dass alle Dateien/Ordner, die mit .gitignore -Einträgen entsprechen, nicht bereitgestellt werden. Einige Tools generieren automatisch eine .gitignore Datei für die Build-Ausgabe. | with | Ja |
Standardmäßig benötigt die Aktion keine Token -Konfiguration und verwendet das bereitgestellte Github -Token von Repository Scoped, um die Bereitstellung vorzunehmen. Wenn Sie mehr Anpassung benötigen, können Sie den Bereitstellungstyp mit den folgenden Optionen ändern.
| Schlüssel | Wertinformationen | Typ | Erforderlich |
|---|---|---|---|
token | Diese Option ist standardmäßig mit dem auf dem repository Scoped Github Token. Wenn Sie jedoch weitere Berechtigungen für Dinge wie die Bereitstellung für ein anderes Repository benötigen, können Sie hier ein persönliches Zugriffs -Token (PAT) hinzufügen. Dies sollte im secrets / with dem Menü als Geheimnis gespeichert werden. Wir empfehlen, ein Servicekonto mit den geringsten Berechtigungen zu verwenden, und empfehlen, eine neue Pat zu generieren, die Sie mit den erforderlichen geringsten Berechtigungsbereichen auswählen. Erfahren Sie hier mehr über das Erstellen und Verwenden verschlüsselter Geheimnisse. | with | NEIN |
ssh-key | Sie können die Aktion für die Bereitstellung mit SSH konfigurieren, indem Sie diese Option auf einen privaten SSH -Schlüssel einstellen, der als Geheimnis gespeichert ist. Es kann auch auf true eingestellt werden, um eine vorhandene SSH -Client -Konfiguration zu verwenden. Weitere Informationen zum Hinzufügen Ihres öffentlichen/privaten SSH -Schlüsselpaares finden Sie im Bereich "öffentliches SSH -TSSH) bitte in den Abschnitt" Bereitstellungsschlüssel "dieses Readme. | with | NEIN |
| Schlüssel | Wertinformationen | Typ | Erforderlich |
|---|---|---|---|
branch | Dies ist die Filiale, die Sie beispielsweise auf gh-pages oder docs bereitstellen möchten. Standardeinstellungen zu gh-pages . | with | NEIN |
git-config-name | Ermöglicht das Anpassen des Namens, der der GIT -Konfiguration angehängt ist, die beim Drücken der Bereitstellungs -Commits verwendet wird. Wenn dies nicht enthalten ist, wird der Name im GitHub -Kontext verwendet, gefolgt vom Namen der Aktion. | with | NEIN |
git-config-email | Ermöglicht das Anpassen der E -Mail, die an die GIT -Konfiguration angehängt ist, die beim Drücken der Bereitstellungs -Commits verwendet wird. Wenn dies nicht enthalten ist, wird die E -Mail im GitHub -Kontext verwendet, gefolgt von einer generischen Noreply -Github -E -Mail. Sie können <> für den Wert einfügen, wenn Sie dieses Feld insgesamt weglassen und die Commits ohne E -Mail überschreiten möchten. | with | NEIN |
repository-name | Ermöglicht Ihnen einen anderen Repository -Pfad an, solange Sie die Berechtigungen haben, um ihn zu drängen. Dies sollte so formatiert werden: JamesIves/github-pages-deploy-action . Sie müssen eine PAT in der token -Eingabe verwenden, damit diese Konfigurationsoption ordnungsgemäß funktioniert. | with | NEIN |
target-folder | Wenn Sie den Inhalt des Bereitstellungsordners in ein bestimmtes Verzeichnis in der Bereitstellungszweig in ein bestimmtes Verzeichnis drücken möchten, können Sie ihn hier angeben. | with | NEIN |
commit-message | Wenn Sie die Commit -Nachricht für eine Integration anpassen müssen, können Sie dies tun. | with | NEIN |
clean | Sie können diese Option verwenden, um Dateien aus Ihrem Bereitstellungsziel zu löschen, die in Ihrer Bereitstellungsquelle nicht mehr vorhanden sind. Ein Anwendungsfall ist, wenn Ihr Projekt Hash -Dateien generiert, die von Build bis Build variieren. .ssh Verwendung .github clean wirkt sich nicht aus .git Diese Option wird standardmäßig eingeschaltet und kann durch Einstellen auf false abgeschaltet werden. | with | NEIN |
clean-exclude | Wenn Sie clean verwenden müssen, aber bestimmte Dateien oder Ordner aufbewahren möchten, können Sie diese Option verwenden. Dies sollte jedes Muster als einzelne Linie in einer Multiline -Zeichenfolge enthalten. | with | NEIN |
dry-run | Schieben Sie nicht wirklich zurück, sondern verwenden Sie stattdessen --dry-run git push -Aufrufe. | with | NEIN |
single-commit | Diese Option kann auf true umgeschaltet werden, wenn Sie es vorziehen möchten, dass Sie einen einzigen Einsatz in der Bereitstellungszweig haben, anstatt die vollständige Geschichte aufrechtzuerhalten. Die Verwendung dieser Option führt auch dazu, dass jeder vorhandene Verlauf aus der Bereitstellungszweig ausgelöscht wird . | with | NEIN |
force | Force-Push-neuen Bereitstellungen, um die vorherige Version zu überschreiben; Versuchen Sie ansonsten, neue Bereitstellungen auf bestehende Einsätze zu wiederholen. Diese Option wird standardmäßig eingeschaltet und kann durch Einstellen auf false umgeschaltet werden, was möglicherweise nützlich ist, wenn mehrere Bereitstellungen in einer einzelnen Filiale vorhanden sind. | with | NEIN |
attempt-limit | Wie viele Rebase -Versuche, vor dem Aufsetzen des Jobs zu machen? Diese Option ist standardmäßig 3 und kann nützlich sein, um sich zu erhöhen, wenn mehrere Bereitstellungen in einer einzelnen Filiale vorhanden sind. | with | NEIN |
silent | Schweigen Sie die Wirkungsausgabe, die verhindert, dass sie Git -Nachrichten anzeigen. | with | NEIN |
tag | Fügen Sie dem Commit ein Tag hinzu. Funktioniert nur, wenn dry-run nicht verwendet wird. | with | NEIN |
Wenn die Aktion korrekt konfiguriert ist, sollten Sie den Workflow die Bereitstellung unter den konfigurierten Bedingungen auslösen.
Die Aktion exportiert eine Umgebungsvariable, die als deployment_status bezeichnet wird, die Sie in Ihrem Workflow verwenden können, um festzustellen, ob die Bereitstellung erfolgreich war oder nicht. Sie finden eine Erläuterung für jeden Statusart unten.
| Status | Beschreibung |
|---|---|
success | Der success zeigt an, dass die Aktion erfolgreich in die Filiale eingesetzt wurde. |
failed | Der failed Status zeigt an, dass die Aktion beim Versuch auf einen Fehler aufgetreten ist. |
skipped | Der skipped Status zeigt an, dass die Aktion frühzeitig beendet wurde, da die Bereitstellung nichts Neues gab. |
Dieser Wert wird auch als Schrittausgabe als deployment-status festgelegt.
Wenn Sie es vorziehen möchten, einen SSH -Bereitstellungsschlüssel im Gegensatz zu einem Token zu verwenden, müssen Sie zunächst einen neuen SSH -Schlüssel erstellen, indem Sie den folgenden Terminalbefehl ausführen und die E -Mail durch einen an Ihr Github -Konto verbundenen E -Mail ersetzen.
ssh-keygen -t rsa -m pem -b 4096 -C " [email protected] " -N " " Sobald Sie das Schlüsselpaar generiert haben, müssen Sie den Inhalt des öffentlichen Schlüssels in das Menü "Bereitstellung" des Repositorys hinzufügen. Sie können diese Option finden, indem Sie zu Settings > Deploy Keys . Sie können den öffentlichen Schlüssel nennen, was Sie wollen, aber Sie müssen ihm Schreibzugriff erhalten. Fügen Sie anschließend den Inhalt des privaten Schlüssels zum Menü Settings > Secrets als DEPLOY_KEY hinzu.
Mit diesem konfigurierten können Sie den ssh-key -Teil der Aktion auf Ihren privaten Schlüssel einstellen, der als Geheimnis gespeichert ist.
- name : Deploy
uses : JamesIves/github-pages-deploy-action@v4
with :
folder : site
ssh-key : ${{ secrets.DEPLOY_KEY }} name : Build and Deploy
on :
push :
branches :
- main
jobs :
deploy :
concurrency : ci-${{ github.ref }}
runs-on : ubuntu-latest
steps :
- name : Checkout ?️
uses : actions/checkout@v4
- name : Install and Build ? # This example project is built using npm and outputs the result to the 'build' folder. Replace with the commands required to build your project, or remove this step entirely if your site is pre-built.
run : |
npm ci
npm run build
- name : Deploy
uses : JamesIves/github-pages-deploy-action@v4
with :
folder : build
clean : true
clean-exclude : |
special-file.txt
some/*.txt
ssh-key : ${{ secrets.DEPLOY_KEY }} Wenn Sie den SSH-Client bereits in einem vorherigen Schritt konfiguriert haben, können Sie die Option ssh-key auf true festlegen, damit er über einen vorhandenen SSH-Client bereitgestellt wird. Anstatt die Client -Konfiguration anzupassen, wechselt sie einfach auf die SSH -Endpunkte von GitHub.
Diese Aktion wurde hauptsächlich mit Ubuntu entwickelt. In Ihrer Workflow-Jobkonfiguration wird empfohlen, die runs-on auf ubuntu-latest festzulegen.
jobs :
build-and-deploy :
runs-on : ubuntu-latest Wenn Sie ein Betriebssystem wie Windows verwenden, können Sie dies mit Artefakten unterhalten. In Ihrer Workflow-Konfiguration können Sie die actions/upload-artifact und actions/download-artifact -Aktionen verwenden, um Ihr Projekt auf einem Windows-Job in einen sekundären Job zu verschieben, der die Bereitstellung erledigt.
name : Build and Deploy
on : [push]
permissions :
contents : write
jobs :
build :
runs-on : windows-latest # The first job utilizes windows-latest
steps :
- name : Checkout ?️
uses : actions/checkout@v4
- name : Install and Build ? # This example project is built using npm and outputs the result to the 'build' folder. Replace with the commands required to build your project, or remove this step entirely if your site is pre-built.
run : |
npm ci
npm run build
- name : Upload Artifacts ? # The project is then uploaded as an artifact named 'site'.
uses : actions/upload-artifact@v1
with :
name : site
path : build
deploy :
concurrency : ci-${{ github.ref }}
needs : [build] # The second job must depend on the first one to complete before running and uses ubuntu-latest instead of windows.
runs-on : ubuntu-latest
steps :
- name : Checkout ?️
uses : actions/checkout@v4
- name : Download Artifacts ? # The built project is downloaded into the 'site' folder.
uses : actions/download-artifact@v1
with :
name : site
- name : Deploy
uses : JamesIves/github-pages-deploy-action@v4
with :
folder : ' site ' # The deployment folder should match the name of the artifact. Even though our project builds into the 'build' folder the artifact name of 'site' must be placed here. Wenn Sie einen Container in Ihrem Workflow verwenden, müssen Sie möglicherweise einen zusätzlichen Schritt ausführen, um rsync zu installieren, da diese Aktion davon abhängt. Sie können unten ein Beispiel dafür anzeigen.
- name : Install rsync
run : |
apt-get update && apt-get install -y rsync
- name : Deploy
uses : JamesIves/github-pages-deploy-action@v4 Wenn Sie eine benutzerdefinierte Domäne verwenden und eine CNAME -Datei benötigen oder wenn Sie eine .nojekyll -Datei benötigen, können Sie diese Dateien sicher direkt in die Bereitstellungszweig einsetzen, ohne dass sie nach jeder Bereitstellung überschrieben werden. Außerdem können Sie diese Dateien in Ihren Bereitstellungsordner einbeziehen, um sie zu aktualisieren. Wenn Sie der Bereitstellung zusätzliche Dateien hinzufügen müssen, die durch die Aufbereitungsschritte für Erstellung ignoriert werden sollten, können Sie die Option clean-exclude verwenden.
name : Build and Deploy
permissions :
contents : write
on :
push :
branches :
- main
jobs :
deploy :
concurrency : ci-${{ github.ref }}
runs-on : ubuntu-latest
steps :
- name : Checkout ?️
uses : actions/checkout@v4
- name : Install and Build ? # This example project is built using npm and outputs the result to the 'build' folder. Replace with the commands required to build your project, or remove this step entirely if your site is pre-built.
run : |
npm ci
npm run build
- name : Deploy
uses : JamesIves/github-pages-deploy-action@v4
with :
folder : build
clean : true
clean-exclude : |
special-file.txt
some/*.txtWenn Sie diese Dateien entfernen möchten, müssen Sie in die Bereitstellungszweig direkt entfernen, um sie zu entfernen. Dies soll zu verhindern, dass zufällige Änderungen in Ihrem Bereitstellungsskript das Erstellen von Veränderungen erstellen.
