Repositório privado no Coolify: GitHub App ou deploy key

Resposta rápida

O Coolify lê um repositório privado de dois jeitos. Com o GitHub App, em Sources > New Source > GitHub App, você registra um aplicativo no GitHub, escolhe os repositórios que ele lê e ganha deploy automático a cada push. Com a deploy key, em Keys & Tokens > Private Keys > New Private Key, você gera uma chave SSH, cadastra a chave pública no repositório, sem escrita, e cria a aplicação com a URL SSH. A deploy key serve para qualquer Git, mas o deploy automático exige um webhook manual.

O painel do Coolify é em inglês. Neste manual, os botões aparecem como estão na tela, em negrito, com a tradução ao lado. Dúvida com algum termo? Veja o glossário do Coolify em português.

Você vai aprender

Escolher entre GitHub App e deploy key
Registrar o GitHub App e escolher os repositórios
Gerar uma deploy key e cadastrar a chave pública, só para leitura
Criar a aplicação com a URL SSH e ligar o deploy automático

Antes de começar

Um projeto criado (projetos e ambientes)
Acesso de administrador ao repositório no GitHub ou no Git que você usa
Para o GitHub App, o painel no seu domínio com HTTPS (domínio do painel)

Neste guia

Qual caminho escolher
Caminho 1: GitHub App
Caminho 2: deploy key
GitLab, Bitbucket e Gitea
Problemas comuns

Qual caminho escolher

Nos dois caminhos, o Coolify só lê o código: ele não precisa de permissão de escrita no repositório.

GitHub App ou deploy key
	GitHub App	Deploy key
Onde funciona	GitHub	Qualquer Git com SSH
Acesso	Os repositórios escolhidos na instalação	O repositório em que a chave foi cadastrada
Deploy a cada push	Já vem configurado	Precisa de webhook manual
Indicado para	Quem usa GitHub e quer publicar a cada push	Um repositório só, ou Git fora do GitHub

Caminho 1: GitHub App

Abra Sources e clique em New Source
No painel: IntegrationsSources(Integrações › Fontes)
A página Sources (fontes) guarda as ligações com GitHub, GitLab e Gitea. Clique em New Source (nova fonte).
Escolha GitHub App
O menu mostra as três integrações. Clique em GitHub App. As outras, GitLab App e Gitea / Forgejo App, seguem a mesma ideia.
Dê um nome e siga para o GitHub
Digite um nome para a fonte. Para um app de organização, preencha Organization com o nome dela; para a sua conta pessoal, deixe em branco. O endereço do webhook é só o endereço base do painel, como https://painel.example.com.
Dica System wide libera o app para todas as equipes do Coolify. Deixe desligado se só a sua equipe vai usar.
Crie o app e instale nos repositórios
Esta parte acontece no GitHub. O Coolify já envia o pedido pronto, com permissões, webhook e chave.
- As permissões obrigatórias são de leitura: conteúdo, metadados e e-mail. As de pull request e deployments são opcionais.
- Dê ao app um nome único no GitHub e confirme. O Coolify guarda as credenciais sozinho.
- Na instalação, escolha All repositories (todos) ou Only select repositories (só os escolhidos). Prefira a segunda.
Crie a aplicação pelo GitHub App
No ambiente do projeto, clique em New Resource e escolha Git Repository (with GitHub App). Selecione a fonte e o repositório. Daí em diante, o formulário é o mesmo do repositório público: branch, build pack, porta e pasta.

O GitHub precisa alcançar o painel

O deploy automático do GitHub App é um webhook: a cada push, o GitHub chama o seu painel. Se ele não alcança esse endereço, o acesso ao repositório funciona, mas o deploy automático não. Com o painel no seu domínio e HTTPS, o caminho é pelas portas 80 e 443.

Caminho 2: deploy key

A deploy key é uma chave SSH: o Coolify guarda a parte privada, e o repositório recebe a parte pública.

