> ## Knowledge Base Index
> Fetch the complete knowledge base index at: https://help.squarecloud.app/sitemap.xml
> Use this file to discover available pages before exploring further.
> Pure-Markdown content can be obtained by appending a '.md' suffix to the content URLs listed in the sitemap (without the trailing slash).

# Workflow (GitHub Actions): deploy automático

# 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.
```yaml
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.