merge: develop → staging (0.7.8-rc.1) — Sprint 106

Sprint 106: imagem da plataforma em registry público (GHCR) — setup.sh puxa via
minikube image load com fallback de build local. Inclui docs pós-release v0.7.7 e
bump version.base → 0.7.8.

Programado em par com: Claude IA

Author: greencapk8s

.github/workflows/publish-image.yml

@@ -0,0 +1,66 @@
+name: Publish Image
+
+# Publishes the platform image to GHCR on every release tag. setup.sh pulls this
+# image by default (see ADR 0019), turning the heavy local build into a fast pull.
+#
+# NOTE: the ghcr.io/greencapk8s/platform package must be made public once, manually,
+# after the first publish — GHCR creates packages as private by default. Public
+# visibility lets setup.sh pull with no imagePullSecret.
+
+on:
+  push:
+    tags:
+      - "v*"
+  # workflow_dispatch is for re-publishing a release whose original run failed.
+  # Run it against a tag ref (not a branch) — otherwise no image tag is derived and
+  # the build fails cleanly instead of publishing a stray :latest from a branch.
+  workflow_dispatch:
+
+jobs:
+  publish:
+    # Fixed version, not ubuntu-latest — that tag moves to a newer image over time
+    # without notice, risking non-reproducible CI runs
+    runs-on: ubuntu-24.04
+    timeout-minutes: 30
+    permissions:
+      contents: read
+      packages: write
+    steps:
+      - uses: actions/checkout@v6
+
+      - name: Set up Docker Buildx
+        uses: docker/setup-buildx-action@v3
+
+      - name: Log in to GHCR
+        uses: docker/login-action@v3
+        with:
+          registry: ghcr.io
+          username: ${{ github.actor }}
+          password: ${{ secrets.GITHUB_TOKEN }}
+
+      - name: Derive image tags
+        id: meta
+        uses: docker/metadata-action@v5
+        with:
+          images: ghcr.io/greencapk8s/platform
+          # latest is added explicitly below; disable metadata-action's auto-latest
+          flavor: latest=false
+          # {{version}} strips the leading v (v0.7.8 -> 0.7.8). latest is applied
+          # only to stable release tags — never a pre-release (v0.7.8-rc.1 contains
+          # a '-'), so an RC never hijacks the latest that end users pull.
+          tags: |
+            type=semver,pattern={{version}}
+            type=raw,value=latest,enable=${{ startsWith(github.ref, 'refs/tags/') && !contains(github.ref_name, '-') }}
+
+      - name: Build and push (linux/amd64)
+        uses: docker/build-push-action@v6
+        with:
+          context: .
+          file: docker/Dockerfile
+          # amd64 only — arm64 would need QEMU emulation on the runner, slowing every
+          # release to serve the macOS/Apple Silicon minority (setup.sh builds arm64
+          # locally instead — see ADR 0019)
+          platforms: linux/amd64
+          push: true
+          tags: ${{ steps.meta.outputs.tags }}
+          labels: ${{ steps.meta.outputs.labels }}

.github/workflows/setup-script-validate.yml

@@ -48,6 +48,10 @@ jobs:
       AUTO_INSTALL: "y"
       PROFILE_CHOICE: "1"
       INSTALL_ONLY: ${{ matrix.install_only }}
+      # Force the local build path: setup.sh now defaults to pulling the published
+      # image, but this workflow exists to validate that docker/Dockerfile and the
+      # source still build. On PRs (pre-release) no image is published yet anyway.
+      BUILD_LOCAL: "true"
     steps:
       - uses: actions/checkout@v6
 

…/sprint-96/issues/01-criar-asynctasks.md …/sprint-96/issues/01-criar-asynctasks.md.scratch/sprint-96/issues/01-criar-asynctasks.md renamed to .scratch/archive/sprint-96/issues/01-criar-asynctasks.md .scratch/sprint-96/issues/01-criar-asynctasks.md renamed to .scratch/archive/sprint-96/issues/01-criar-asynctasks.md

