Fai il deploy su Square Cloud da GitHub Actions

A ogni push, release o avvio manuale, l’action ufficiale installa la CLI di Square Cloud sul runner, la verifica e invia il tuo codice alla tua applicazione.

Vedi su GitHub MarketplaceConfigurala in tre passaggi
Funziona sui runner Linux, Windows e macOS, su x64 e arm64. Il codice sorgente è su GitHub.

Deploy a ogni push in tre passaggi

Due valori salvati nel tuo repository e un file di workflow. Da lì in poi, ogni push su main invia il codice alla tua applicazione e la riavvia.

  1. 1

    Salva una chiave API come secret

    Crea una chiave API nelle impostazioni di sicurezza del tuo account e salvala nel repository come secret SQUARECLOUD_API_KEY.

  2. 2

    Salva l’ID dell’applicazione

    Copia l’ID dalla pagina dell’applicazione nella dashboard e salvalo come variabile del repository SQUARECLOUD_APP_ID.

  3. 3

    Aggiungi il workflow

    Fai il commit del file qui sotto come .github/workflows/deploy.yml. Il prossimo push su main fa il deploy della tua applicazione.

.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

  • Mantieni lo step di checkout

    Senza actions/checkout, il runner non ha file da inviare.

  • Ferma? Parte comunque

    --restart riavvia l’applicazione dopo l’upload e la avvia se era ferma. Senza, i nuovi file entrano in uso al prossimo riavvio.

  • L’ID può stare nella cartella

    Senza ID, commit legge la riga ID= del file squarecloud.app nella cartella, se esiste, quindi basta commit --restart.

Cosa fa l’action sul runner

Quattro passaggi, in quest’ordine, su ogni runner. Se uno fallisce, fallisce anche lo step, così un deploy che non è avvenuto non appare mai verde.

  1. 1

    Scarica la build giusta

    Sceglie la release della CLI per il sistema e il processore del runner: la più recente o la versione che fissi tu. I runner self-hosted la tengono nella loro tool cache.

  2. 2

    La verifica prima di installarla

    Lo SHA-256 del download viene confrontato con il checksums.txt della release. Un file che non corrisponde non viene mai installato né avviato.

  3. 3

    Passa la chiave senza salvarla

    La chiave viene mascherata nei log e impostata come SQUARECLOUD_API_KEY per il resto del job. Niente viene scritto sul disco del runner.

  4. 4

    Avvia il tuo comando

    squarecloud seguito dal tuo command parte in workdir. Se il comando fallisce, fallisce anche lo step.

Un workflow per ogni modo di rilasciare

Quattro schemi dalla documentazione dell’action, pronti da copiare. Le righe evidenziate sono quelle che cambiano rispetto al workflow qui sopra.

  • Staging e produzione

    I push su main vanno in produzione e quelli su develop in staging, ognuno sulla propria applicazione.

    • Il pulsante Run workflow nella scheda Actions fa il deploy del branch che scegli
    • concurrency mette in fila i deploy dello stesso branch invece di sovrapporli
    .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

  • Più applicazioni in un repository

    Ogni cartella è un’applicazione a sé. Una matrice fa il deploy di tutte fianco a fianco, un job per cartella.

    • workdir indirizza ogni deploy alla sua cartella
    • fail-fast: false evita che un deploy fallito annulli gli altri
    .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 alla pubblicazione di una release

    Solo il codice di una release pubblicata arriva all’applicazione.

    • I push e le release in bozza non fanno il deploy
    .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

  • Variabili d’ambiente dai secret

    Tieni token e password nei secret di GitHub e inviali all’applicazione prima di ogni deploy. env set aggiunge o aggiorna solo le variabili che elenca, e il riavvio dopo il commit le carica.

    • Dalla CLI 3.1.1, i valori con spazi o caratteri come $, &, ; o | arrivano esattamente come salvati nel secret
    • Con la CLI 3.1.0, racchiudi tu ogni valore tra apici singoli
    • Passare i secret tramite env tiene i loro valori fuori dallo script che GitHub avvia
    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

Cinque input

Solo token è obbligatorio. Gli altri hanno valori predefiniti che puoi lasciare così.

