Faça deploy na Square Cloud pelo GitHub Actions
A cada push, release ou disparo manual, a action oficial instala a CLI da Square Cloud no runner, confere o download e envia seu código para a sua aplicação.
Deploy a cada push em três passos
Dois valores salvos no seu repositório e um arquivo de workflow. A partir daí, cada push na main envia o código para a sua aplicação e a reinicia.
- 1
Salve a chave de API
Crie uma chave de API nas configurações de segurança da sua conta e salve no repositório como o secret SQUARECLOUD_API_KEY.
- 2
Salve o ID da aplicação
Copie o ID na página da aplicação, no painel, e salve como a variável de repositório SQUARECLOUD_APP_ID.
- 3
Adicione o workflow
Faça commit do arquivo abaixo como .github/workflows/deploy.yml. O próximo push na main faz o deploy da sua aplicação.
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 }} --restartMantenha a etapa de checkout
Sem
actions/checkout, o runner não tem arquivos para enviar.Parada? Ela inicia também
--restartreinicia a aplicação depois do upload e a inicia se ela estiver parada. Sem ele, os novos arquivos só valem a partir do próximo reinício.O ID pode ficar na pasta
Sem um ID, o
commitlê a linhaID=dosquarecloud.appda pasta, quando ele existe, e aícommit --restartbasta.
O que a action faz no runner
Quatro passos, nesta ordem, em qualquer runner. Se algum deles falhar, a etapa do workflow falha junto, e um deploy que não aconteceu nunca aparece verde.
- 1
Baixa a build certa para o runner
Escolhe o release da CLI para o sistema e o processador do runner: o mais recente ou a versão que você fixar. Runners auto-hospedados guardam a CLI no cache de ferramentas.
- 2
Confere antes de instalar
O SHA-256 do download é comparado com o
checksums.txtdo release. Um arquivo que não bate nunca é instalado nem roda. - 3
Passa a chave sem salvá-la
A chave é mascarada nos logs e definida como
SQUARECLOUD_API_KEYpelo resto do job. Nada é gravado no disco do runner. - 4
Roda o seu comando
squarecloudseguido do seucommandroda emworkdir. Se o comando falhar, a etapa falha.
Um workflow para cada jeito de fazer deploy
Quatro padrões da documentação da action, prontos para copiar. As linhas destacadas são o que muda em relação ao workflow acima.
Staging e produção
Pushes na
mainvão para produção e pushes nadevelopvão para staging, cada um para a sua própria aplicação.- O botão Run workflow, na aba Actions, faz o deploy do branch que você escolher
concurrencyfaz os deploys do mesmo branch esperarem um pelo outro em vez de se sobreporem
.github/workflows/deploy.ymlname: 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 }} --restartVárias aplicações em um repositório
Cada pasta é uma aplicação. Uma matriz faz o deploy delas lado a lado, um job por pasta.
workdiraponta cada deploy para a sua pastafail-fast: falseimpede que um deploy com falha cancele os outros
.github/workflows/deploy.ymlname: 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 }} --restartDeploy quando um release é publicado
Só o código de um release publicado chega à aplicação.
- Pushes e releases em rascunho não fazem deploy
.github/workflows/deploy.ymlname: 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 }} --restartVariáveis de ambiente vindas de secrets
Guarde tokens e senhas nos secrets do GitHub e envie para a aplicação antes de cada deploy. O
env setadiciona ou atualiza só as variáveis que lista, e o reinício depois do commit as carrega.- A partir da CLI 3.1.1, valores com espaços ou caracteres como
$,&,;ou|chegam exatamente como estão no secret - Na CLI 3.1.0, coloque você mesmo cada valor entre aspas simples
- Passar os secrets por
envmantém os valores fora do script que o GitHub roda
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- A partir da CLI 3.1.1, valores com espaços ou caracteres como
Cinco inputs
Só o token é obrigatório. Os outros têm valores padrão que você pode deixar como estão.
tokenObrigatório- Sua chave de API da Square Cloud. Guarde em um secret, nunca no arquivo do workflow.
command- O comando da CLI a rodar, sem o prefixo
squarecloud, comocommit --restart. Sem ele, a action só instala a CLI. versionPadrãolatest- A versão da CLI a instalar:
latest, ou da 3.1.0 em diante. Descobrir a versão mais recente não chama a API do GitHub, então o limite de requisições dela nunca atrapalha. workdirPadrão.- A pasta onde o comando roda, relativa à raiz do repositório.
install-onlyPadrãofalse- Só instala a CLI e define a chave, para que as próximas etapas do job rodem o
squarecloudpor conta própria.
Fixe a versão da CLI
Faz o deploy da pasta bot sempre com a CLI 3.1.1, seja qual for o release mais recente.
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 }} --restartRode vários comandos
Com install-only, a CLI e a chave ficam disponíveis para as próximas etapas: build, deploy e, por fim, o status em 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
Qualquer runner do GitHub
A action é testada nos runners Linux, Windows e macOS do GitHub, em x64 e arm64. Seus runners auto-hospedados também funcionam, desde que a versão do runner suporte actions node24.
Linux
x64 e arm64 nos runners hospedados pelo GitHub. Nos seus próprios runners, também x86 ou ARMv7.
- Testada em ubuntu-latest e ubuntu-24.04-arm
Windows
x64 e arm64 nos runners hospedados pelo GitHub. Nos seus próprios runners, também x86.
- Testada em windows-latest e windows-11-arm
macOS
Intel e Apple silicon, nos runners hospedados pelo GitHub e nos seus.
- Testada em macos-latest
Sua chave continua secreta
A action trata a chave de API como a senha que ela é.
Mascarada nos logs
A chave é registrada como secret antes de qualquer coisa rodar, então aparece como *** em toda linha de log.
Nunca vai para o disco
A CLI lê a chave de SQUARECLOUD_API_KEY. Ela não é salva no runner nem passada na linha de comando.
Restrita a um job
As próximas etapas do mesmo job podem usá-la; outros jobs, não. Rode actions em que você não confia em um job separado.
Chave por repositório
Dê a cada repositório a sua própria chave, para revogar uma sem mexer nas outras.
Uma CLI feita para workflows
Todo comando que a action roda é um comando da CLI da Square Cloud, e a CLI foi feita para funcionar sem terminal.
Confirme com -y
Comandos que alteram ou apagam dados pedem confirmação. Um workflow não tem como responder, então adicione
-y: sem ele, o comando sai com código 1 e não muda nada.JSON para scripts
Comandos que mostram dados aceitam
--json, com uma saída que a próxima etapa consegue ler.Depure as requisições
Defina
SQUARECLOUD_DEBUG: 1noenvda etapa para registrar método, caminho, status e duração de cada requisição à API, nunca cabeçalhos ou corpos.Escolha o que enviar
O
commitdeixa de fora o que osquarecloud.ignorelista, na sintaxe do gitignore.node_modules,.gite lockfiles ficam de fora, a não ser que você os inclua de volta com!.
Já usa a @v2?
A @v2 agora aponta para a nova versão, então seu workflow continua funcionando sem mudanças. Veja o que mudou.
- O
workdiré aplicado. Até a 2.1.2 ele era ignorado e os comandos rodavam na raiz do repositório. - A chave não é mais passada na linha de comando nem salva no runner.
- Runners Windows, macOS e arm64 são suportados.
- O download da CLI é conferido com os checksums, e o novo input
versionfixa a versão. - Descobrir a CLI mais recente não chama mais a API do GitHub, então o limite de requisições da API não interfere.
- A action roda no Node 24.
A CLI 3.1 também deixa os lockfiles de fora dos uploads. Para continuar enviando o seu, adicione !package-lock.json (ou o seu lockfile) ao squarecloud.ignore.
Um plano para cada fase do seu projeto
Comece pequeno e escale quando precisar, sem contratos de fidelidade.
Hobby
Para validar ideias, bots e projetos pessoais
A partir de R$ 12,49/mês
- 1 GB de RAM
- 1 vCPU
- Até 4 projetos
- Escala até 2 GB no mesmo plano
Standard
RecomendadoPara produção, com bancos de dados e domínio próprio
A partir de R$ 44,99/mês
- 4 GB de RAM
- 4 vCPU
- Até 16 projetos
- Escala até 8 GB no mesmo plano
Pro
Para alta escala, com snapshots diários das aplicações e analytics avançado
A partir de R$ 124,99/mês
- 12 GB de RAM
- 6 vCPU
- Até 48 projetos
- Escala até 24 GB no mesmo plano
4,9 de 5 · 402 avaliações no Google + TrustpilotTrustpilot