Deployen Sie mit GitHub Actions auf Square Cloud

Bei jedem Push, Release oder manuellen Start installiert die offizielle Action die Square Cloud CLI auf dem Runner, prüft sie und sendet Ihren Code an Ihre Anwendung.

Im GitHub Marketplace ansehenIn drei Schritten einrichten
Läuft auf Linux-, Windows- und macOS-Runnern, mit x64 und arm64. Der Quellcode liegt auf GitHub.

In drei Schritten zum Deploy bei jedem Push

Zwei Werte in Ihrem Repository und eine Workflow-Datei. Danach sendet jeder Push auf main den Code an Ihre Anwendung und startet sie neu.

  1. 1

    API-Schlüssel speichern

    Erstellen Sie in den Sicherheitseinstellungen Ihres Kontos einen API-Schlüssel und speichern Sie ihn im Repository als Secret SQUARECLOUD_API_KEY.

  2. 2

    Anwendungs-ID speichern

    Kopieren Sie die ID von der Seite der Anwendung im Dashboard und speichern Sie sie als Repository-Variable SQUARECLOUD_APP_ID.

  3. 3

    Workflow hinzufügen

    Committen Sie die Datei unten als .github/workflows/deploy.yml. Der nächste Push auf main deployt Ihre Anwendung.

.github/workflows/deploy.yml
name: Deployon:  push:    branches: [main]jobs:  deploy:    runs-on: ubuntu-latest    steps:      - uses: actions/checkout@v7      - uses: squarecloudofc/github-action@v2        with:          token: ${{ secrets.SQUARECLOUD_API_KEY }}          command: commit ${{ vars.SQUARECLOUD_APP_ID }} --restart

  • Checkout-Schritt behalten

    Ohne actions/checkout hat der Runner keine Dateien zum Senden.

  • Gestoppt? Sie startet auch

    --restart startet die Anwendung nach dem Upload neu und startet sie, falls sie gestoppt war. Ohne die Option werden die neuen Dateien erst beim nächsten Neustart wirksam.

  • Die ID kann im Ordner liegen

    Ohne ID liest commit die Zeile ID= aus der squarecloud.app im Ordner, sofern vorhanden. Dann genügt commit --restart.

Was die Action auf dem Runner tut

Vier Schritte, in dieser Reihenfolge, auf jedem Runner. Schlägt einer fehl, schlägt auch der Workflow-Schritt fehl: Ein Deploy, der nicht stattgefunden hat, erscheint nie grün.

  1. 1

    Lädt den passenden Build herunter

    Sie wählt das CLI-Release für System und Prozessor des Runners: das neueste oder die Version, die Sie festlegen. Selbst gehostete Runner behalten es in ihrem Tool-Cache.

  2. 2

    Prüft ihn vor der Installation

    Der SHA-256 des Downloads wird mit der checksums.txt des Releases abgeglichen. Eine Datei, die nicht übereinstimmt, wird nie installiert oder gestartet.

  3. 3

    Übergibt den Schlüssel, ohne ihn zu speichern

    Der Schlüssel wird in den Logs maskiert und für den Rest des Jobs als SQUARECLOUD_API_KEY gesetzt. Auf die Festplatte des Runners wird nichts geschrieben.

  4. 4

    Startet Ihren Befehl

    squarecloud mit Ihrem command läuft in workdir. Schlägt der Befehl fehl, schlägt auch der Schritt fehl.

Der passende Workflow für jede Auslieferung