tokenObbligatorio
La tua chiave API di Square Cloud. Tienila in un secret, mai nel file del workflow.
command
Il comando della CLI da avviare, senza il prefisso squarecloud, per esempio commit --restart. Senza, l’action installa solo la CLI.
versionPredefinito latest
La versione della CLI da installare: latest, oppure 3.1.0 o successive. Trovare l’ultima versione non chiama l’API di GitHub, quindi il suo limite di richieste non è mai d’intralcio.
workdirPredefinito .
La cartella in cui parte il comando, relativa alla radice del repository.
install-onlyPredefinito false
Installa solo la CLI e imposta la chiave, così gli step successivi del job possono avviare squarecloud da soli.

  • Fissa la versione della CLI

    Fa il deploy della cartella bot con la CLI 3.1.1 a ogni avvio, qualunque sia l’ultima release.

    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

  • Avvia più comandi

    Con install-only, la CLI e la sua chiave restano disponibili per gli step successivi: build, deploy e poi lo stato in 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

Qualsiasi runner di GitHub

L’action è testata sui runner Linux, Windows e macOS di GitHub, su x64 e arm64. Funzionano anche i tuoi runner self-hosted, purché la loro versione supporti le action node24.

  • Linux

    x64 e arm64 sui runner ospitati da GitHub. I tuoi runner possono essere anche x86 o ARMv7.

    • Testata su ubuntu-latest e ubuntu-24.04-arm

  • Windows

    x64 e arm64 sui runner ospitati da GitHub. I tuoi runner possono essere anche x86.

    • Testata su windows-latest e windows-11-arm

  • macOS

    Intel e Apple silicon, sia sui runner ospitati da GitHub sia sui tuoi.

    • Testata su macos-latest

La tua chiave resta segreta

L’action tratta la chiave API come la password che è.

  • Mascherata nei log

    La chiave viene registrata come secret prima che parta qualsiasi cosa, quindi appare come *** in ogni riga di log.

  • Mai sul disco

    La CLI la legge da SQUARECLOUD_API_KEY. Non viene salvata sul runner né passata dalla riga di comando.

  • Limitata a un job

    Gli step successivi dello stesso job possono usarla, gli altri job no. Avvia le action di cui non ti fidi in un job separato.

  • Una chiave per repo

    Dai a ogni repository la sua chiave, così puoi revocarne una senza toccare le altre.

Una CLI pensata per i workflow

Ogni comando che l’action avvia è un comando della CLI di Square Cloud, e la CLI è fatta per funzionare senza terminale.

  • Conferma con -y

    I comandi che modificano o eliminano dati chiedono conferma. Un workflow non può rispondere, quindi aggiungi -y: senza, il comando termina con codice 1 e non cambia nulla.

  • JSON per gli script

    I comandi che stampano dati accettano --json, per un output che lo step successivo può leggere.

  • Traccia ogni richiesta

    Imposta SQUARECLOUD_DEBUG: 1 nell’env dello step per registrare metodo, percorso, stato e durata di ogni richiesta all’API, mai header o body.

  • Scegli cosa inviare

    commit esclude ciò che elenca squarecloud.ignore, con la sintassi di gitignore. node_modules, .git e i lockfile restano fuori, a meno che tu non li riaggiunga con !.

Usi già @v2?

@v2 ora punta alla nuova versione, quindi il tuo workflow continua a funzionare senza modifiche. Ecco cosa è cambiato.

  • workdir viene applicato. Fino alla 2.1.2 veniva ignorato e i comandi partivano dalla radice del repository.
  • La chiave non viene più passata dalla riga di comando né salvata sul runner.
  • I runner Windows, macOS e arm64 sono supportati.
  • Il download della CLI viene verificato con i suoi checksum, e il nuovo input version ne fissa la versione.
  • Trovare l’ultima CLI non chiama più l’API di GitHub, quindi il limite di richieste dell’API non la riguarda.
  • L’action gira su Node 24.

La CLI 3.1 esclude anche i lockfile dagli upload. Per continuare a inviare il tuo, aggiungi !package-lock.json (o il tuo lockfile) a squarecloud.ignore.

Risorse correlate

Un piano per ogni fase del tuo progetto

Inizia in piccolo e scala quando ne hai bisogno, senza contratti di permanenza.

Confronta tutti i piani

4,9 su 5 · 402 recensioni su Google + TrustpilotTrustpilot

Ospitato in un datacenter partner con certificazioni
Tier 3ISO 27001SOC 2 Type IIProtezione DDoS Always-On
Esplora la nostra infrastruttura

Pronto a scalare il tuo progetto?

Unisciti agli oltre 500.000 sviluppatori che hanno usato Square Cloud per ospitare i loro progetti.

Inizia ora su Square CloudVedi piani e prezzi
  • Prezzi prevedibili
  • Nessuna sorpresa in fattura
  • Deploy in pochi secondi
  • Alta disponibilità
  • Scala con stabilità
  • Riavvio automatico
  • SSL e sicurezza inclusi
  • Container isolati