# Plan: CI dla repozytoriów Logintegry

\[PLAN\] Stan na 2026-09-30. Dotyczy repozytoriów aplikacji, `teamcity-configuration-as-a-code`, `apollo-docker` i `logintegra-ansible`. Strona jest dla zespołu, który utrzymuje TeamCity i procesy wdrożeń.

## Problem

TeamCity wdraża, odtwarza bazy i uruchamia serwery, ale prawie nie sprawdza zmian przed scaleniem.

| Obszar | Stan na 2026-09-30 |
| --- | --- |
| Pull requesty | Żadna konfiguracja nie używa `pullRequests` ani `commitStatusPublisher`, więc PR nie dostaje wyniku builda. |
| Testy backendu | `ApolloRunGradleCheck` nie ma wyzwalacza i powiadamia Slacka tylko o zawieszonym buildzie. |
| Lint frontendu | Skrypt `lint:teamcity` kończy się `return 0`, więc błędy lintu nie zatrzymują builda. |
| Testy w repozytoriach | `apollo/backend` ma 36 specyfikacji, `mikroserwis-sms` nie ma testów. |
| Artefakty | Środowiska testowe dostają obraz z `bootJar`, a produkcja plik `war` zbudowany osobno. |
| Buildy na hostach | `apollo-docker.sh` klonuje 10 repozytoriów na hosta testowego i buduje tam obrazy. |
| Sekrety | Token Bitbucketa leży w `ToolboxConstants.kt`, a hasła w śledzonym `.env` repozytorium `apollo-docker`. |
| Zmiany przez commit | Od czerwca 2026 powstało 21 commitów ze zmianą gałęzi testów i 8 z nowym tokenem. |
| Logika w DSL | Konfiguracja ma 13 tys. linii Kotlina i 57 bloków `scriptContent`, których nie da się uruchomić lokalnie. |

## Zasady

1. Każda zmiana trafia do gałęzi głównej przez PR z zielonym buildem.
2. Build aplikacji jest opisany w jej repozytorium i działa tak samo lokalnie i w CI.
3. Aplikację budujemy raz, a na kolejne środowiska promujemy ten sam artefakt.
4. Sekrety są tylko w bezpiecznych parametrach TeamCity albo w Vault.
5. TeamCity wiąże kroki ze sobą, a nie zawiera logiki.
6. Serwery tworzy Terraform, a konfiguruje Ansible, więc TeamCity nie zarządza maszynami.

## Docelowy przepływ

```
flowchart LR
    pr[PR w Bitbucket] --> check[PR check<br/>lint, testy, build]
    check -->|status| pr
    pr -->|merge| main[develop / release-*]
    main --> build[Build artefaktu<br/>war + obraz, wersja]
    build --> reg[(Registry<br/>obrazy i war)]
    reg --> test[Środowiska testowe<br/>apollo-docker]
    reg --> qa[QA<br/>tomcat-node]
    qa -->|ręczne zatwierdzenie| prod[Produkcja<br/>Tomcat]

    classDef ci stroke:#1e88e5,stroke-width:2px
    classDef env stroke:#43a047,stroke-width:2px
    class check,build ci
    class test,qa,prod env
```

Niebieskie obramowanie oznacza build w CI, zielone oznacza środowisko.

## Konwencje

| Element | Konwencja |
| --- | --- |
| Gałęzie | `develop`, `master`, `A-12345`, `DEV-123`, `release-4.172.0`, `hotfix-4.172.1` |
| Wersja artefaktu | `4.172.0` z gałęzi release, `4.172.0-dev.<liczba commitów>+<sha>` z `develop` |
| Tag obrazu | wersja artefaktu oraz `develop` jako tag przesuwany |
| Skrypty CI w repozytorium | `ci/check.sh`, `ci/build.sh`, `ci/publish.sh` |
| Wynik testów | JUnit XML w `build/test-results/` albo `test-results/` |

Nazwy hotfixów w `apollo/backend` mają trzy formy: `hotfix-N.N.N`, `hotfix-N_N_N` i `hotfix_N_N_N`. Obowiązuje tylko pierwsza.

## Plan wdrożenia

### Etap 0: sekrety

Unieważniamy token Bitbucketa z `ToolboxConstants.kt` i tworzymy nowy. Nowy token trafia do parametru `credentialsJSON:` w TeamCity. W `apollo-docker` zostaje `.env.example` z wartościami `<VAULT>`, a `.env.local` na hoście tworzy rola Ansible `apollo_docker`. Klucz `google-storage-test-key.p12` znika z repozytorium i trafia do Vault. Oba repozytoria dostają skan `gitleaks` w PR check.

Gotowe, gdy `gitleaks detect` nie znajduje sekretów w bieżącej wersji obu repozytoriów.

### Etap 1: PR check dla Apollo

Pierwsze są `apollo/backend` i `apollo/frontend`, bo tam powstaje najwięcej zmian. Każde repozytorium dostaje build „PR check” z funkcjami `pullRequests` dla Bitbucket Cloud i `commitStatusPublisher`.