Vier Muster aus der Dokumentation der Action, bereit zum Kopieren. Die hervorgehobenen Zeilen zeigen, was sich gegenüber dem Workflow oben ändert.

  • Staging und Produktion

    Pushes auf main gehen in die Produktion, Pushes auf develop ins Staging, jeweils in eine eigene Anwendung.

    • Der Button Run workflow im Tab Actions deployt den Branch Ihrer Wahl
    • concurrency lässt Deploys desselben Branches aufeinander warten, statt sie zu überlappen
    .github/workflows/deploy.yml
    name: Deployon:  push:    branches: [main, develop]  workflow_dispatch:concurrency:  group: deploy-${{ github.ref_name }}jobs:  deploy:    runs-on: ubuntu-latest    steps:      - uses: actions/checkout@v7      - uses: squarecloudofc/github-action@v2        with:          token: ${{ secrets.SQUARECLOUD_API_KEY }}          command: commit ${{ github.ref_name == 'main' && vars.PRODUCTION_APP_ID || vars.STAGING_APP_ID }} --restart

  • Mehrere Anwendungen in einem Repository

    Jeder Ordner ist eine eigene Anwendung. Eine Matrix deployt sie nebeneinander, mit einem Job pro Ordner.

    • workdir richtet jeden Deploy auf seinen Ordner aus
    • fail-fast: false verhindert, dass ein fehlgeschlagener Deploy die anderen abbricht
    .github/workflows/deploy.yml
    name: Deployon:  push:    branches: [main]jobs:  deploy:    runs-on: ubuntu-latest    strategy:      fail-fast: false      matrix:        include:          - folder: bot            app: ${{ vars.BOT_APP_ID }}          - folder: website            app: ${{ vars.WEBSITE_APP_ID }}    steps:      - uses: actions/checkout@v7      - uses: squarecloudofc/github-action@v2        with:          token: ${{ secrets.SQUARECLOUD_API_KEY }}          workdir: ${{ matrix.folder }}          command: commit ${{ matrix.app }} --restart

  • Deploy beim Veröffentlichen eines Releases

    Nur der Code eines veröffentlichten Releases erreicht die Anwendung.

    • Pushes und Release-Entwürfe lösen keinen Deploy aus
    .github/workflows/deploy.yml
    name: Deployon:  release:    types: [published]jobs:  deploy:    runs-on: ubuntu-latest    steps:      - uses: actions/checkout@v7      - uses: squarecloudofc/github-action@v2        with:          token: ${{ secrets.SQUARECLOUD_API_KEY }}          command: commit ${{ vars.SQUARECLOUD_APP_ID }} --restart

  • Umgebungsvariablen aus Secrets

    Bewahren Sie Tokens und Passwörter in GitHub-Secrets auf und senden Sie sie vor jedem Deploy an die Anwendung. env set fügt nur die aufgeführten Variablen hinzu oder aktualisiert sie, und der Neustart nach dem Commit lädt sie.

    • Ab CLI 3.1.1 kommen Werte mit Leerzeichen oder Zeichen wie $, &, ; oder | genau so an, wie sie im Secret gespeichert sind
    • Mit CLI 3.1.0 setzen Sie jeden Wert selbst in einfache Anführungszeichen
    • Über env übergebene Secrets bleiben außerhalb des Skripts, das GitHub startet
    jobs.deploy.steps
    - uses: squarecloudofc/github-action@v2  with:    token: ${{ secrets.SQUARECLOUD_API_KEY }}    install-only: true- name: Update environment variables  run: squarecloud app env set --app "$APP_ID" "DISCORD_TOKEN=$DISCORD_TOKEN" "DATABASE_URL=$DATABASE_URL"  env:    APP_ID: ${{ vars.SQUARECLOUD_APP_ID }}    DISCORD_TOKEN: ${{ secrets.DISCORD_TOKEN }}    DATABASE_URL: ${{ secrets.DATABASE_URL }}- run: squarecloud commit ${{ vars.SQUARECLOUD_APP_ID }} --restart

Fünf Eingaben

Nur token ist erforderlich. Die anderen haben Standardwerte, die Sie so lassen können.

tokenErforderlich
Ihr Square Cloud API-Schlüssel. Bewahren Sie ihn in einem Secret auf, nie in der Workflow-Datei.
command
Der CLI-Befehl, den die Action startet, ohne das Präfix squarecloud, zum Beispiel commit --restart. Ohne ihn installiert die Action nur die CLI.
versionStandard latest
Die zu installierende CLI-Version: latest oder 3.1.0 und höher. Die Suche nach der neuesten Version ruft die GitHub-API nicht auf, deren Rate-Limit also nie im Weg steht.
workdirStandard .
Der Ordner, in dem der Befehl läuft, relativ zum Stammverzeichnis des Repositorys.
install-onlyStandard false
Installiert nur die CLI und setzt den Schlüssel, damit spätere Schritte des Jobs squarecloud selbst starten können.

  • CLI-Version festlegen

    Deployt den Ordner bot bei jedem Lauf mit CLI 3.1.1, egal welches Release das neueste ist.

    jobs.deploy.steps
    - uses: squarecloudofc/github-action@v2  with:    token: ${{ secrets.SQUARECLOUD_API_KEY }}    version: 3.1.1    workdir: bot    command: commit ${{ vars.SQUARECLOUD_APP_ID }} --restart

  • Mehrere Befehle starten

    Mit install-only bleiben die CLI und ihr Schlüssel für die nächsten Schritte verfügbar: Build, Deploy und danach der Status als JSON.

    jobs.deploy.steps
    - uses: squarecloudofc/github-action@v2  with:    token: ${{ secrets.SQUARECLOUD_API_KEY }}    install-only: true- run: npm ci && npm run build- run: squarecloud commit ${{ vars.SQUARECLOUD_APP_ID }} --restart- run: squarecloud app status ${{ vars.SQUARECLOUD_APP_ID }} --json

Jeder GitHub-Runner