Abra Private Keys e clique em New Private Key
No painel: Keys & TokensPrivate Keys(Chaves e tokens › Chaves privadas)
A localhost's key é a chave com que o Coolify acessa a própria VPS: deixe essa como está. Clique em New Private Key (nova chave privada).
Clique em Generate ED25519
O Coolify gera e salva a chave na hora. Generate RSA fica para o Git que não aceita ED25519.
1. Generate ED25519: gera uma chave nova, do tipo recomendado.
2. Add manually: cola uma chave que você já tem.
Dê um nome e copie a chave pública
Abra a chave nova pela engrenagem da coluna Actions, dê um nome que lembre o repositório, como deploy-site-da-loja, e copie a chave pública. A chave privada fica só no Coolify.
Cadastre a chave pública no repositório
No GitHub, abra o repositório, vá em Settings > Deploy keys e adicione a chave pública. Deixe a permissão de escrita (Allow write access) desmarcada: o Coolify só precisa ler.
Dica No GitLab, a chave entra nas deploy keys do projeto. No Bitbucket, nas access keys do repositório. Nos dois, sem escrita.
Escolha Private Git Repository (with Deploy Key)
No ambiente do projeto, clique em New Resource, escolha Private Git Repository (with Deploy Key) e selecione a chave criada. Sem nenhuma chave disponível, a tela mostra No private keys e o botão Create Private Key (criar chave privada).
Cole a URL SSH e publique
Use o endereço SSH do repositório, não o HTTPS. O resto é igual ao do repositório público. Depois do Deploy, confira no log se o código foi baixado.

git@github.com:empresa/projeto.git
git@gitlab.com:empresa/projeto.git
git@bitbucket.org:empresa/projeto.git

Formato da URL SSH em cada Git. O endereço que começa com https:// não funciona com deploy key.

Deploy key não publica sozinha a cada push

A chave só dá acesso ao código. Para publicar a cada push, cadastre um webhook manual no repositório e ligue o deploy automático (Advanced > Deployment > Auto deploy), ou chame o Deploy Webhook da sua esteira de CI. O passo a passo está em deploy automático e rollback.

GitLab, Bitbucket e Gitea

Todos aceitam deploy key. O GitLab tem também o GitLab App, e o Gitea / Forgejo App atende Gitea, Forgejo e Codeberg. No Bitbucket, a deploy key se chama access key. O deploy automático usa webhook com o evento de push.

Como saber se deu certo

A fonte aparece em Sources ou a chave em Private Keys, e o log do deploy mostra o código baixado do repositório privado.

Problemas comuns

O deploy falha ao baixar o código, com Permission denied (publickey)

Causa provável: A chave pública não está no repositório, foi cadastrada em outro repositório ou a URL usada é HTTPS.
O que fazer: Confira a chave em Settings > Deploy keys do repositório e use a URL SSH, no formato git@github.com:empresa/projeto.git.

O push não dispara o deploy

Causa provável: Com deploy key, falta o webhook manual. Com GitHub App, o GitHub não alcança o painel.
O que fazer: Cadastre o webhook (deploy automático). No GitHub App, as configurações do app no GitHub mostram as entregas do webhook e o erro de cada uma.

O repositório não aparece na lista do GitHub App

Causa provável: Ele ficou de fora dos repositórios escolhidos na instalação.
O que fazer: Inclua o repositório nas configurações do app no GitHub.

Não resolveu? Veja os problemas comuns do Coolify ou abra um chamado na central do cliente.

Próximo passoBuild packs no Coolify: Railpack, Dockerfile, Compose e imagem prontaO que muda entre Railpack, Static, Dockerfile, Docker Compose e imagem pronta, quando usar cada um e a porta que cada um espera.

Fontes e documentação oficial

Coolify é um software de código aberto mantido pelo próprio projeto. Este manual é da Hospedagem Segura, para quem roda o Coolify nas nossas VPS, e foi conferido na versão 4.7.5.

Continue aprendendo

Ver todos os guias do Manual do Coolify

Rode o Coolify numa VPS da Hospedagem Segura

VPS Linux com acesso root, disco NVMe e IPv4 dedicado a partir de R$ 69,90/mês. Prefere a VPS pronta? No VPS Assistido, o Coolify vem instalado, com o painel no seu domínio, e a equipe ajuda no dia a dia.

Ver VPS para Coolify Conhecer o VPS Assistido