| Repozytorium | PR check |
| --- | --- |
| `apollo/backend` | `./gradlew check` oraz generowanie OpenAPI |
| `apollo/frontend` | `npm ci`, `npm run lint`, `ember test` w Chrome headless |

Lint frontendu przestaje kończyć się `return 0`. Istniejące błędy lintu trafiają do pliku wyjątków, żeby nowe błędy zatrzymywały build. W Bitbucket włączamy regułę scalania „co najmniej jeden udany build”.

Gotowe, gdy PR z nieprzechodzącym testem nie da się scalić w obu repozytoriach.

### Etap 2: build w repozytorium

Każde repozytorium dostaje katalog `ci/` ze skryptami z tabeli konwencji. Build w TeamCity wywołuje jeden skrypt. Bloki `scriptContent` z logiką przenosimy do skryptów w repozytorium aplikacji. Do `teamcity-configuration-as-a-code/.teamcity/scripts/` trafia tylko logika, która nie należy do żadnej aplikacji. PR check dostają też `apollo-admin`, mikroserwisy i `infokiosk`.

Gotowe, gdy każdy build aplikacji w TeamCity ma jeden krok, który da się uruchomić lokalnie.

### Etap 3: jeden artefakt

Backend buduje raz `bootWar` z numerem wersji. Ten sam plik `war` trafia na Tomcat i do obrazu Dockera, który uruchamia go przez `java -jar`. Obrazy i pliki `war` trafiają do jednego registry z wersją w nazwie. `apollo-docker` pobiera obrazy według tagów z `.docker-tags` i niczego nie buduje. Z `apollo-docker.sh` znikają `get_repos`, `pull` i `build_and_push` oraz plik `docker-compose.build.yaml`.

Gotowe, gdy QA i produkcja uruchamiają plik `war` o tej samej sumie SHA-256 co obraz na środowisku testowym.

### Etap 4: wdrożenia jako promocja

Wdrożenie przyjmuje wersję artefaktu, a nie gałąź. Środowisko testowe zespołu dostaje najnowszą wersję ze swojej gałęzi release, ustalaną w czasie builda. To usuwa commity ze zmianą gałęzi testów w konfiguracji. Wdrożenie na produkcję wymaga ręcznego zatwierdzenia w TeamCity i wersji, która przeszła QA. Hosty pochodzą z dynamicznego inventory, zgodnie z planem `teamcity-dynamic-targets.md` w `logintegra-ansible`.

Gotowe, gdy nowa gałąź release albo nowy host nie wymaga commitu w `teamcity-configuration-as-a-code`.

### Etap 5: TeamCity bez operacji na serwerach

Budowy takie jak `HandleScalewayServerTemplate` i `ExecuteAnsibleCommand` zastępujemy playbookami Ansible i Terraformem, uruchamianymi z `logintegra-dev`. Odtwarzanie baz przechodzi do narzędzia w repozytorium, np. `logintegra-toolbox-cli`. TeamCity może takie narzędzie wywołać, ale nie zawiera jego logiki.

Gotowe, gdy konfiguracja TeamCity nie zawiera poleceń `scw`, `ansible-playbook` ani `pg_restore`.

### Etap 6: widoczność

TeamCity zbiera wyniki testów z JUnit XML i oznacza niestabilne testy. Slack dostaje powiadomienia tylko o błędach na `develop`, `release-*` i `master`. Każdy PR check trwa krócej niż 15 minut dzięki cache Gradle i npm na agentach.

Gotowe, gdy zespół przez dwa tygodnie nie wyłącza powiadomień z CI.

## Ryzyka

| Ryzyko | Co robimy |
| --- | --- |
| Obowiązkowy zielony build blokuje pilne poprawki | Administrator repozytorium może scalić PR z pominięciem reguły, a każdy taki przypadek trafia do YouTrack. |
| Testy backendu wymagają bazy PostgreSQL | PR check uruchamia bazę w kontenerze obok builda. |
| Testy Ember w Chrome headless są niestabilne | Niestabilne testy trafiają na listę w TeamCity, a nie są wyłączane po cichu. |
| Obraz uruchamiający `war` zachowuje się inaczej niż Tomcat | QA działa na `tomcat-node`, więc różnice wyjdą przed produkcją. |
| Agenci TeamCity są za słabi na równoległe PR checki | Mierzymy kolejkę przez pierwsze dwa tygodnie i dopiero wtedy decydujemy o nowych agentach. |

## Otwarte pytania

1. Które registry przechowuje obrazy i pliki `war`, skoro `REGISTRY_URL` w `.env` jest puste?
2. Czy Bitbucket Pipelines ma przejąć PR checki, jeśli TeamCity po etapie 2 nadal będzie trudny?
3. Kto zatwierdza wdrożenie na produkcję i czy wystarczy do tego rola w TeamCity?
4. Czy `mikroserwis-sms` na Grails 4 i Javie 8 dostaje testy, czy czeka na migrację?