Die Action ist auf den Linux-, Windows- und macOS-Runnern von GitHub getestet, mit x64 und arm64. Ihre eigenen selbst gehosteten Runner funktionieren ebenfalls, sofern ihre Runner-Version node24-Actions unterstützt.

  • Linux

    x64 und arm64 auf GitHub-gehosteten Runnern. Ihre eigenen Runner können auch x86 oder ARMv7 sein.

    • Getestet auf ubuntu-latest und ubuntu-24.04-arm

  • Windows

    x64 und arm64 auf GitHub-gehosteten Runnern. Ihre eigenen Runner können auch x86 sein.

    • Getestet auf windows-latest und windows-11-arm

  • macOS

    Intel und Apple Silicon, auf GitHub-gehosteten Runnern wie auf Ihren eigenen.

    • Getestet auf macos-latest

Ihr Schlüssel bleibt geheim

Die Action behandelt den API-Schlüssel wie das Passwort, das er ist.

  • In Logs maskiert

    Der Schlüssel wird als Secret registriert, bevor irgendetwas startet, und erscheint daher in jeder Logzeile als ***.

  • Nie auf der Festplatte

    Die CLI liest ihn aus SQUARECLOUD_API_KEY. Er wird weder auf dem Runner gespeichert noch über die Befehlszeile übergeben.

  • Auf einen Job begrenzt

    Spätere Schritte desselben Jobs können ihn nutzen, andere Jobs nicht. Starten Sie Actions, denen Sie nicht vertrauen, in einem separaten Job.

  • Ein Schlüssel pro Repo

    Geben Sie jedem Repository einen eigenen Schlüssel, damit Sie einen widerrufen können, ohne die anderen anzufassen.

Eine CLI, gebaut für Workflows

Jeder Befehl, den die Action startet, ist ein Befehl der Square Cloud CLI, und die CLI ist dafür gebaut, ohne Terminal zu funktionieren.

  • Mit -y bestätigen

    Befehle, die Daten ändern oder löschen, fragen vorher nach. Ein Workflow kann nicht antworten, also fügen Sie -y hinzu: Ohne die Option endet der Befehl mit Code 1 und ändert nichts.

  • JSON für Skripte

    Befehle, die Daten ausgeben, akzeptieren --json, für eine Ausgabe, die der nächste Schritt auswerten kann.

  • Anfragen verfolgen

    Setzen Sie SQUARECLOUD_DEBUG: 1 im env des Schritts, um Methode, Pfad, Status und Dauer jeder API-Anfrage zu protokollieren, nie Header oder Bodys.

  • Upload filtern

    commit lässt aus, was squarecloud.ignore in gitignore-Syntax auflistet. node_modules, .git und Lockfiles bleiben draußen, außer Sie nehmen sie mit ! wieder auf.

Sie nutzen schon @v2?

@v2 zeigt jetzt auf die neue Version, Ihr Workflow läuft also unverändert weiter. Das hat sich geändert.

  • workdir wird angewendet. Bis 2.1.2 wurde es ignoriert und Befehle liefen im Stammverzeichnis des Repositorys.
  • Der Schlüssel wird nicht mehr über die Befehlszeile übergeben oder auf dem Runner gespeichert.
  • Windows-, macOS- und arm64-Runner werden unterstützt.
  • Der CLI-Download wird anhand seiner Prüfsummen geprüft, und die neue Eingabe version legt die Version fest.
  • Die Suche nach der neuesten CLI ruft die GitHub-API nicht mehr auf, das Rate-Limit der API betrifft sie also nicht.
  • Die Action läuft auf Node 24.

CLI 3.1 lässt außerdem Lockfiles aus Uploads heraus. Um Ihres weiterhin zu senden, fügen Sie !package-lock.json (oder Ihr Lockfile) zu squarecloud.ignore hinzu.

Verwandte Ressourcen

Ein Plan für jede Phase Ihres Projekts

Starten Sie klein und skalieren Sie bei Bedarf – ohne Vertragsbindung.

Alle Pläne vergleichen

4,9 von 5 · 402 Bewertungen auf Google + TrustpilotTrustpilot

Gehostet in einem Partner-Rechenzentrum mit den Zertifizierungen
Tier 3ISO 27001SOC 2 Type IIAlways-On-DDoS-Schutz
Entdecken Sie unsere Infrastruktur

Bereit, Ihr Projekt zu skalieren?

Schließen Sie sich den mehr als 500.000 Entwicklern an, die Square Cloud für das Hosting ihrer Projekte genutzt haben.

Jetzt mit Square Cloud startenPläne und Preise ansehen
  • Vorhersehbare Preise
  • Keine Überraschungen bei der Abrechnung
  • Deploy in Sekunden
  • Hohe Verfügbarkeit
  • Stabil skalieren
  • Automatischer Neustart
  • SSL und Sicherheit inklusive
  • Isolierte Container