@@ -0,0 +1,17 @@
+# 01 — Workflow de publicação da imagem da plataforma no GHCR
+
+Status: done
+
+Hoje nenhum pipeline publica a imagem da plataforma — ela só existe quando alguém roda `docker build` localmente (no `setup.sh` ou no `docker compose`). Esta entrega cria o lado **produtor**: um workflow do GitHub Actions que constrói a imagem da plataforma e a publica em `ghcr.io/greencapk8s/platform` a cada release, deixando-a pronta para o `setup.sh` puxar (issue 02).
+
+Gatilho do workflow: push de git tag `v*` — a mesma tag que já é a fonte de verdade da versão em `main` (ver `build.gradle.kts` → `lastGitTag`), garantindo uma imagem por release e o versionamento da imagem 1:1 com o do binário. Além disso, `workflow_dispatch` para permitir republicar manualmente uma tag caso a release falhe no meio, sem custo e como rede de segurança.
+
+A imagem é construída a partir de `docker/Dockerfile` para a plataforma **`linux/amd64`** apenas — publicar arm64 exigiria emulação QEMU no runner, encarecendo cada release para beneficiar a minoria macOS/Apple Silicon (decisão registrada na ADR 0019; o `setup.sh` cobre arm64 com build local). O login no GHCR usa o `GITHUB_TOKEN` do próprio Actions com permissão `packages: write` — sem cadastrar secret externo.
+
+Tags aplicadas à imagem publicada, derivadas do nome da git tag (`v0.7.8` → `0.7.8`): a versão exata `X.Y.Z` sempre, e `latest` **apenas** quando a tag é um release estável (`vX.Y.Z`), nunca um pré-release (`vX.Y.Z-rc.N`) — assim um RC tagueado não sequestra o `latest` que os usuários finais puxam. A tag `X.Y.Z` é o ponto imutável e reproduzível; `latest` é o ponteiro móvel que o `setup.sh` consome por padrão.
+
+O pacote no GHCR precisa ficar com **visibilidade pública** (sem `imagePullSecret` no consumo) e vinculado ao repositório. A primeira publicação cria o pacote como privado por padrão — ajustar a visibilidade para público (via configuração do pacote no GitHub ou `gh`) faz parte desta entrega; documentar no corpo da issue/PR que esse passo é manual e único, caso o Actions não consiga defini-lo por si.
+
+Cobertura de teste: não há código Java envolvido — a validação é a própria execução do workflow. Como a publicação só dispara em tag `v*`, o caminho pode ser exercitado antes do primeiro release real via `workflow_dispatch`, confirmando que a imagem aparece pública em `ghcr.io/greencapk8s/platform` com as tags esperadas. O gate de testes Karibu/integração do fluxo de sprint não se aplica a esta entrega.
+
+Fora de escopo: multi-arch (só amd64 nesta sprint) e a troca do `docker-compose.yml` para a imagem publicada (registrada no backlog como follow-up).

…int-96/issues/02-migrar-execute-unico.md …int-96/issues/02-migrar-execute-unico.md.scratch/sprint-96/issues/02-migrar-execute-unico.md renamed to .scratch/archive/sprint-96/issues/02-migrar-execute-unico.md .scratch/sprint-96/issues/02-migrar-execute-unico.md renamed to .scratch/archive/sprint-96/issues/02-migrar-execute-unico.md

