GitHub Actions für das Deployment von Plugins/Themes

Veröffentlicht: 1. Juli 2024 – Kommentar hinterlassen

Während der Erstellung von Plugins oder Themes muss man häufig Assets generieren oder es irgendwohin deployen, beispielsweise ins WordPress.org Plugin-Repository. Da der Code häufig auf GitHub gehostet wird, können dafür die sogenannten GitHub Actions verwendet werden.

GitHub Actions

Was sind GitHub Actions genau? Sie sind ein Dienst, den du auf GitHub verwenden kannst, um definierte Aktionen auszuführen, nachdem Code veröffentlicht, ein Tag hinzugefügt oder eine andere Git-verwandte Aktion ausgeführt wurde. Du kannst festlegen, was die Aktion tun und wann das geschehen soll. Es gibt auch einen Marktplatz mit Aktionen, die jemand erstellt hat, und die du verwenden kannst, ohne das Rad neu erfinden zu müssen. Für die meisten üblichen Aktionen gibt es also bereits eine Lösung.

Wie funktionieren sie?

Die Konfiguration der GitHub Actions musst du innerhalb deines Repositories ins Verzeichnis .github/workflows legen. Es ist eine YAML-Datei (oder mehrere YAML-Dateien) und beinhaltet genaue Anweisungen, wann etwas wie ausgeführt werden soll.

Upload zu WordPress.org

Wenn ein Plugin ins WordPress.org Plugin-Repository geladen werden soll, gibt es dafür eine Action von 10up, die dafür verwendet werden kann. Im folgenden Beispiel wird der Code immer dann zu WordPress.org hochgeladen, wenn ein Tag erstellt wird:

name: Deploy to WordPress.org
on:
  push:
    tags:
    - "*"
    - "!*-*"
jobs:
  tag:
    name: New tag
    runs-on: ubuntu-latest
    steps:
    - uses: actions/checkout@v4
    - name: WordPress Plugin Deploy
      id: deploy
      uses: 10up/action-wordpress-plugin-deploy@stable
      env:
        SVN_PASSWORD: ${{ secrets.SVN_PASSWORD }}
        SVN_USERNAME: ${{ secrets.SVN_USERNAME }}
Code-Sprache: YAML (yaml)

Wir verwenden hier zwei Actions. Eine ist die actions/checkout@v4, um den eigentlichen Code aus dem Repository zu erhalten, die andere ist die 10up/action-wordpress-plugin-deploy@stable zum Upload nach WordPress.org.

Aber lass es uns Zeile für Zeile herunterbrechen:
Zuerst wird der Name der Aktion festgelegt. Dann legen wir fest, dass die Aktion immer dann gestartet werden soll, wenn ein Tag gepusht wird, das kein - enthält (was es erlaubt, Tags wie v1.0.0-dev1 zu ignorieren).
Dann erstellen wir die Jobs, d. h. einen Job namens „tag“ mit dem Namen „New tag“, der auf der neuesten Ubuntu-Version mit zwei Schritten läuft: der eine ist der oben erwähnte Checkout-Schritt, um den Code zu erhalten, der andere ist die Deploy-Aktion von 10up. Wie du vielleicht schon gesehen hast, werden ein Benutzername und ein Passwort benötigt, um sich mit dem SVN auf WordPress.org zu verbinden. Gehe dazu in deinem Repository auf GitHub zu Settings > Secrets and variables > Actions und erstelle die beiden Variablen SVN_USERNAME und SVN_PASSWORD mit deinem Benutzernamen und Passwort für dein WordPress.org-Konto.

Assets kompilieren und minifizieren

Oft muss man auch Code kompilieren, wie SCSS/Sass zu CSS oder JavaScript minifizieren. Auch dafür kannst du eine Action verwenden. Ich verwende normalerweise @wordpress/scripts, um den Code zu kompilieren und zu minifizieren, daher muss ich npm vor dem Deployment ausführen. Um das zu tun, verwende ich die Action bahmutov/npm-install@v1 mit den folgenden Schritten:

    - uses: bahmutov/npm-install@v1
    - name: npm build
      run: npm run build
Code-Sprache: YAML (yaml)

Als Beispiel integriert im Job von oben, sieht der gesamte Code so aus:

name: Deploy to WordPress.org
on:
  push:
    tags:
    - "*"
    - "!*-*"
