Pular para o conteúdo principal
Conecte a sua conta ou organização do GitHub à Cube e escolha o repositório e a branch de um projeto. A cada push nessa branch, a Cube baixa o commit, troca os arquivos do projeto e instala as dependências só se o package.json ou o requirements.txt mudou. Nada de .zip, workflow ou chave de API guardada no repositório.
A Cube só lê o código dos repositórios que você liberar e nunca muda nada neles. Com o Status no GitHub autorizado, ela marca no commit só o resultado de cada deploy.

1. Conecte o GitHub

  1. No painel, abra Integrações e clique em Conectar o GitHub.
  2. O GitHub abre a página do app Cube Hosting Deploy. Escolha onde instalar: a sua conta ou uma organização.
  3. Em Repository access, marque Only select repositories e escolha os repositórios que a Cube pode ler. Clique em Install.
  4. O GitHub pede para autorizar o app com a sua conta. Isso confirma que a instalação é sua, e a Cube não guarda nada dessa autorização.
  5. Você volta ao painel com o aviso GitHub conectado e vê os repositórios liberados.
Numa organização em que você não é dono, o GitHub manda um pedido ao dono. Quando ele aprovar, quem conecta é ele, ou quem administra todos os repositórios liberados: ser membro da organização ou colaborador de um repositório não basta.
Para liberar mais repositórios depois, clique em Repositórios no GitHub na conexão, em Integrações. Numa organização, depois de liberar, clique em Conectar o GitHub de novo para o repositório novo aparecer na Cube.

2. Hospede um repositório

No painel, clique em Novo projeto e escolha a aba GitHub:
  1. Escolha o repositório (dá para buscar pelo nome) e a branch.
  2. Num repositório com mais de um app, preencha a Pasta raiz do app, como apps/web. Vazio, vale o repositório inteiro.
  3. Clique em Analisar e configurar. A Cube baixa o último commit da branch e mostra o que achou, como no envio do .zip: linguagem, versão, arquivo principal e comando de início. Um cube.json na raiz do repositório (ou da Pasta raiz) preenche a configuração.
  4. Confira e clique em Enviar e instalar.
O projeto já nasce ligado ao repositório, com o deploy a cada push ligado.

Ligar um projeto que já existe

Na página do projeto, abra Configurações › Deploy:
  1. Em Modo de deploy, escolha GitHub.
  2. Em Repositório, escolha o repositório; em Branch, a branch.
  3. Num monorepo, escreva a Pasta raiz do app (opcional).
  4. Deixe Deploy a cada push ligado (desligado, o código só muda quando você clicar em Implantar agora).
  5. Clique em Salvar alterações.
Para voltar ao envio de .zip, escolha Envio de .zip no mesmo lugar e salve.

Monorepo: Pasta raiz

Num repositório com mais de um app (um monorepo, como apps/api e apps/web), a Pasta raiz faz o projeto usar só uma pasta do repositório para instalar e rodar. Assim o mesmo repositório serve um projeto por pasta, e cada projeto leva só o que é dele.
  • Escreva o caminho a partir da raiz do repositório, separado por /: apps/web, sem .. e sem \. As letras maiúsculas e minúsculas contam. Vazio, vale o repositório inteiro.
  • Um arquivo com \ no nome (apps\web\x.js, criado fora do Windows) conta como pastas, como num .zip do Windows: ele fica em apps/web/x.js. Com a Pasta raiz apps ou apps/web, ele entra na pasta, mas só se ela existir de verdade no repositório: um apps\web\x.js sozinho não cria a pasta apps/web para escolher. Dois arquivos que dão o mesmo caminho (a\b e a/b) param o deploy com unsafe_zip, com e sem a Pasta raiz.
  • A pasta tem de existir na branch escolhida; senão, o painel mostra root_directory_not_found no próprio campo.
  • A pasta vale como a raiz do projeto: o cube.json, o package.json (ou o requirements.txt, o go.mod…) e o index.html que a Cube lê são os da pasta, e os comandos rodam dentro dela.
  • O limite do .zip do plano vale para a pasta compactada (root_directory_too_large). O repositório inteiro pode ter até 100 MB compactado; acima disso, o deploy para com repository_too_large.
  • Um push que não mexe em nenhum arquivo da pasta não reinstala o projeto: o push só em apps/api não mexe no projeto de apps/web. Na dúvida, a Cube implanta: num force push, numa branch nova ou num push com 2.048 commits ou mais de uma vez (o máximo que o GitHub lista no aviso do push). Implantar agora sempre implanta.
  • Para trocar a pasta, mude em Configurações › Deploy e salve. Trocar só a pasta não implanta: o código novo chega no próximo push ou no Implantar agora.
A Cube usa só a pasta: nada de fora dela entra no projeto. Num monorepo com workspaces (npm, Yarn ou pnpm workspaces, Turborepo, Nx), as dependências workspace:* e o lockfile que ficam na raiz do repositório não chegam à pasta, e a instalação não acha esses pacotes. Deixe o app instalável sozinho dentro da pasta: as dependências publicadas no registro (ou o código delas copiado para dentro da pasta) e o próprio lockfile nela. Se não der, use o GitHub Actions: o CI roda o build com o monorepo inteiro e envia só o resultado.

