# GitLab CI/CD for `pcp-ballistics-service`

This document describes the pilot GitLab CI/CD setup for `pcp-ballistics-service`.
It is intentionally scoped to one service so the same structure can be reused later for other services in this monorepo.

## Pipeline behavior

The root pipeline is defined in [.gitlab-ci.yml](/home/emelianovan/WORK/Kotlin/pcp/.gitlab-ci.yml) and includes the service-specific jobs from [.gitlab/ci/pcp-ballistics-service.yml](/home/emelianovan/WORK/Kotlin/pcp/.gitlab/ci/pcp-ballistics-service.yml).

Pipeline creation is limited by `workflow: rules`:

- merge request: create a pipeline only when `pcp-ballistics-service` or its dependencies changed
- push to `dev`: create a pipeline only when `pcp-ballistics-service` or its dependencies changed
- push to `master`: create a pipeline only when `pcp-ballistics-service` or its dependencies changed

No deploy jobs are created for merge requests.

## Jobs

The pilot flow has four stages:

1. `ballistics:test`
   Runs `:services:pcp-ballistics-service:test` outside Docker.
   Publishes JUnit and HTML/JaCoCo reports.

2. `ballistics:build`
   Runs `:services:pcp-ballistics-service:bootJar` outside Docker.
   Publishes `build/libs/*.jar` as an artifact.

3. `ballistics:image`
   Builds and pushes the Docker image with Kaniko using the jar artifact from the previous stage.
   Tags:
   - `${CI_COMMIT_SHORT_SHA}`
   - `${CI_COMMIT_REF_SLUG}-${CI_COMMIT_SHORT_SHA}`

4. deploy jobs
   - `ballistics:deploy:dev`
   - `ballistics:deploy:master`

   Both are manual and use Helm:
   `helm upgrade --install --wait --atomic --timeout`.

## Branch behavior

### `dev`

Push to `dev`:

- runs test, build and image jobs
- exposes a manual deploy button to the `dev` environment

### `master`

Push to `master`:

- runs test, build and image jobs
- exposes a manual deploy button to the `master` environment

### merge request

Merge request pipeline:

- runs test and build only
- does not create deploy jobs

## `rules:changes` scope

The pilot dependency map for `pcp-ballistics-service` includes:

- `services/pcp-ballistics-service/**/*`
- `libs/pcp-types-lib/**/*`
- `libs/ballistics-lib/**/*`
- `config-repo/pcp-ballistics-service.yaml`
- `config-repo/application*.yaml`
- Gradle root files and wrapper
- CI files
- `charts/pcp-ballistics-service/**/*`

This is the pattern to reuse later for other services: service directory + direct shared libraries + service config + CI/Helm files.

## Helm deploy model

The chart lives in [charts/pcp-ballistics-service](/home/emelianovan/WORK/Kotlin/pcp/charts/pcp-ballistics-service).

The deployment model is kubeconfig-based, not GitLab Agent-based.
This keeps the pilot setup simple and practical. A later migration to GitLab Agent is still possible because deploy logic is already isolated in dedicated jobs.

## Required GitLab CI/CD variables

Registry auth uses standard GitLab registry variables:

- `CI_REGISTRY`
- `CI_REGISTRY_USER`
- `CI_REGISTRY_PASSWORD`

Deploy jobs require:

- `BALLISTICS_KUBE_CONFIG_DEV`
- `BALLISTICS_KUBE_NAMESPACE_DEV`
- `BALLISTICS_CONFIG_SERVER_URI_DEV`
- `BALLISTICS_KUBE_CONTEXT_DEV` optional
- `BALLISTICS_CONFIG_LABEL_DEV` optional, defaults to `master`
- `BALLISTICS_SPRING_PROFILE_DEV` optional, defaults to `dev`

- `BALLISTICS_KUBE_CONFIG_MASTER`
- `BALLISTICS_KUBE_NAMESPACE_MASTER`
- `BALLISTICS_CONFIG_SERVER_URI_MASTER`
- `BALLISTICS_KUBE_CONTEXT_MASTER` optional
- `BALLISTICS_CONFIG_LABEL_MASTER` optional, defaults to `master`
- `BALLISTICS_SPRING_PROFILE_MASTER` optional, defaults to `dev`

`BALLISTICS_KUBE_CONFIG_*` must contain base64-encoded kubeconfig content.

## Config server and Vault

Runtime secrets are not duplicated in GitLab CI.

The Helm chart only passes bootstrap parameters needed by Spring Cloud Config:

- `CONFIG_SERVER_URI`
- `SPRING_PROFILES_ACTIVE`
- `SPRING_CLOUD_CONFIG_LABEL`
- `CONFIG_SERVER_FAIL_FAST`

`pcp-ballistics-service` continues to obtain runtime configuration and secrets through `spring-cloud-config-server` and Vault at runtime.

## How to scale this to other services

To onboard another service later:

1. create a dedicated `.gitlab/ci/<service>.yml`
2. define that service's `rules:changes`
3. add a dedicated Helm chart
4. keep the same stage structure:
   `test -> build -> image -> manual deploy`
5. keep config-service/Vault integration at runtime, without copying secrets into GitLab