Despliega en Square Cloud desde GitHub Actions

Con cada push, release o activación manual, la action oficial instala la CLI de Square Cloud en el runner, la verifica y envía tu código a tu aplicación.

Ver en GitHub MarketplaceConfigúrala en tres pasos
Funciona en runners Linux, Windows y macOS, en x64 y arm64. El código fuente está en GitHub.

Despliega con cada push en tres pasos

Dos valores guardados en tu repositorio y un archivo de workflow. A partir de ahí, cada push a main envía el código a tu aplicación y la reinicia.

  1. 1

    Guarda la clave de API

    Crea una clave de API en la configuración de seguridad de tu cuenta y guárdala en el repositorio como el secreto SQUARECLOUD_API_KEY.

  2. 2

    Guarda el ID de la aplicación

    Copia el ID desde la página de la aplicación en el panel y guárdalo como la variable de repositorio SQUARECLOUD_APP_ID.

  3. 3

    Agrega el workflow

    Haz commit del archivo de abajo como .github/workflows/deploy.yml. El próximo push a main despliega tu aplicación.

.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

  • Conserva el paso de checkout

    Sin actions/checkout, el runner no tiene archivos que enviar.

  • ¿Detenida? También arranca

    --restart reinicia la aplicación después de la subida y la inicia si estaba detenida. Sin él, los archivos nuevos se aplican en el próximo reinicio.

  • El ID puede quedarse en la carpeta

    Sin un ID, commit lee la línea ID= del squarecloud.app de la carpeta, cuando existe, así que basta con commit --restart.

Lo que hace la action en el runner

Cuatro pasos, en este orden, en cualquier runner. Si alguno falla, el paso del workflow también falla, así que un despliegue que no ocurrió nunca aparece en verde.

  1. 1

    Descarga la build del runner

    Elige la release de la CLI para el sistema y el procesador del runner: la más reciente o la versión que fijes. Los runners autohospedados la guardan en su caché de herramientas.

  2. 2

    La verifica antes de instalarla

    El SHA-256 de la descarga se compara con el checksums.txt de la release. Un archivo que no coincide nunca se instala ni se ejecuta.

  3. 3

    Pasa la clave sin guardarla

    La clave se enmascara en los logs y se define como SQUARECLOUD_API_KEY durante el resto del job. No se escribe nada en el disco del runner.

  4. 4

    Ejecuta tu comando

    squarecloud seguido de tu command se ejecuta en workdir. Si el comando falla, el paso falla.

Un workflow para cada forma de desplegar

Cuatro patrones de la documentación de la action, listos para copiar. Las líneas resaltadas son lo que cambia respecto al workflow de arriba.

  • Staging y producción

    Los push a main van a producción y los push a develop van a staging, cada uno a su propia aplicación.

    • El botón Run workflow de la pestaña Actions despliega la rama que elijas
    • concurrency hace que los despliegues de la misma rama esperen su turno en lugar de solaparse
    .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

  • Varias aplicaciones en un repositorio

    Cada carpeta es su propia aplicación. Una matriz las despliega en paralelo, un job por carpeta.

    • workdir apunta cada despliegue a su carpeta
    • fail-fast: false evita que un despliegue fallido cancele los demás
    .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

  • Despliega al publicar una release

    Solo el código de una release publicada llega a la aplicación.

    • Los push y las releases en borrador no despliegan
    .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

  • Variables de entorno desde secretos

    Guarda tokens y contraseñas en los secretos de GitHub y envíalos a la aplicación antes de cada despliegue. env set agrega o actualiza solo las variables que indica, y el reinicio tras el commit las carga.

    • Desde la CLI 3.1.1, los valores con espacios o caracteres como $, &, ; o | llegan tal como están guardados en el secreto
    • Con la CLI 3.1.0, envuelve tú mismo cada valor entre comillas simples
    • Pasar los secretos por env mantiene sus valores fuera del script que ejecuta GitHub
    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

Cinco inputs

Solo token es obligatorio. Los demás tienen valores por defecto que puedes dejar tal cual.