O que acontece em cada push

  • Só a branch escolhida conta. Push em outra branch, tag ou branch apagada não mexe no projeto.
  • Com a Pasta raiz, só conta o push que mexe em algum arquivo da pasta.
  • A Cube baixa o commit do push e troca todos os arquivos do projeto pelos do repositório (ou da Pasta raiz), como no envio de um .zip novo. As pastas node_modules, venv, .venv, .git e __pycache__ ficam de fora.
  • As dependências só são instaladas de novo se o package.json (com o lock) ou o requirements.txt mudou. O build do cube.json roda de novo.
  • Se o projeto estava no ar, ele volta com o código novo. Parado, continua parado.
  • Chegou um push enquanto uma instalação ainda roda? A Cube espera ela terminar e implanta o push mais novo.
  • A configuração do projeto (tipo, comando, memória, versão) continua a de Configurações › Geral; o cube.json só vale na criação.
O repositório compactado segue o limite do .zip do plano: 5 MB no Free e 10 MB nos pagos. Arquivos grandes que o projeto não usa (vídeos, backups, dumps) fazem o deploy parar com repository_too_large. Num repositório com mais de um app, a Pasta raiz faz o limite valer só para a pasta do app.
Variáveis como o token do bot ficam em Variáveis de ambiente, nunca no repositório.

Implantar agora

Em Configurações › Deploy, Implantar agora manda na hora o último commit da branch, pelo mesmo caminho do push. Serve para o primeiro deploy depois de ligar o GitHub e para quando o deploy a cada push está desligado.

Histórico de envios

Cada push e cada Implantar agora aparecem no Histórico de envios (Configurações › Deploy) com o commit: os 7 primeiros caracteres, a mensagem e quem fez, além do resultado da instalação. O código de cada commit implantado fica guardado como versão, para baixar ou voltar para ele: veja Versões e voltar atrás. Quando o deploy para antes da instalação, o histórico diz o motivo e nada muda no projeto:

Status no GitHub

Com o Status no GitHub, o resultado de cada push e de cada Implantar agora aparece no próprio commit, no GitHub, com o nome Cube Hosting (com a Pasta raiz, Cube Hosting · apps/web, uma linha por pasta): O link Details do status abre Configurações › Deploy do projeto, com o motivo completo. A descrição nunca leva log, variável nem nada do projeto (nem o nome dele: a linha leva só a pasta), porque num repositório público qualquer pessoa vê o commit. Veja em Configurações › Deploy, na linha Status no GitHub:
  • Ligado: cada deploy já aparece no commit.
  • Falta autorizar no GitHub: o app Cube Hosting Deploy pede uma permissão nova, a de marcar o status do commit (Commit statuses). Clique em Autorizar no GitHub, revise o pedido do app e aceite. Numa organização, quem aceita é o dono dela. Até aceitar, o deploy segue igual, só sem o status. Depois de aceitar, a linha mostra Ligado em alguns minutos.
  • Em breve: o recurso ainda não foi liberado. O resultado fica só no histórico de envios.
O primeiro envio de um projeto criado pelo Novo projeto não marca o commit; os pushes e os Implantar agora seguintes, sim. Dois projetos ligados à mesma branch do mesmo repositório com a mesma Pasta raiz (ou os dois sem ela) dividem a mesma linha no commit, e vale o resultado do último; com pastas diferentes, cada um tem a sua.

Desconectar

Em Integrações, Desconectar tira o app da conta ou organização no GitHub. Os projetos ligados a ela voltam ao envio de .zip, e o que está no ar continua no ar. Remover o app direto nas configurações do GitHub tem o mesmo efeito. Se o GitHub não responder na hora, a Cube desliga a conexão do mesmo jeito e avisa que o app ficou instalado lá. Para tirar, abra Repositórios no GitHub e clique em Uninstall.

Segurança

  • O app pede só leitura do conteúdo dos repositórios que você escolher e, para o Status no GitHub, a permissão de marcar o status do commit. Ele não muda o código, não abre pull request e não vê os outros repositórios.
  • A conexão fica presa à conta da Cube que clicou em Conectar, e só o dono da instalação conecta: a própria conta pessoal do GitHub ou, numa organização, quem administra todos os repositórios liberados (a Cube fica só com esses). Um colaborador ou membro sem esse acesso não liga a sua instalação à conta dele, e a mesma instalação não fica em duas contas.
  • Cada download usa uma autorização do GitHub que vale 1 hora e só para aquele repositório, e ela nunca é guardada. O status do commit usa outra, também só daquele repositório, que só marca o status e nem lê o código.
  • O código do repositório passa pelo mesmo caminho seguro do .zip: é conferido e instalado separado de todos os outros projetos. Veja Segurança.

GitHub Actions ou o deploy pelo GitHub?