Workflow: O que é e como usar na Square Cloud

No desenvolvimento de software moderno, a agilidade é fundamental. O termo Workflow (fluxo de trabalho) refere-se a uma sequência automatizada de processos que levam seu código do repositório até o servidor de produção. Na Square Cloud, você pode utilizar o GitHub Actions para automatizar seus deploys, garantindo maior segurança e menor tempo de inatividade (downtime).

1. O que é um Workflow do GitHub?

Um Workflow é um processo configurável e automatizado que executará um ou mais "jobs" (trabalhos). Ele é definido por um arquivo YAML no seu repositório (dentro da pasta .github/workflows) e é acionado por eventos específicos, como um "push", a criação de um "pull request" ou o lançamento de uma nova versão (tag).

Componentes principais:

• Events (on): O gatilho que inicia o fluxo (ex: disparar quando uma tag v1.0 é criada).
• Jobs: Conjunto de etapas que executam no mesmo runner.
• Steps: Tarefas individuais, como instalar dependências, compilar o código ou enviar arquivos.

2. A Estratégia de Build Externo

Uma das maiores vantagens de usar Workflows com a Square Cloud é a capacidade de realizar o build (compilação) fora do ambiente de hospedagem.

Ao buildar no GitHub Actions e enviar apenas o resultado final (o pacote pronto para rodar) para a Square Cloud, você reduz drasticamente o uso de CPU no servidor durante a atualização e garante que sua aplicação volte a ficar online quase instantaneamente, já que ela só precisará executar o comando de start.

3. Entendendo o Passo de Deploy na Square

O coração da automação é a Square Cloud GitHub Action. Diferente de um upload manual, este passo funciona como uma ponte inteligente entre o GitHub e os servidores da Square. A Action instala a CLI da Square e facilita a interação com a API, permitindo fazer commits com uma linha 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 }}'

Como funciona o comando commit:

Ao utilizar a action oficial, o comando commit não cria uma nova aplicação do zero; ele substitui os arquivos da aplicação existente (identificada pelo SQUARECLOUD_APP_ID) pelos arquivos contidos no seu arquivo .zip.

Pontos Chave da Action:

• Encapsulamento: O zip que você pode gerar antes desse passo do workflow, é enviado via API. Isso garante que apenas os arquivos necessários para a produção (sem códigos fonte brutos ou caches pesados) sejam transferidos.
• Autenticação Segura: A comunicação é validada através do seu SQUARE_CLOUD_TOKEN, adquirido na dashboard da Square.
• A flag --restart: Este parâmetro é fundamental. Ao incluí-lo, a Square Cloud entende que, assim que o envio do commit for concluído, a aplicação deve ser reiniciada automaticamente para aplicar as mudanças, eliminando a necessidade de intervenção manual no dashboard.

4. Exemplo Prático: Deploy Automatizado de Next.js

Abaixo, apresentamos um exemplo de workflow que prepara uma aplicação Next.js e a envia para a Square Cloud sempre que uma nova tag de versão (ex: v1.0.2) é publicada no 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 Segredos (Secrets)

Para que o GitHub tenha permissão de enviar arquivos para a sua conta na Square Cloud, você não deve escrever seus tokens diretamente no código. Em vez disso, utilize os GitHub Secrets:

1. No seu repositório, vá em Settings > Secrets and variables > Actions > Repository Secrets.
2. Adicione SQUARECLOUD_APP_ID: O ID da sua aplicação na Square.
3. Adicione SQUARE_CLOUD_TOKEN: Seu token de API (encontrado nas configurações da sua conta na Square Cloud).

6. Além do GitHub: O Ecossistema de CI/CD

Embora o GitHub Actions seja a ferramenta mais integrada, o conceito de Workflow é universal. Desenvolvedores também utilizam soluções como GitLab CI/CD ou Jenkins para alcançar resultados semelhantes. A chave é sempre buscar a automação para evitar erros humanos e garantir que o ambiente de produção seja um espelho fiel do que foi testado e aprovado no desenvolvimento.

Atualizado em: 13/05/2026