@@ -0,0 +1,19 @@
+# 02 — Step 5 do setup.sh puxa a imagem publicada e carrega via `minikube image load`
+
+Status: done
+
+Esta é a entrega central da sprint: o lado **consumidor** da imagem publicada (issue 01). Hoje o Step 5 do `setup.sh` sempre roda um `docker build` completo (resolução de dependências Gradle + `bootJar` com frontend Vaadin de produção) e faz `docker push` para o registry interno do minikube via port-forward — o passo mais pesado da instalação, mesmo quando o código não mudou. Esta entrega reescreve o Step 5 para, por padrão, **puxar** a imagem já publicada e carregá-la no cluster, mantendo o build local como caminho alternativo.
+
+Decisão de puxar vs buildar, com esta precedência: (1) se `BUILD_LOCAL=true`, builda — via deliberada para o desenvolvedor testar o próprio código-fonte não-lançado; (2) senão, se a arquitetura (`uname -m`) **não** for `amd64` (arm64 em Apple Silicon ou Linux ARM), builda com aviso — não há imagem publicada para essa arquitetura; (3) senão (amd64, sem override), puxa a imagem publicada. Se o pull falhar (rede fora, GHCR indisponível), o script **cai automaticamente no build local com um aviso visível** — nunca trava a instalação, coerente com o posicionamento plug-and-play para iniciantes (ADR 0019).
+
+Tag puxada: `latest` por padrão, sobrescrevível por `PLATFORM_IMAGE_TAG` (ex. `PLATFORM_IMAGE_TAG=0.7.7`). O `latest` mantém o script sem manutenção acoplada ao release; o override preserva reprodutibilidade quando alguém precisa de uma versão exata.
+
+Ambos os caminhos convergem para o mesmo nome de imagem local `ghcr.io/greencapk8s/platform:latest`: o pull já traz esse nome (normalizado para a tag local `:latest` quando `PLATFORM_IMAGE_TAG` aponta para outra versão, via `docker tag`); o build local produz a imagem com esse mesmo nome. Daí em diante, um único mecanismo: `minikube image load ghcr.io/greencapk8s/platform:latest -p $PROFILE`, que injeta a imagem direto no runtime dos nós — eliminando o port-forward e o `docker push` para o registry interno que o Step 5 fazia. O registry interno **permanece** no cluster, usado só pelo Kaniko dos Templates e pela view de Registry; o que sai é apenas a imagem da plataforma passar por ele.
+
+O manifest `setup/manifests/05-greencap-deployment.yaml` passa a referenciar `ghcr.io/greencapk8s/platform:latest` com `imagePullPolicy: IfNotPresent` (hoje é `localhost:5000/greencap-platform/platform:latest` com `Always`). O `IfNotPresent` é essencial: usa a imagem carregada pelo `image load` sem tentar sair para a internet — necessário no caminho build-local, onde essa tag nem existe na GHCR. Como a tag `:latest` não muda entre releases, um `kubectl apply` de rerun não detectaria imagem nova sozinho; por isso, após o `image load`, o Step 5 executa `kubectl rollout restart deployment/greencap` para o rerun pegar a imagem recarregada. (O deployment só é criado no Step 7 — o rollout restart deve ser tolerante à primeira execução, quando o deployment ainda não existe.)
+
+Ajuste de CI incluído nesta mesma entrega, para não deixar a validação quebrada: o workflow `setup-script-validate.yml` passa a rodar o `setup.sh` com `BUILD_LOCAL=true`, mantendo a validação do caminho de build do Dockerfile/código-fonte (o propósito do workflow) mesmo depois de o padrão do script virar pull. Sem isso, o CI passaria a exercitar o pull de uma imagem que, em PRs pré-release, ainda não existe.
+
+Cobertura de teste: não há código Java — a validação é o CI (`setup-script-validate` continua verde com `BUILD_LOCAL=true`) mais o aceite manual no browser (`http://greencap.local`, login admin/admin, plataforma sobe). O caminho de pull só é plenamente exercitável depois que a issue 01 publicar uma imagem; até lá o `setup.sh` exercita o fallback de build, e o pull pode ser fumaça-testado publicando uma imagem via `workflow_dispatch` (issue 01) e rodando `setup.sh` em amd64. O gate Karibu/integração do fluxo de sprint não se aplica.
+
+Fora de escopo: garbage collection do registry interno (item vizinho no backlog) e a troca do `docker-compose.yml` (follow-up no backlog).

…6/issues/03-migrar-polling-recorrente.md …6/issues/03-migrar-polling-recorrente.md.scratch/sprint-96/issues/03-migrar-polling-recorrente.md renamed to .scratch/archive/sprint-96/issues/03-migrar-polling-recorrente.md .scratch/sprint-96/issues/03-migrar-polling-recorrente.md renamed to .scratch/archive/sprint-96/issues/03-migrar-polling-recorrente.md

@@ -0,0 +1,13 @@
+# 03 — README: documentar a imagem publicada e os overrides do setup
+
+Status: done
+
+Com o `setup.sh` passando a puxar uma imagem publicada por padrão (issue 02), o README precisa refletir o novo comportamento — hoje ele descreve (ou pressupõe) que a instalação constrói a imagem localmente. Esta entrega atualiza a documentação para explicar que a instalação agora baixa uma imagem pronta de `ghcr.io/greencapk8s/platform`, tornando o setup mais rápido, e expõe as chaves de override para quem precisa de outro comportamento.
+
+O que documentar, de forma enxuta e sem prometer detalhes de implementação: que o `setup.sh` puxa a imagem publicada em `amd64` e constrói localmente em arm64 ou quando `BUILD_LOCAL=true`; que `PLATFORM_IMAGE_TAG` fixa uma versão específica (ex. `PLATFORM_IMAGE_TAG=0.7.7`) em vez do `latest` padrão; e que, se o pull falhar, a instalação constrói localmente de forma automática — não trava. Mencionar que a imagem é pública (nenhuma autenticação é necessária para puxá-la).
+
+Manter o tom e o posicionamento já estabelecidos no README (setup-first, plug-and-play): a mensagem principal é "a instalação agora é mais rápida porque baixa uma imagem pronta", com os overrides como nota para desenvolvedores, não como fluxo principal.
+
+Cobertura de teste: entrega puramente documental — sem código, sem CI novo. Validação por revisão do texto no aceite manual.
+
+Fora de escopo: documentar a troca do `docker-compose.yml` para a imagem publicada (essa mudança está no backlog; o README só será ajustado nesse ponto quando o follow-up for implementado).

