# Git Deploy

> Conecte seu servidor a um repositório do GitHub, GitLab, Gitea ou Forgejo e faça deploy automaticamente a cada push, release ou tag, com caminhos protegidos, reinícios, verificações de CI e rollback com um clique.

A aba **Git Deploy** no Portal conecta seu servidor a um repositório Git no **GitHub**, **GitLab**, **Gitea** ou **Forgejo**. Os arquivos dele são copiados para o seu servidor automaticamente — a cada push, quando você publica uma release, quando envia uma tag, ou com o clique de um botão. Se quiser, o seu servidor é parado com segurança antes do deploy e iniciado de novo depois.

Resumindo: envie o seu código e, alguns segundos depois, ele está rodando no seu servidor. Sem mais upload via SFTP, sem descompactar arquivos ZIP no gerenciador de arquivos, sem reinícios esquecidos.

## O que você vai aprender

- Como conectar um repositório, com o app GitHub Daki Git Deploy ou com um token de acesso
- Quando um deploy é executado e como disparar um você mesmo
- Como manter mundos, bancos de dados e arquivos `.env` seguros com caminhos protegidos
- Como funcionam os reinícios, o histórico de deploys, os rollbacks e o status no seu repositório
- Como dar à sua equipe as permissões certas

---

## Para quem é

- **Desenvolvedores de bots do Discord e de apps Node.js, Python ou Java** cujo código já está no GitHub ou no GitLab.
- **Redes de Minecraft e equipes de servidores de jogos** que mantêm plugins, configurações ou datapacks em um repositório e querem que as mudanças sejam publicadas de forma rastreável.
- **Equipes:** várias pessoas trabalham no repositório, o servidor está sempre atualizado, e as permissões dos subusuários definem exatamente quem pode fazer deploy.
- **Projetos baseados em releases:** só versões publicadas (por exemplo, um `.jar` pronto de uma release) chegam ao servidor, não cada trabalho em andamento.

---

## Antes de começar

- Um servidor no Portal que mostre a aba **Git Deploy**. Ela fica na navegação do servidor, em **Essentials**, logo após **Files** por padrão.
- Um repositório no GitHub (github.com), GitLab (gitlab.com ou sua própria instância, incluindo subgrupos como `grupo/subgrupo/projeto`), Gitea ou Forgejo (por exemplo, Codeberg ou sua própria instância). Repositórios públicos e privados funcionam.

> **Nota:** A Daki decide, por tipo de servidor (egg), se a aba é exibida. Se você não vir **Git Deploy**, ela não está habilitada para o tipo do seu servidor.

> **Info:** Este guia usa os rótulos em inglês da aba Git Deploy. A aba está disponível em 19 idiomas e segue o idioma que você escolheu no Portal — os botões ficam no mesmo lugar em todos os idiomas.

---

## Início rápido com GitHub (recomendado)

O caminho mais rápido: conecte-se pelo **Daki Git Deploy**, o app oficial do GitHub da Daki Hosting. Você entra no GitHub e escolhe os seus repositórios — **sem token e sem webhook**.

**Passo 1: Abra a aba Git Deploy**

No Portal, abra o seu servidor e vá para a aba **Git Deploy**. Em **Git service**, escolha **GitHub**.

**Passo 2: Conecte com o GitHub**

Na caixa **GitHub access**, clique em **Connect with GitHub**. Entre no GitHub e autorize o app.

Na primeira vez, o GitHub leva você direto para escolher quais repositórios o app pode acessar (**All repositories** ou apenas alguns selecionados) — uma etapa só, em vez de duas. Depois, você volta ao Portal, e a caixa **GitHub access** mostra **Connected via Daki Git Deploy as** com o seu nome no GitHub. A caixa **Webhook** confirma que não há nada para configurar: os pushes e as releases chegam pelo app sozinhos.

**Passo 3: Escolha o seu repositório e o branch**

Clique em **Choose from my repositories** e selecione o seu repositório, ou cole a URL web ou de clone, ou informe o caminho. Clique em **Load branches** e escolha o branch que será publicado. Deixe o campo vazio para usar o branch padrão do repositório.