jobs:
  tag:
    name: New tag
    runs-on: ubuntu-latest
    steps:
    - uses: actions/checkout@v4
    - uses: bahmutov/npm-install@v1
    - name: npm build
      run: npm run build
    - name: WordPress Plugin Deploy
      id: deploy
      uses: 10up/action-wordpress-plugin-deploy@stable
      env:
        SVN_PASSWORD: ${{ secrets.SVN_PASSWORD }}
        SVN_USERNAME: ${{ secrets.SVN_USERNAME }}
Code-Sprache: PHP (php)

Die Action installiert so alle npm-Abhängigkeiten und führt den Befehl npm run build aus, der in @wordpress/scripts verwendet wird, um Assets zu generieren. Das passiert, bevor der Code zu WordPress.org geladen wird.

Auf entfernten Server via SSH laden

Es kann auch notwendig sein, Code auf einen anderen Server zu laden. In diesem Beispiel mittels rsync über eine SSH-Verbindung. Ich verwende diese Variante, um ein Plugin automatisch nach dem Deployment aktuell zu halten, ohne erst nach Updates zu suchen. Dafür verwende ich die Aktionen shimataro/ssh-key-action und Burnett01/rsync-deployments, allerdings kann rsync auch direkt innerhalb der GitHub Actions ausgeführt werden (wie jeder andere Kommandozeilen-Befehl auch):

      - name: Install SSH key
        uses: shimataro/ssh-key-action@v2
        with:
          key: ${{ secrets.SSH_PRIVATE_KEY }}
          known_hosts: ${{ secrets.KNOWN_HOSTS }}
      - name: Deploy plugin
        uses: Burnett01/rsync-deployments@7.0.1
        with:
          switches: -ahv --exclude=".git"
          path: .
          remote_path: /home/wp-content/plugins/plugin-name
          remote_host: ${{ secrets.REMOTE_HOST }}
          remote_user: ${{ secrets.REMOTE_USER }}
          remote_key: ${{ secrets.SSH_PRIVATE_KEY }}
Code-Sprache: YAML (yaml)

Die Action shimataro/ssh-key-action stellt sicher, dass die GitHub Action den Host-Schlüssel meines Servers kennt und sich damit über SSH verbinden kann. Der zweite lädt den Code dann so hoch, wie er zu diesem Zeitpunkt ist, in das Plugins-Verzeichnis einer WordPress-Instanz auf meinem Server.

Um sie zu verwenden, musst du wieder ein paar Variablen erstellen, wie oben beschrieben:

• KNOWN_HOSTS: Der/Die Host-Schlüssel des Servers. Für den Server example.com erhältst du sie beispielsweise via ssh-keyscan example.com.
• SSH_PRIVATE_KEY: Ein privater SSH-Schlüssel, der zu einem erlaubten öffentlichen SSH-Schlüssel auf deinem Server passt.
• REMOTE_HOST: Der Hostname deines Servers.
• REMOTE_USER: Der Benutzername auf deinem Server.

Release erstellen

Du kannst auch ein GitHub-Release erstellen und das Plugin/Theme als ZIP-Datei anhängen, um auch später immer auf genau diese veröffentlichte Version zugreifen zu können. Das erfordert, dass du die ZIP-Datei selbst erstellst und sie dann über eine GitHub Action zu einem Release hinzufügst:

      - run: mkdir ${{ github.event.repository.name }}-build && rsync -a . ${{ github.event.repository.name }}-build
      - run: cd ${{ github.event.repository.name }}-build && zip -r ../${{ github.event.repository.name }}.zip * -x "${{ github.event.repository.name }}-build/*" && cd ..
      - run: rm -rf ${{ github.event.repository.name }}-build
      - name: Create Release
        id: create_release
        uses: softprops/action-gh-release@v2
        with:
          files: ${{ github.event.repository.name }}.zip
          name: Release ${{ github.ref_name }}
Code-Sprache: YAML (yaml)

Ich verwende ein temporäres Verzeichnis, um alle Dateien dort hinein zu kopieren, die ich in der ZIP-Datei haben möchte. Über rsync kann ich Inhalte ausschließen, die nicht in dieses Verzeichnis kopiert werden und damit später auch nicht in der ZIP-Datei vorhanden sind.

Um das Release dann zu erstellen, verwende ich die GitHub Action softprops/action-gh-release und hänge die erstellte ZIP-Datei dort mit an. Diese ist nach dem Repository benannt, während das Release so heißt wie der Tag, den ich an der Stelle vergeben habe.

Fazit

Niemand möchte etwas manuell machen, was man automatisieren kann. GitHub Actions sind wunderbar dafür verwendbar, dein WordPress Plugin/Theme vollständig automatisiert zu veröffentlichen und ohne darüber nachzudenken, nachdem du die Aktionen einmal definiert hast.