.scratch/sprint-106/issues/01-workflow-publicacao-imagem-ghcr.md

@@ -2,7 +2,7 @@
   <img src="docs/assets/greencap.png" alt="GreenCap K8s" width="170" />
   <h1>GreenCap K8s</h1>
   <p><strong>Simple Kubernetes cluster management.</strong></p>
-  <p>A lightweight web platform to monitor and operate the Kubernetes clusters you already run — a friendlier alternative to OpenShift or Rancher for individuals and small teams who study, build, and test on Kubernetes.</p>
+  <p>A lightweight web platform to run and operate Kubernetes. One command brings up a local cluster with GreenCap on it — ready to study, build, and test — and you can connect clusters you already run.</p>
 
   <p>
     <a href="LICENSE"><img src="https://img.shields.io/badge/License-Apache_2.0-blue.svg" alt="License: Apache 2.0" /></a>
@@ -24,11 +24,11 @@
 
 ## What is GreenCap?
 
-GreenCap is a web platform for **monitoring and managing external Kubernetes clusters**. You register access to clusters you already run — minikube, kind, managed, or on-prem — and GreenCap gives you a clean UI to see and operate what lives inside them.
+GreenCap is a web platform for **operating Kubernetes through a UI instead of a terminal**. One command (`./setup/setup.sh`) brings up a local cluster with GreenCap running on it — the fastest way to start. You can also connect clusters you already run: minikube, kind, managed, or on-prem.
 
 It's built for a specific audience: **individuals and small/medium teams who study, develop, and test against Kubernetes**, and want the day-to-day operations without the operational weight of an enterprise platform.
 
-- **It does not provision clusters.** GreenCap is a management layer over clusters that exist outside it — not a cluster lifecycle tool.
+- **Two layers, one install.** `setup.sh` provisions a local cluster to get you started; the app itself is a management layer over clusters — it operates what lives inside them, it is not a cluster lifecycle tool.
 - **It's not read-only.** GreenCap actively creates, deletes, scales, restarts, and deploys — every action governed by the acting user's Kubernetes RBAC.
 - **It's multi-user and RBAC-native.** Each non-admin user is backed by a Kubernetes ServiceAccount; their access is exactly what Kubernetes RBAC grants — nothing more.
 
@@ -97,11 +97,13 @@ cd greencap-k8s
 ./setup/setup.sh
 ```
 
-The wizard provisions a real Kubernetes cluster (minikube), builds and deploys GreenCap into it, and wires up local access. When it finishes:
+The wizard provisions a real Kubernetes cluster (minikube), pulls the published GreenCap image and deploys it, and wires up local access. When it finishes:
 
 - **URL:** http://greencap.local
 - **Login:** `admin` / `admin` &nbsp;(change it after your first login)
 
+> **How the image is provided.** On `amd64` the wizard pulls the prebuilt public image from `ghcr.io/greencapk8s/platform` — no build, no authentication. On `arm64` (Apple Silicon), or when you set `BUILD_LOCAL=true`, it builds from source locally instead; if a pull ever fails, it falls back to a local build automatically, so setup never stalls. Pin a specific release with `PLATFORM_IMAGE_TAG=X.Y.Z ./setup/setup.sh` (defaults to `latest`).
+
 To tear everything down:
 
 ```bash
@@ -129,9 +131,17 @@ Go deeper:
 - [`docs/adr/`](docs/adr/) — architectural decision records
 - [`.dev/README.md`](.dev/README.md) — developer guide
 
+## Security
+
+- **Encrypted kubeconfig** — cluster credentials are always encrypted before they are persisted.
+- **Native Kubernetes RBAC** — each non-admin user acts through their own ServiceAccount, so every action is authorized by the cluster itself.
+- **One source of truth** — GreenCap does not maintain a parallel permission system. What Kubernetes RBAC grants is exactly what the user can do.
+
+Found a vulnerability? See [SECURITY.md](SECURITY.md).
+
 ## Contributing
 
-Contributions are welcome — bug reports, feature ideas, docs, and code. Start with the [contributing guide](CONTRIBUTING.md), and please review our [Code of Conduct](CODE_OF_CONDUCT.md). Found a security issue? See [SECURITY.md](SECURITY.md).
+Contributions are welcome — bug reports, feature ideas, docs, and code. Start with the [contributing guide](CONTRIBUTING.md), and please review our [Code of Conduct](CODE_OF_CONDUCT.md).
 
 ## License