tokenObligatorio
Tu clave de API de Square Cloud. Guárdala en un secreto, nunca en el archivo del workflow.
command
El comando de la CLI que se ejecuta, sin el prefijo squarecloud, por ejemplo commit --restart. Sin él, la action solo instala la CLI.
versionPor defecto latest
La versión de la CLI que se instala: latest, o la 3.1.0 o posterior. Buscar la versión más reciente no llama a la API de GitHub, así que su límite de solicitudes nunca estorba.
workdirPor defecto .
La carpeta en la que se ejecuta el comando, relativa a la raíz del repositorio.
install-onlyPor defecto false
Solo instala la CLI y define la clave, para que los pasos siguientes del job ejecuten squarecloud por su cuenta.

  • Fija la versión de la CLI

    Despliega la carpeta bot siempre con la CLI 3.1.1, sea cual sea la release más reciente.

    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

  • Ejecuta varios comandos

    Con install-only, la CLI y su clave quedan disponibles para los pasos siguientes: build, despliegue y, al final, el estado en 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

Cualquier runner de GitHub

La action se prueba en los runners Linux, Windows y macOS de GitHub, en x64 y arm64. Tus runners autohospedados también funcionan, siempre que su versión admita actions node24.

  • Linux

    x64 y arm64 en los runners alojados por GitHub. En tus propios runners, también x86 o ARMv7.

    • Probada en ubuntu-latest y ubuntu-24.04-arm

  • Windows

    x64 y arm64 en los runners alojados por GitHub. En tus propios runners, también x86.

    • Probada en windows-latest y windows-11-arm

  • macOS

    Intel y Apple silicon, en los runners alojados por GitHub y en los tuyos.

    • Probada en macos-latest

Tu clave sigue siendo secreta

La action trata la clave de API como la contraseña que es.

  • Oculta en los logs

    La clave se registra como secreto antes de que se ejecute nada, así que aparece como *** en cada línea del log.

  • Nunca en el disco

    La CLI la lee de SQUARECLOUD_API_KEY. No se guarda en el runner ni se pasa por la línea de comandos.

  • Limitada a un job

    Los pasos siguientes del mismo job pueden usarla; otros jobs no. Ejecuta las actions en las que no confíes en un job aparte.

  • Clave por repositorio

    Da a cada repositorio su propia clave, para revocar una sin tocar las demás.

Una CLI hecha para workflows

Cada comando que ejecuta la action es un comando de la CLI de Square Cloud, y la CLI está pensada para funcionar sin terminal.

  • Confirma con -y

    Los comandos que cambian o borran datos piden confirmación. Un workflow no puede responder, así que agrega -y: sin él, el comando termina con código 1 y no cambia nada.

  • JSON para scripts

    Los comandos que muestran datos aceptan --json, con una salida que el siguiente paso puede leer.

  • Rastrea cada solicitud

    Define SQUARECLOUD_DEBUG: 1 en el env del paso para registrar el método, la ruta, el estado y la duración de cada solicitud a la API, nunca cabeceras ni cuerpos.

  • Elige qué se envía

    commit deja fuera lo que lista squarecloud.ignore, con sintaxis de gitignore. node_modules, .git y los lockfiles quedan fuera salvo que los vuelvas a incluir con !.

¿Ya usas @v2?

@v2 ahora apunta a la nueva versión, así que tu workflow sigue funcionando sin cambios. Esto es lo que cambió.

  • workdir se aplica. Hasta la 2.1.2 se ignoraba y los comandos se ejecutaban en la raíz del repositorio.
  • La clave ya no se pasa por la línea de comandos ni se guarda en el runner.
  • Se admiten runners Windows, macOS y arm64.
  • La descarga de la CLI se verifica con sus checksums, y el nuevo input version fija la versión.
  • Buscar la CLI más reciente ya no llama a la API de GitHub, así que el límite de solicitudes de la API no la afecta.
  • La action funciona con Node 24.

La CLI 3.1 también deja los lockfiles fuera de las subidas. Para seguir enviando el tuyo, agrega !package-lock.json (o tu lockfile) a squarecloud.ignore.

Recursos relacionados

Un plan para cada etapa de tu proyecto

Empieza pequeño y escala cuando lo necesites, sin contratos de permanencia.

Comparar todos los planes

4,9 de 5 · 402 reseñas en Google + TrustpilotTrustpilot

Alojado en un datacenter asociado con certificaciones
Tier 3ISO 27001SOC 2 Type IIProtección DDoS Always-On
Explora nuestra infraestructura

¿Listo para escalar tu proyecto?

Únete a los más de 500 mil desarrolladores que han usado Square Cloud para alojar sus proyectos.

Comienza ahora en Square CloudVer planes y precios
  • Precios predecibles
  • Sin sorpresas en la factura
  • Deploy en segundos
  • Alta disponibilidad
  • Escala con estabilidad
  • Reinicio automático
  • SSL y seguridad incluidos
  • Contenedores aislados