Build Automatizado e CI/CD Para Jogos: Pare de Exportar na Mao
Build automatizado e CI/CD para jogos: aprenda a montar um pipeline com Godot e GitHub Actions que exporta e publica seu jogo a cada push, sem trabalho manual.
Todo dev indie conhece esse ritual: terminou o patch, abre a Godot, exporta para Windows, exporta para Linux, exporta para Web, zipa tudo, sobe no itch.io, sobe na Steam, torce para nao ter esquecido nada. Um build automatizado acaba com esse ritual. Com CI/CD para jogos, cada push no repositorio dispara um pipeline que exporta, empacota e publica o jogo sozinho, sempre do mesmo jeito, sem depender da sua maquina nem da sua memoria. Neste guia voce vai montar isso na pratica com Godot 4 e GitHub Actions, do primeiro comando headless ate o upload automatico para o itch.io.
O problema: exportar na mao nao escala
Exportar manualmente funciona ate a primeira vez que da errado. E ela sempre chega, geralmente assim:
- Voce exporta para Windows e Linux, mas esquece a versao Web. Jogadores do navegador ficam uma semana com o bug que voce ja corrigiu.
- O build sai da sua maquina com uma versao diferente dos export templates, e um crash que "nunca acontece aqui" aparece so no executavel dos jogadores.
- No meio da correria de um hotfix, voce zipa a pasta errada, ou sobe o build de debug em vez do release.
- Seu colega de equipe nao consegue gerar o build porque o projeto "so exporta direito" no seu computador. O famoso "funciona na minha maquina" aplicado a distribuicao.
Cada exportacao manual e uma sequencia de uns dez passos repetidos por plataforma. Humanos sao ruins em repetir dez passos sem errar, ainda mais sob pressao de lancamento. Maquinas sao otimas nisso. A ideia do CI/CD e simplesmente entregar esse trabalho repetitivo para uma maquina.
Antes de automatizar, o projeto precisa estar inteiro no repositorio, incluindo os assets binarios. Se ainda nao configurou isso, veja como funciona o controle de versao para jogos com Git e Git LFS, porque o pipeline vai clonar o repositorio do zero a cada build: o que nao estiver versionado nao entra no jogo final.
O que e CI/CD para jogos, traduzido
CI/CD e sigla para integracao continua e entrega continua. Traduzindo para o vocabulario de quem faz jogo:
CI (integracao continua): toda vez que alguem envia codigo para o repositorio, um servidor baixa o projeto e verifica que ele continua saudavel. No minimo, confirma que o jogo exporta sem erro. Se voce tiver testes automatizados, roda os testes tambem. Se algo quebrar, voce descobre em minutos, no commit exato que causou o problema, e nao tres semanas depois na vespera do lancamento.
CD (entrega continua): alem de verificar, o servidor gera os builds finais de cada plataforma e os deixa prontos para publicar, ou publica direto. O resultado pratico: soltar um patch vira dar um push, esperar dez minutos e conferir que a nova versao esta no ar.
O servidor que faz isso e um servico de CI. O mais acessivel para indie e o GitHub Actions, que ja vem embutido no GitHub: voce descreve os passos do build num arquivo YAML dentro do repositorio, e o GitHub executa esses passos numa maquina virtual Linux a cada push. Para repositorio publico e de graça; para privado, o plano gratuito da 2000 minutos por mes, o que e bastante para um jogo indie.
A base de tudo: exportar a Godot pela linha de comando
Automatizar so e possivel porque a Godot 4 exporta sem abrir o editor. O modo headless roda a engine sem janela nem GPU, perfeito para um servidor. O comando central e este:
# Exporta o build de release usando o preset "Windows Desktop"
godot --headless --export-release "Windows Desktop" build/jogo.exe
# Variante de debug, com console e simbolos, para testar
godot --headless --export-debug "Windows Desktop" build/jogo-debug.exe
Tres detalhes fazem esse comando funcionar ou falhar:
- O nome do preset ("Windows Desktop", "Linux", "Web") precisa ser exatamente o nome configurado em Projeto, Exportar dentro do editor. Esses presets ficam salvos no arquivo
export_presets.cfg, na raiz do projeto. Esse arquivo tem que estar versionado no Git, senao o servidor de CI nao tem como saber o que exportar. - Os export templates da mesma versao da engine precisam estar instalados na maquina que roda o comando. Templates 4.3 com editor 4.4 nao funcionam. No CI, a instalacao dos templates vira um passo do pipeline.
- A pasta de destino precisa existir antes do comando, entao o pipeline cria a pasta
build/antes de exportar.
Se voce nunca exportou nem manualmente, comece entendendo o processo no editor com o guia de como exportar seu jogo na Godot para Windows. O pipeline automatiza exatamente aqueles passos, entao ajuda saber o que cada um faz.
Teste o comando na sua maquina antes de levar para o CI. Se ele funciona no seu terminal, a chance de funcionar no servidor e alta, porque o ambiente do CI e mais limpo e previsivel que o seu desktop.
O workflow completo no GitHub Actions
Crie o arquivo .github/workflows/build.yml no repositorio. O YAML abaixo e um pipeline real e comentado que exporta o jogo para Windows a cada push na branch principal:
name: Build do jogo
on:
push:
branches: [main]
env:
GODOT_VERSION: '4.4'
NOME_JOGO: MeuJogo
jobs:
exportar-windows:
runs-on: ubuntu-latest
steps:
# 1. Baixa o codigo do repositorio.
# lfs: true garante que assets no Git LFS venham junto.
- name: Checkout do projeto
uses: actions/checkout@v4
with:
lfs: true
# 2. Baixa a Godot headless e os export templates.
# IMPORTANTE: engine e templates da MESMA versao.
- name: Instalar Godot e export templates
run: |
wget -q https://github.com/godotengine/godot/releases/download/${GODOT_VERSION}-stable/Godot_v${GODOT_VERSION}-stable_linux.x86_64.zip
wget -q https://github.com/godotengine/godot/releases/download/${GODOT_VERSION}-stable/Godot_v${GODOT_VERSION}-stable_export_templates.tpz
unzip -q Godot_v${GODOT_VERSION}-stable_linux.x86_64.zip
mv Godot_v${GODOT_VERSION}-stable_linux.x86_64 godot
mkdir -p ~/.local/share/godot/export_templates/${GODOT_VERSION}.stable
unzip -q Godot_v${GODOT_VERSION}-stable_export_templates.tpz
mv templates/* ~/.local/share/godot/export_templates/${GODOT_VERSION}.stable/
# 3. Exporta o jogo em modo headless.
# "Windows Desktop" e o nome do preset no export_presets.cfg.
- name: Exportar para Windows
run: |
mkdir -p build/windows
./godot --headless --export-release "Windows Desktop" build/windows/${NOME_JOGO}.exe
# 4. Publica o resultado como artefato baixavel
# na pagina da execucao do workflow.
- name: Guardar artefato
uses: actions/upload-artifact@v4
with:
name: build-windows
path: build/windows
O que acontece a cada push: o GitHub sobe uma maquina Linux limpa, clona seu projeto, instala a Godot com os templates certos, roda o mesmo comando de exportacao que voce testou no terminal e anexa o build pronto na pagina do workflow, onde qualquer pessoa da equipe baixa o zip. Para exportar Linux e Web tambem, e so duplicar o passo 3 trocando o preset e a pasta de destino: a engine ja esta instalada, os passos extras custam segundos.
Se preferir nao escrever a instalacao da Godot na mao, a comunidade mantem actions prontas que fazem esse trabalho, como a firebelley/godot-export e imagens Docker como a barichello/godot-ci, que ja vem com engine e templates instalados. Elas encurtam o YAML, mas saber o que acontece por baixo ajuda muito na hora de depurar um build que falhou.
Publicando automatico no itch.io com o butler
Gerar o build sozinho ja e otimo, mas da para fechar o ciclo: publicar sozinho. Para o itch.io, a ferramenta oficial e o butler, um executavel de linha de comando mantido pelo proprio itch. Ele envia builds por canal (windows, linux, web) e so transmite a diferenca entre a versao nova e a anterior, o que torna o upload rapido mesmo com jogo grande.
Primeiro, gere uma API key na sua conta do itch.io (em configuracoes, API keys) e salve no repositorio do GitHub como secret com o nome BUTLER_API_KEY. Depois adicione estes passos no fim do job:
# 5. Instala o butler, a CLI oficial do itch.io
- name: Instalar butler
run: |
wget -q -O butler.zip https://broth.itch.zone/butler/linux-amd64/LATEST/archive/default
unzip -q butler.zip
chmod +x butler
# 6. Envia o build para o canal windows do seu jogo.
# Troque seu-usuario/seu-jogo pela sua pagina no itch.
- name: Publicar no itch.io
env:
BUTLER_API_KEY: ${{ secrets.BUTLER_API_KEY }}
run: |
./butler push build/windows seu-usuario/seu-jogo:windows --userversion 1.0.${{ github.run_number }}
O parametro --userversion carimba cada build com um numero de versao visivel na pagina do itch. Usar o github.run_number garante que cada execucao gera um numero novo e crescente, sem voce precisar lembrar de atualizar nada.
E a Steam?
A Steam tambem tem upload por linha de comando: o sistema se chama SteamPipe e funciona atraves da ferramenta steamcmd, que le um script de build em formato VDF e envia o depot para o branch que voce escolher no Steamworks. E totalmente automatizavel no mesmo workflow, com as credenciais guardadas como secrets, mas a configuracao de conta, depots e branches merece cuidado proprio. O fluxo completo de patch na Steam, incluindo branch beta antes de ir para o publico, esta detalhado no guia de como atualizar seu jogo na Steam com patches.
Quando vale a pena montar isso
A conta e simples. O setup do pipeline custa uma tarde de trabalho na primeira vez. Cada rodada manual de exportar para tres plataformas, zipar e subir custa de 30 a 60 minutos, com risco real de erro em cada rodada.
Antes do lancamento, enquanto voce so gera build para playtest de vez em quando, da para viver sem. A partir do primeiro patch pos-lancamento, o pipeline ja se pagou: hotfix vira push, e o build que chega aos jogadores e gerado sempre no mesmo ambiente limpo, nao na maquina de quem estava disponivel na hora. Para jogo com versao Web no itch.io, o ganho e ainda maior, porque atualizar a versao do navegador deixa de ser um passo separado que todo mundo esquece.
Ha um beneficio menos obvio: o build para de depender de uma pessoa. Em equipe pequena, se so voce sabe exportar, voce e o gargalo de todo lancamento. Com o pipeline no repositorio, qualquer pessoa com permissao de push consegue soltar uma versao.
Erros comuns que quebram o pipeline
Quase todo build automatizado que falha cai num destes casos:
- export_presets.cfg fora do repositorio. O arquivo esta no seu
.gitignoreou nunca foi commitado, e o CI falha dizendo que o preset nao existe. Versione o arquivo. Se ele contiver segredo (senha de keystore Android, por exemplo), mova o segredo para variavel de ambiente e mantenha o resto versionado. - Templates de versao diferente da engine. Editor 4.4 com templates 4.3 gera erro de template nao encontrado, ou pior, um build sutilmente quebrado. No YAML acima, engine e templates saem da mesma variavel
GODOT_VERSIONjustamente para nunca divergirem. - Build sem numero de versao. Sem carimbo de versao, voce recebe um report de bug e nao sabe qual build o jogador esta rodando. Use
--userversionno butler e mostre a versao na tela inicial do jogo. - Assets faltando por causa do LFS. Sem
lfs: trueno checkout, os arquivos do Git LFS chegam como ponteiros de texto e o jogo exporta com texturas e audios corrompidos. O build sai verde, mas o jogo abre quebrado. - Nome do preset digitado diferente. "Windows Desktop" no editor e "windows desktop" no YAML nao sao a mesma coisa. Copie o nome exato do export_presets.cfg.
Comece pequeno, automatize um passo por vez
Nao tente montar o pipeline inteiro de uma vez. A ordem que funciona: primeiro faca o comando headless exportar na sua maquina. Depois leve esse comando para um workflow que so gera o artefato. Quando isso estiver estavel, adicione o butler e o canal do itch.io. A Steam entra por ultimo, quando o resto ja roda sozinho ha algumas semanas.
Cada etapa dessas ja entrega valor sozinha, e em uma ou duas tardes voce sai do ritual manual para um fluxo em que publicar patch e rotina de dez minutos, nao um evento estressante. Seu tempo de producao volta para onde ele rende: fazer o jogo, nao empacotar o jogo.
Perguntas frequentes
O que e um build automatizado de jogo?
E um build gerado por um servidor de CI (como o GitHub Actions) toda vez que voce envia codigo para o repositorio. O pipeline baixa o projeto, exporta o jogo pela linha de comando da engine e publica o resultado, sem ninguem clicar em Exportar no editor.
O GitHub Actions e gratuito para projetos de jogos?
Para repositorios publicos, sim, sem limite pratico. Para repositorios privados, o plano gratuito inclui 2000 minutos por mes de maquina Linux, o que cobre com folga dezenas de builds de um jogo indie 2D. Builds maiores ou com LFS pesado podem exigir plano pago.
A Godot consegue exportar o jogo sem abrir o editor?
Sim. A Godot 4 exporta pela linha de comando com godot --headless --export-release "Nome do Preset" caminho/arquivo. Basta ter os export templates da mesma versao instalados na maquina e o export_presets.cfg versionado junto com o projeto.
Como envio o build automaticamente para o itch.io?
Com o butler, a ferramenta oficial de linha de comando do itch.io. O comando butler push pasta usuario/jogo:canal envia o build para um canal da sua pagina, e o itch so publica o que mudou entre versoes. No CI, a autenticacao e feita pela variavel BUTLER_API_KEY.
Devo versionar o export_presets.cfg no Git?
Sim, ele e essencial: guarda os presets de exportacao que o comando headless usa. Sem ele no repositorio, o CI nao sabe como exportar. So tome cuidado com segredos, como senhas de keystore Android, que devem ficar fora dele, em variaveis de ambiente.
CI/CD vale a pena para um dev solo?
Vale a partir do momento em que voce publica o jogo e precisa soltar patches. O setup leva uma tarde e elimina o ciclo manual de exportar, zipar e subir para cada plataforma, que e lento e propenso a erro justamente quando voce esta corrigindo um bug urgente.
