# Deploy pelo GitHub

URL: https://0.0.0.0:3002/docs/deploy-github

Conectar uma conta ou organização do GitHub, criar apps a partir de um repositório e usar monorepos.

Aplicações com origem **GitHub** pegam o código direto de um repositório, sem upload. O Hydro usa um GitHub App da AcquaCloud: você escolhe em quais repositórios ele entra, e ele só tem **leitura** do código e permissão para marcar o **status** dos commits.

## Conectar e criar [#conectar-e-criar]

1. **Configurações do workspace → GitHub → Conectar conta do GitHub.** No GitHub, escolha a conta ou organização e os repositórios. É preciso ser proprietário ou administrador do workspace.
2. **Aplicações → Criar aplicação → GitHub.** Escolha o repositório, a branch, a pasta (num monorepo) e se cada push faz deploy. O primeiro deploy sai na criação, com o último commit da branch.
3. **Na aplicação:** "Deploy do último commit", "Deploy de outro commit" e "Refazer deploy sem build". Cada deploy mostra o commit, com link para o GitHub. Branch, pasta e deploy automático mudam em **Configurações → Repositório**.

## Opções do repositório [#opções-do-repositório]

| Campo           | Padrão      | O que faz                                                                       |
| --------------- | ----------- | ------------------------------------------------------------------------------- |
| `branch`        | —           | Branch acompanhada. Precisa existir no repositório                              |
| `rootDir`       | `""` (raiz) | Pasta da app num **monorepo**, como `apps/loja`                                 |
| `autoDeploy`    | `true`      | Faz deploy a cada push na branch                                                |
| `watchRootOnly` | `false`     | Com `rootDir`, só faz deploy automático quando o push muda arquivos dessa pasta |

O repositório é guardado pelo **ID**: renomeá-lo no GitHub não quebra a app. Branch, pasta e as duas opções mudam com `PATCH .../apps/{appId}` em `github`.

## Deploy [#deploy]

| Gatilho    | Como                                                                                                    |
| ---------- | ------------------------------------------------------------------------------------------------------- |
| **Manual** | `POST .../apps/{appId}/deployments` com `{}` (último commit da branch) ou `{ "commitSha": "<40 hex>" }` |
| **Push**   | Automático com `autoDeploy`: cada push na branch faz deploy do commit novo                              |

Durante o deploy, o commit ganha o status **pending** no GitHub, com o contexto `Hydro / <nome da app>`, e termina como **success** ou **failure**, com o motivo.

### Pushes seguidos [#pushes-seguidos]

* Deploy ainda na fila: o push novo **substitui** o anterior, que fica cancelado.
* Deploy já em build: o push novo **espera** o build terminar e faz deploy em seguida. Só o push mais recente vale.

### Quando o push não faz deploy [#quando-o-push-não-faz-deploy]

* Push de tag, branch apagada ou outra branch.
* `autoDeploy` desligado ou app sem acesso ao repositório.
* `watchRootOnly` ligado e nenhum arquivo alterado dentro de `rootDir`.

## Acesso perdido [#acesso-perdido]

Se a instalação for suspensa ou removida no GitHub, ou o repositório sair dela, as apps ficam com `github.accessLost: true`: continuam no ar, mas pushes são ignorados e o deploy manual responde `404 github_repository_not_found`. Reconectar a conta restaura o acesso.

## Limitações [#limitações]

* Submódulos e arquivos do Git LFS não vêm no código baixado.
* Sem previews de pull request.