Workflow: qué es y cómo usarlo en Square Cloud

En el desarrollo de software moderno, la agilidad es fundamental. El término Workflow (flujo de trabajo) se refiere a una secuencia automatizada de procesos que llevan tu código del repositorio hasta el servidor de producción. En Square Cloud, puedes utilizar GitHub Actions para automatizar tus deploys, garantizando mayor seguridad y menor tiempo de inactividad (downtime).

1. ¿Qué es un Workflow de GitHub?

Un Workflow es un proceso configurable y automatizado que ejecutará uno o más "jobs" (trabajos). Se define mediante un archivo YAML en tu repositorio (dentro de la carpeta .github/workflows) y se activa por eventos específicos, como un "push", la creación de un "pull request" o el lanzamiento de una nueva versión (tag).

Componentes principales:

• Events (on): El disparador que inicia el flujo (ej.: ejecutar cuando se crea una tag v1.0).
• Jobs: Conjunto de etapas que se ejecutan, como compilar el código o enviar archivos.

2. La estrategia de build externo

Una de las mayores ventajas de usar Workflows con Square Cloud es la capacidad de realizar el build (compilación) fuera del entorno de alojamiento.

Al hacer el build en GitHub Actions y enviar solo el resultado final (el paquete listo para ejecutarse) a Square Cloud, reduces drásticamente el uso de CPU en el servidor durante la actualización y garantizas que tu aplicación vuelva a estar en línea casi al instante, ya que solo necesitará ejecutar el comando de start.

3. Entendiendo el paso de deploy en Square

El corazón de la automatización es la Square Cloud GitHub Action. A diferencia de un upload manual, este paso funciona como un puente inteligente entre GitHub y los servidores de Square. La Action instala la CLI de Square y facilita la interacción con la API, permitiendo hacer commits con una línea de comando.

      - name: Deploy na Square Cloud
        uses: squarecloudofc/github-action@v2
        with:
          # Envia o zip como um commit direto para a sua aplicação
          command: commit --file project.zip ${{ secrets.SQUARECLOUD_APP_ID }} --restart
          token: '${{ secrets.SQUARE_CLOUD_TOKEN }}'

Cómo funciona el comando commit:

Al utilizar la action oficial, el comando commit no crea una nueva versión; en su lugar, sustituye la aplicación actual (identificada por el SQUARECLOUD_APP_ID) por los archivos contenidos en tu archivo .zip.

Puntos clave de la Action:

• Encapsulamiento: El zip que puedes generar antes de este paso del workflow se envía vía API. Esto garantiza que solo se transfieran los archivos necesarios para producción (sin códigos fuente en bruto ni cachés pesadas).
• Autenticación segura: La comunicación se valida a través de tu SQUARE_CLOUD_TOKEN, adquirido en el dashboard de Square.
• La flag --restart: Este parámetro es fundamental. Al incluirlo, Square Cloud entiende que, en cuanto se complete el envío del commit, la aplicación debe reiniciarse automáticamente para aplicar los cambios, eliminando la necesidad de intervención manual en el dashboard.

4. Ejemplo práctico: deploy automatizado de Next.js

A continuación, presentamos un ejemplo de workflow que prepara una aplicación Next.js y la envía a Square Cloud siempre que se publica una nueva tag de versión (ej.: v1.0.2) en GitHub.

name: "Deploy Nextjs app"

on:
  push:
    tags:
      - "v*" # Aciona o workflow em qualquer tag que comece com 'v'

jobs:
  build-and-deploy:
    runs-on: ubuntu-latest
    steps:
      - name: Checkout do código
        uses: actions/checkout@v6

      - name: Configurar Node.js
        uses: actions/setup-node@v6
        with:
          node-version: 24

      - name: Instalar dependências
        run: npm install

      - name: Build do projeto
        # Compila o Next.js e ajusta permissões dos arquivos essenciais
        run: npm run build && chmod -R 777 .next next.config.ts package.json

      - name: Compactar arquivos (Zip)
        # Cria o pacote apenas com o necessário para rodar (sem o código fonte bruto)
        run: zip -r project.zip package.json .next next.config.ts public -x ".next/cache/*"

      - name: Deploy na Square Cloud
        uses: squarecloudofc/github-action@v2
        with:
          # Envia o zip como um commit direto para a sua aplicação
          command: commit --file project.zip ${{ secrets.SQUARECLOUD_APP_ID }} --restart
          token: '${{ secrets.SQUARE_CLOUD_TOKEN }}'

5. Configurando secretos (Secrets)

Para que GitHub tenga permiso de enviar archivos a tu cuenta en Square Cloud, nunca debes exponer tu token en el código. En su lugar, utiliza los GitHub Secrets:

1. En tu repositorio, ve a Settings > Secrets and variables > Actions > Repository Secrets.
2. Añade SQUARECLOUD_APP_ID: El ID de tu aplicación en Square.
3. Añade SQUARE_CLOUD_TOKEN: Tu token de API (encontrado en la configuración de tu cuenta en Square Cloud).

6. Más allá de GitHub: el ecosistema de CI/CD

Aunque GitHub Actions es la herramienta más integrada, el concepto de Workflow es universal. Los desarrolladores también utilizan soluciones como GitLab CI/CD o Jenkins para lograr resultados similares. La clave es siempre buscar la automatización para evitar errores humanos y garantizar que el entorno de producción sea un espejo fiel de lo que fue probado y aprobado en el desarrollo.

Actualizado el: 13/06/2026