**Passo 4: Escolha quando e como fazer o deploy**

Em **When to deploy**, escolha um modo (por exemplo, **Every push**). Depois, defina a pasta de destino, os seus [caminhos protegidos](#protected-paths) e o [comportamento de reinício](#restart-behavior).

**Passo 5: Salve**

Clique em **Save settings** na barra na parte inferior. Pronto: o cabeçalho da aba mostra **Automatic deploys on**, e o seu próximo push será publicado automaticamente. Para fazer o deploy agora mesmo, clique em **Deploy now** no canto superior direito.

- **Permitir outro repositório:** **Choose repositories on GitHub** abre de novo a seleção de repositórios no GitHub, onde você escolhe a quais repositórios o Daki Git Deploy pode acessar.
- **Remover a conexão:** clique em **Disconnect**. Depois disso, o servidor não faz mais deploy a partir de repositórios privados.

> **Dica:** Você nunca precisa renovar nada. Para cada deploy, o Portal busca em segundo plano uma chave nova e de curta duração no GitHub (válida por 1 hora), que chega apenas ao único repositório do seu servidor.

---

## Início rápido com um token de acesso

Para **GitLab**, **Gitea** e **Forgejo** — e para o GitHub, se você preferir — você salva um token de acesso pessoal. Repositórios públicos funcionam sem nenhum token.

**Passo 1: Escolha o serviço Git**

Abra o seu servidor → **Git Deploy** e escolha o **Git service**. Para a sua própria instância de GitLab, Gitea ou Forgejo, informe a URL do servidor (por exemplo, `https://codeberg.org` ou `https://git.example.com`). Para o gitlab.com, deixe o campo vazio.

**Passo 2: Informe o repositório**

Informe o repositório como um caminho (`dono/nome`) ou simplesmente cole a URL web ou de clone dele. Para um repositório **público**, só isso basta — sem token, a caixa de acesso mostra **No token – public repositories only**.

**Passo 3: Salve um token para repositórios privados**

No GitHub, primeiro clique em **Use an own access token instead** na caixa **GitHub access**. Depois, crie um token no seu provedor Git — o link **Create a token on …** no Portal leva você direto à página certa — e salve-o em **Personal access token**. O Portal verifica o token imediatamente. Veja [Permissões do token](#token-permissions) para as permissões que ele precisa.

**Passo 4: Escolha as suas configurações e salve**

Escolha quando fazer o deploy, a pasta de destino, os caminhos protegidos e o comportamento de reinício, depois clique em **Save settings**.

**Passo 5: Adicione o webhook**

A caixa **Webhook** mostra o **Payload URL** e o **Secret**, cada um com um botão de copiar. Adicione-os ao seu repositório conforme descrito em [Configure o webhook](#set-up-the-webhook). Abaixo da caixa, **Last delivery** mostra se o webhook está chegando.

**Passo 6: Ative os deploys automáticos**

Ative **Automatic deploys active**.

### Permissões do token

| Provedor | Tipo de token | Permissões para deploys | Também necessário para o status no seu repositório |
| :--- | :--- | :--- | :--- |
| GitHub | Token de granularidade fina, somente para este repositório | *Contents: Read-only* (para **Wait for CI checks** também *Actions: Read-only*) | *Commit statuses* e *Deployments*: *Read and write* |
| GitLab | Token de acesso pessoal, de projeto ou de grupo | `read_api` + `read_repository` | `api` no lugar de `read_api`, papel Developer |
| Gitea / Forgejo | Settings → Applications | `repository: Read`, `user: Read` | `repository: Read and Write` |

Se apenas a permissão de escrita para o status estiver faltando, o seu servidor ainda recebe o deploy — o log do deploy mostra uma observação.

### Configure o webhook

**GitHub**

No seu repositório, vá para **Settings → Webhooks → Add webhook**:

1. Cole o **Payload URL** e o **Secret** do Portal.
2. Defina o content type como `application/json`.
3. Em eventos, escolha **Just the push event**. No modo de releases, escolha **Releases**.

**GitLab**

No seu projeto, vá para **Settings → Webhooks**:

1. Cole o **Payload URL** como URL e o **Secret** em **Secret token**.
2. Em gatilhos, marque **Push events**. No modo de tags, marque **Tag push events**; no modo de releases, **Releases events**.

**Gitea / Forgejo**

No seu repositório, vá para **Settings → Webhooks → Add webhook** e escolha Gitea ou Forgejo:

1. Cole o **Payload URL**, defina o content type como `application/json` e informe o **Secret**.
2. Escolha **Push events** ou, no modo de releases, **Custom events → Release**.

> **Dica:** Seu provedor Git não consegue acessar o Portal, por exemplo porque a sua instância de Gitea roda na sua rede doméstica? Escolha um intervalo em **Also check … for updates** (por exemplo **Also check Gitea for updates**). A primeira verificação faz o deploy do estado atual uma vez.

---

## Quando um deploy é executado

Em **When to deploy**, escolha um dos quatro modos:

| Modo | O que é publicado |
| :--- | :--- |
| **Manual** | Somente quando alguém clica em **Deploy now**. |
| **Every push** | Cada push para o branch escolhido. |
| **Releases** | Somente quando uma release é publicada. Você pode publicar o **código-fonte** da release ou um **arquivo da release** (por exemplo, `*.jar`) — opcionalmente salvo com um nome fixo (por exemplo, `server.jar`) e opcionalmente extraído, se for um `.zip`. Pré-releases podem ser incluídas ou deixadas de fora. |
| **Tags** | Quando uma tag que corresponde a um padrão é enviada, por exemplo `v*`. |

### Gatilhos

- **Webhook:** o seu provedor Git informa as mudanças imediatamente, e o deploy começa em segundos. Com o app do GitHub, isso acontece automaticamente, sem um webhook seu.
- **Verificações de atualização (polling):** opcionais, para casos em que o seu provedor Git não consegue acessar o Portal. Intervalos de 5 minutos a 1 dia.
- **Deploy now:** a qualquer momento, com o clique de um botão. No modo de releases, você pode escolher uma release específica.
- **Pular um push:** coloque `[skip deploy]` na mensagem do commit e esse push não é publicado. `[deploy skip]` e `[no deploy]` também funcionam.

### Aguarde as verificações de CI

Com **Wait for CI checks** ativado (somente no modo **Every push**), um commit só é publicado quando o CI dele está verde — GitHub Actions, GitLab CI e Gitea/Forgejo Actions são suportados. Se o CI falhar, o deploy é ignorado.

---

## Todas as configurações explicadas

| Seção | Configuração | O que faz |
| :--- | :--- | :--- |
| Repositório | **Git service** | GitHub, GitLab, Gitea ou Forgejo |
| Repositório | **Server URL** | Somente para instâncias próprias; precisa estar acessível pela internet |
| Repositório | **Repository** | `dono/nome` ou uma URL; **Choose from my repositories** mostra uma lista |
| Repositório | **Branch** | Vazio = branch padrão; **Load branches** mostra uma lista |
| Quando fazer deploy | **Manual** / **Every push** / **Releases** / **Tags** | Veja [Quando um deploy é executado](#when-a-deploy-runs) |
| Quando fazer deploy | **Wait for CI checks** | Somente com **Every push** |
| Quando fazer deploy | **Include pre-releases**, **What to deploy** (**Source code** / **Release file**), **Save as**, **Extract .zip files instead of uploading them** | Somente com **Releases** |
| Quando fazer deploy | **Tag pattern** | Somente com **Tags**, por exemplo `v*`; vazio = todas as tags |
| Quando fazer deploy | **Also check … for updates** (com o nome do seu serviço Git, por exemplo **Also check GitHub for updates**) | Polling: **Never (webhook only)**, 5/10/15/30 min, 1/3/6/12/24 h |
| Quando fazer deploy | **Automatic deploys active** | Desligado pausa o webhook e o polling; **Deploy now** continua funcionando |
| Quando fazer deploy | **Show deploys in the repository** | Status no commit, veja [Status no seu repositório](#status-in-your-repository) |
| Arquivos | **Folder in the repository** | Publica somente uma subpasta, por exemplo `dist`; vazio = tudo |
| Arquivos | **Target folder on the server** | Para onde os arquivos vão; `/` = a pasta principal do seu servidor |
| Arquivos | **Protected paths** | Uma regra por linha, veja [Caminhos protegidos](#protected-paths) |
| Arquivos | **Remove files that were deleted from the repository** | Limpeza opcional, veja abaixo |
| Reinício | **Restart if running** / **Always start** / **Do not restart** | Veja [Comportamento de reinício](#restart-behavior) |
| Reinício | **If the server does not stop** | Parar imediatamente, ou após 5 s, 10 s (padrão: **Kill after 10 seconds**), 15 s, 30 s, 1 min, 2 min ou 5 min |

As mudanças só têm efeito depois que você clica em **Save settings**. Enquanto houver algo não salvo, uma barra na parte inferior mostra **Discard** e **Save settings**, e **Deploy now** fica bloqueado.

**Remove files that were deleted from the repository** remove apenas arquivos que um deploy anterior gravou — nunca caminhos protegidos e nunca arquivos criados por você. Pastas vazias permanecem no lugar.

---

## Caminhos protegidos

Arquivos e pastas em **Protected paths** **nunca são sobrescritos nem excluídos** por um deploy. Se ainda não existirem, são criados uma única vez. Perfeito para mundos de jogos, bancos de dados e senhas.

Escreva uma regra por linha, relativa à pasta de destino. Linhas vazias e linhas que começam com `#` são ignoradas. `*` nunca corresponde através de um `/`.

| Regra | Protege |
| :--- | :--- |
| `world/` | Toda pasta chamada `world`, em qualquer profundidade |
| `/world/` | Somente `world` diretamente na pasta de destino |
| `*.db` | Todo arquivo que termina em `.db`, em qualquer lugar |
| `.env` | Todo arquivo chamado `.env`, em qualquer lugar |
| `/config.yml` | Somente `config.yml` diretamente na pasta de destino |
| `plugins/*/config.yml` | `config.yml` em cada subpasta direta de `plugins` |

Exemplos típicos:

**Minecraft**

```

world/

world_nether/

world_the_end/

plugins/*/config.yml

whitelist.json

ops.json

banned-*.json

```

**Bot do Discord / Node.js**

```

.env

*.db

*.sqlite

node_modules/

data/

```

**Python**

```

.env

*.db

venv/

```

---

## Comportamento de reinício

| Opção | O que acontece |
| :--- | :--- |
| **Restart if running** | O servidor é parado antes de os arquivos serem gravados e iniciado de novo depois. Um servidor desligado continua desligado. |
| **Always start** | Igual à opção acima, e um servidor desligado é iniciado depois do deploy. |
| **Do not restart** | Os arquivos são substituídos enquanto o servidor continua rodando. |

**If the server does not stop:** alguns programas, especialmente apps Node.js, ignoram o sinal de parada. Nesse caso, o servidor é encerrado à força depois do tempo que você escolher (imediatamente, de 5 segundos até 5 minutos; **Kill after 10 seconds** por padrão), para que o deploy não fique travado. Encerrar na hora é o mais rápido, mas não dá tempo ao servidor para salvar nada.

> **Nota:** Duas redes de segurança: se o servidor não desligar de jeito nenhum, **nenhum arquivo é alterado**. Se o deploy falhar depois que o servidor foi parado, o servidor é **iniciado de novo**.

---

## O que acontece durante um deploy

1. Um gatilho (push, release, tag, verificação de atualização ou botão) cria um deploy.
2. Se **Wait for CI checks** estiver ativado, ele espera pelas verificações de CI verdes (**Waiting**).
3. O **Portal** baixa o arquivo compactado do seu provedor Git. As suas credenciais nunca saem do Portal e nunca chegam ao seu servidor.
4. O arquivo é preparado: apenas a pasta escolhida, com os caminhos protegidos filtrados, e conteúdo inseguro, como links simbólicos, é descartado.
5. Conforme as suas configurações, o servidor é parado (e encerrado à força depois do tempo escolhido, se necessário).
6. Os arquivos são gravados na pasta de destino; opcionalmente, arquivos excluídos no repositório são removidos.
7. Conforme as suas configurações, o servidor é iniciado de novo.
8. O resultado e o log completo aparecem no histórico — e, se ativado, como status no commit.

Um deploy normalmente leva **de 10 a 40 segundos**, além do tempo que o seu servidor precisa para parar.

---

## Histórico, logs e rollback

A lista **Deployments** no final da aba mostra cada deploy com o seu status, branch e commit (por exemplo `main @ 75cd0a1`), número, gatilho, a pessoa que o iniciou, o horário e a mensagem do commit. O cabeçalho da aba mostra quando o servidor foi publicado pela última vez.

| Status | Significado |
| :--- | :--- |
| **Waiting** | Aguardando as verificações de CI |
| **Scheduled** | Na fila, começa em instantes |
| **Running** | O deploy está em andamento |
| **Deployed** | Concluído com sucesso |
| **Failed** | Algo deu errado — o log mostra o quê |
| **Skipped** | Não publicado, por exemplo porque o CI falhou ou o commit tem `[skip deploy]` |
| **Cancelled** | Cancelado antes de começar |

- **Log:** cada deploy tem um log ao vivo, que é atualizado enquanto o deploy roda. **Hide log** fecha o log de novo.
- **Rollback com um clique:** clique em **Deploy again** em um deploy anterior para publicar aquele estado mais uma vez.
- **Cancelar:** deploys em **Waiting** ou **Scheduled** podem ser cancelados.

Vários servidores podem fazer deploy ao mesmo tempo, mas cada servidor roda apenas um deploy por vez. Um novo gatilho substitui um deploy mais antigo que ainda está esperando.

---

## Status no seu repositório

Com **Show deploys in the repository** ativado, o seu commit mostra um status **Daki Hosting / *nome do seu servidor***: amarelo enquanto o deploy roda, depois um check verde ou um X vermelho, com um link para a aba Git Deploy.

- No GitHub, um deploy também aparece em **Deployments**, com o nome do seu servidor como ambiente.
- Com o app do GitHub, o status é escrito pelo **Daki Git Deploy** e mostra o logo dele; não há mais nada para configurar. Com um token, mostra a foto da conta do token, e o token precisa de permissões de escrita (veja [Permissões do token](#token-permissions)).
- Você pode desligar isso por servidor. Somente o status e o link são públicos — sem logs e sem detalhes de erros.

---

## Equipes e permissões de subusuários

[Subusuários](https://daki.cc/pt/wiki/guides/subusers) recebem o próprio grupo de permissões **Git Deploy**:

| Permissão | Permite |
| :--- | :--- |
| **view** (`github.read`) | Ver as configurações, o endereço do webhook e o histórico com logs |
| **deploy** (`github.deploy`) | **Deploy now**, **Deploy again** e cancelar deploys |
| **change settings** (`github.update`) | Repositório, acesso, webhook e todas as configurações |

Subusuários **não** têm acesso ao Git Deploy por padrão — você decide quem recebe qual permissão. O dono do servidor sempre pode fazer tudo.

---

## Segurança

- Tokens e segredos são armazenados **criptografados** e **nunca são enviados ao seu navegador**.
- Com o app do GitHub, não há nenhum token seu de longa duração para os deploys: cada deploy usa uma chave de curta duração (1 hora) que chega **apenas ao repositório do seu servidor**.
- O seu próprio acesso ao GitHub decide quais repositórios você pode conectar. Ninguém consegue trazer repositórios de outra pessoa para o próprio servidor.
- Os webhooks são **assinados** com um segredo próprio para cada servidor. Entregas com segredo errado ou para outro repositório são rejeitadas.
- Somente a pessoa que salvou o token pode alterar o repositório, então subusuários não conseguem usar o token do dono para carregar outros repositórios privados.
- Se você mudar o **Git service** ou a URL do servidor, o token salvo é excluído automaticamente ao salvar.
- Caminhos protegidos nunca são sobrescritos, e **Remove files that were deleted from the repository** só exclui o que o Git Deploy gravou.
- O status público no seu repositório não contém logs nem detalhes de erros.

---

## Limitações conhecidas

- Um repositório e um acesso por servidor.
- Cada servidor roda apenas um deploy por vez.
- O status no seu repositório só aparece quando o deploy de fato começa, não enquanto ele espera pelo CI.
- Arquivos de release só são extraídos se forem arquivos `.zip`; um `.tar.gz` é enviado como arquivo.
- Pastas vazias permanecem no lugar depois de **Remove files that were deleted from the repository**.
- Links simbólicos no repositório não são publicados.
- O GitLab não tem pré-releases; uma release com data futura conta como pré-release.
- GitLab: arquivos de release enviados ao projeto (`/uploads/…`) não podem ser baixados com um token de projetos privados; links para o registro de pacotes funcionam.
- **Connect with GitHub** só está disponível para o GitHub; GitLab, Gitea e Forgejo usam um token.

---

## Perguntas frequentes e solução de problemas

**Preciso renovar meu token regularmente?**

Não com o app do GitHub: o Portal busca uma chave nova para cada deploy automaticamente. Um token próprio vale pelo período que você definiu ao criá-lo no seu provedor Git; quando ele expirar, basta salvar um novo.

**Meu repositório não está na lista (app do GitHub)**

Clique em **Choose repositories on GitHub** e permita que o app acesse o repositório.

**O deploy fica em Scheduled**

Aguarde um pouco. Se continuar assim por mais de alguns minutos, por favor [entre em contato com o suporte](https://daki.cc/pt/wiki/guides/support).

**O webhook não chega, ou o GitHub mostra erro 401**

O segredo não confere. Copie o segredo no Portal e informe-o novamente no webhook. **New secret** cria um novo — nesse caso, altere-o também no seu provedor Git.

**Por que o meu deploy foi ignorado?**

Possíveis motivos: as verificações de CI falharam, a mensagem do commit contém `[skip deploy]`, ou um gatilho mais novo substituiu um deploy que ainda estava esperando. O motivo aparece na linha do deploy.

**Não vejo um status no meu commit**

**Show deploys in the repository** precisa estar ativado. Com um token, o token também precisa de permissões de escrita (veja [Permissões do token](#token-permissions)) — o log do deploy mostra o motivo.

**O deploy falha com “The node rejected the request”**

O tipo do seu servidor não permite certos arquivos, ou o disco está cheio. O log mostra os detalhes.

**A URL da minha instância própria de Gitea é rejeitada**

Instâncias próprias precisam estar acessíveis pela internet. Endereços de uma rede doméstica, como `192.168.x.x`, não funcionam.

**Como faço rollback?**

No histórico, clique em **Deploy again** no deploy anterior para o qual você quer voltar.

**O meu mundo de jogo ou o meu banco de dados será sobrescrito?**

Não, se estiverem listados em **Protected paths** (por exemplo, `world/` ou `*.db`).

**Quem na minha equipe pode fazer deploy?**

Somente pessoas com a permissão **deploy** no grupo **Git Deploy** das configurações de subusuários do servidor. O dono do servidor sempre pode fazer tudo.

---

## Próximos passos

- [Subusuários](https://daki.cc/pt/wiki/guides/subusers) — Dê acesso à sua equipe e decida quem pode fazer deploy.
- [Variáveis de ambiente](https://daki.cc/pt/wiki/guides/environment-variables) — Mantenha tokens e senhas fora do seu repositório.
- [Configurações de inicialização](https://daki.cc/pt/wiki/guides/startup-settings) — Defina o comando de inicialização com o qual o seu código publicado roda.
- [Backups](https://daki.cc/pt/wiki/guides/backups) — Salve backups automáticos do seu servidor no Google Drive.

---
Source: https://daki.cc/pt/wiki/guides/git-deploy