CI/CD and Git Implementation Roadmap¶

Implementation Status — Not Yet Active

CI/CD and Git version control are planned but not yet implemented for NeoCore. This document is the team's roadmap for setting it up. No GitHub repository has been created yet. No pipeline is running. All workflow steps below are the intended target state.

Current State

Version control: All services are developed locally without Git. Files are shared between team members manually.
Deployment: Docker Compose is used locally and on the server. Images are built locally and deployed manually via SSH.
Planned tooling: GitHub + GitHub Actions + GitHub Container Registry (GHCR).

What This Document Covers¶

This document gives the team a step-by-step plan to set up Git version control and a CI/CD (Continuous Integration / Continuous Deployment) pipeline using AI assistance. No prior DevOps experience is required. Each phase includes the exact AI prompts the team can use to implement it.

Plain English — What These Terms Mean¶

Term	What It Means in CBMS Context
Git	A system that saves every version of every file. If something breaks, you go back. Every team member's work is collected in one place.
Repository (Repo)	The single folder in Git that holds the entire CBMS project
Branch	A separate copy of the project where you work without affecting others. Like a workspace.
Commit	Saving your current work with a message describing what you did
Push	Uploading your saved work to the shared repository
Pull	Downloading the latest work from the shared repository
CI — Continuous Integration	Every time someone pushes code, the system automatically builds and checks it
CD — Continuous Deployment	Every time the build passes, the system automatically deploys to the server
Pipeline	The automated sequence: Push → Build → Test → Deploy
Docker Compose	Already in use — the pipeline will use this to deploy

Tool Selection¶

Purpose	Tool	Why
Git hosting	GitHub	Most AI-friendly platform, large documentation base, free for private repositories
CI/CD engine	GitHub Actions	Built into GitHub, no separate server needed, easiest for AI-assisted setup
Container registry	GitHub Container Registry (GHCR)	Free, integrated with GitHub Actions
Deployment target	Docker Compose on server	Already in use — no change to existing setup
Notification	Email / Teams webhook	Build success/failure alerts

Environment Strategy¶

Three environments — each has its own server and its own database.

Developer Machine          Development Server         Production Server
(local work)                  (team shared)              (live system)
      │                             │                          │
   feature                       develop                     main
   branch                        branch                     branch
      │                             │                          │
   Docker                      Docker                      Docker
   local                       Compose                     Compose
      │                             │                          │
  alappaddemo               alappaddemo                  alappad
  (local DB)                (dev DB)                    (prod DB)

Environment	Branch	Purpose	Who Deploys
Local	`feature/*`	Individual developer work	Each developer
Development	`develop`	Team integration, testing	Automatic via CI/CD
Production	`main`	Live system	Manual approval + automatic

Git Branch Strategy¶

Simple three-level structure. No complex branching.

main  ──────────────────────────────────────────── (production-ready only)
  │
develop  ──────────────────────────────────────── (team integration)
  │          │              │              │
feature/    feature/      feature/      feature/
deposit-   customer-      gl-screen     product-
screen     kyc-fix        dropdown      config

Rules¶

Rule	Detail
`main` branch	Only Team Lead merges here. Always deployable to production.
`develop` branch	Java Developer merges completed features here. Triggers automatic dev deployment.
`feature/*` branches	Each domain expert or developer works here. Named clearly.
Never work directly on `main`	No exceptions
Never work directly on `develop`	Only Java Developer merges into develop

Daily Git Workflow — Per Role¶

Domain Expert (working with AI on a screen)¶

Morning — Get latest work
─────────────────────────────
git pull origin develop

Work during the day
─────────────────────────────
(Work with AI, save files normally)

End of day — Save and share with Java Developer
─────────────────────────────
Share files via folder / message to Java Developer

Domain experts do not need to use Git commands directly. They share completed files with the Java Developer who handles the Git operations.

Java Developer (integrator and Git manager)¶

Start new feature
─────────────────────────────
git checkout develop
git pull origin develop
git checkout -b feature/deposit-transaction-fix

Work and integrate
─────────────────────────────
(Integrate received files, fix conflicts, test locally with Docker)

Save progress
─────────────────────────────
git add .
git commit -m "feat: integrate deposit transaction screen with service API"
git push origin feature/deposit-transaction-fix

When feature is complete — merge to develop
─────────────────────────────
git checkout develop
git merge feature/deposit-transaction-fix
git push origin develop
(This triggers CI/CD automatically)

Team Lead (production releases)¶

When develop is stable and verified
─────────────────────────────
git checkout main
git merge develop
git push origin main
(This triggers production deployment)

CI/CD Pipeline Design¶

┌─────────────────────────────────────────────────────────────────┐
│                     GitHub Actions Pipeline                      │
│                                                                   │
│  Push to develop                    Push to main                 │
│       │                                   │                       │
│       ▼                                   ▼                       │
│  ┌─────────┐                       ┌─────────┐                   │
│  │  Build  │                       │  Build  │                   │
│  │ All     │                       │ All     │                   │
│  │Services │                       │Services │                   │
│  └────┬────┘                       └────┬────┘                   │
│       │                                 │                         │
│       ▼                                 ▼                         │
│  ┌─────────┐                       ┌─────────┐                   │
│  │  Push   │                       │  Push   │                   │
│  │ Images  │                       │ Images  │                   │
│  │to GHCR  │                       │to GHCR  │                   │
│  └────┬────┘                       └────┬────┘                   │
│       │                                 │                         │
│       ▼                                 ▼                         │
│  ┌─────────┐                       ┌──────────────┐              │
│  │ Deploy  │                       │Manual Approve│              │
│  │  to     │                       │  (Team Lead) │              │
│  │  Dev    │                       └──────┬───────┘              │
│  │ Server  │                              │                       │
│  └─────────┘                             ▼                       │
│                                    ┌─────────┐                   │
│                                    │ Deploy  │                   │
│                                    │  to     │                   │
│                                    │ Prod    │                   │
│                                    │ Server  │                   │
│                                    └─────────┘                   │
└─────────────────────────────────────────────────────────────────┘

Implementation Roadmap¶

Phase 1 — Git Setup¶

Target: Day 1–2 Owner: Java Developer + Team Lead

Steps¶

Step 1.1 — Create GitHub Repository - Go to github.com → New Repository - Name: cbms-microservices - Private repository - Add all team members as collaborators

Step 1.2 — Push Existing Project to GitHub

cd <project-folder>
git init
git add .
git commit -m "initial: CBMS microservices base project"
git branch -M main
git remote add origin https://github.com/<org>/cbms-microservices.git
git push -u origin main

Step 1.3 — Create develop branch

git checkout -b develop
git push origin develop

Step 1.4 — Set branch protection rules - On GitHub → Settings → Branches - Protect main: require Team Lead approval before merge - Protect develop: require Java Developer review before merge

Step 1.5 — Share repository access - Each team member clones the repository once - Domain experts only need to clone — they don't push directly

AI Prompt for This Phase¶

I have an existing Spring Boot microservices project with Docker Compose.
Help me:
1. Initialize a Git repository
2. Create a .gitignore file suitable for Spring Boot + React.js + Docker
3. Push it to GitHub
4. Create a develop branch
5. Set up branch protection rules for main and develop

Project structure:
- Multiple Spring Boot services (Java 17, Maven)
- React.js frontend (arcat-portal)
- docker-compose.yml at root
- PostgreSQL database (not local — external server)

Phase 2 — Basic CI (Automated Build)¶

Target: Day 3–5 Owner: Java Developer + Team Lead

Every push to develop or main automatically builds all services and confirms there are no compilation errors.

What Gets Created¶

File: .github/workflows/ci.yml in the repository root

What It Does¶

Triggers on every push to develop or main
Checks out the code
Sets up Java 17
Runs mvn clean package -DskipTests for each service
Sets up Node.js
Runs npm run build for the React frontend
Reports success or failure via email

AI Prompt for This Phase¶

Create a GitHub Actions workflow file for a Spring Boot microservices project.

Requirements:
- Trigger on push to 'develop' and 'main' branches
- Java 17, Maven build
- React.js frontend build (Node.js 18)
- Multiple services in separate folders under: cbms-ai-microservies/microservices/
  Services: customer-service, deposit-service, transaction-service,
  product-service, generalledger-service, system-setup-service,
  periodicactivity-service, share-service, bankandbranch-service, common-service
- Frontend in: cbms-ai-dev-portal/arcat-portal/
- Skip tests for now
- Send email notification on failure
- Show build status badge in README

Do not use Docker in this phase — build only.

Phase 3 — Docker Image Build and Push¶

Target: Week 2 Owner: Java Developer + Team Lead

After a successful build, automatically create Docker images for all services and push them to GitHub Container Registry (GHCR).

What Gets Created¶

File: .github/workflows/docker-build.yml

What It Does¶

Runs after CI build passes
Builds Docker image for each service using existing Dockerfiles
Tags images with the Git commit hash and latest
Pushes images to GHCR
Images are available to pull on any server

AI Prompt for This Phase¶

Extend the GitHub Actions workflow to build and push Docker images after
a successful Maven build.

Requirements:
- Use GitHub Container Registry (GHCR) — ghcr.io
- Build Docker image for each Spring Boot service
- Each service has its own Dockerfile
- Tag images with: latest AND the git commit SHA
- Authenticate with GHCR using GITHUB_TOKEN (no extra secrets needed)
- Only build images on push to 'develop' and 'main'
- Services list: customer-service, deposit-service, transaction-service,
  product-service, generalledger-service, system-setup-service,
  periodicactivity-service, share-service, bankandbranch-service, common-service

Existing docker-compose.yml uses local build context.
After this phase, docker-compose.yml should pull from GHCR instead of building locally.

Phase 4 — Automated Deployment to Development Server¶

Target: Week 2–3 Owner: Team Lead

After images are pushed to GHCR, automatically deploy to the development server by pulling the new images and restarting Docker Compose.

What Gets Created¶

File: .github/workflows/deploy-dev.yml

Server Setup Required (One Time)¶

# On the development server — run once
# 1. Install Docker and Docker Compose
# 2. Clone the repository
# 3. Create a deployment SSH key
# 4. Add the public key to the server's authorized_keys
# 5. Add the private key to GitHub Secrets as SSH_DEV_SERVER_KEY
# 6. Add server IP to GitHub Secrets as DEV_SERVER_IP

What the Pipeline Does on Each Push to `develop`¶

GitHub Actions
      │
      ├── SSH into development server
      │
      ├── git pull (get latest docker-compose.yml)
      │
      ├── docker-compose pull (pull new images from GHCR)
      │
      └── docker-compose up -d (restart with new images)

AI Prompt for This Phase¶

Create a GitHub Actions deployment workflow for a development server.

Requirements:
- Trigger after Docker images are successfully pushed to GHCR
- Deploy only on push to 'develop' branch
- Use SSH to connect to the development server
- Server IP stored in GitHub Secret: DEV_SERVER_IP
- SSH key stored in GitHub Secret: SSH_DEV_SERVER_KEY
- SSH user stored in GitHub Secret: DEV_SERVER_USER
- On the server: cd to project folder, pull latest images, restart docker-compose
- Send notification on deployment success or failure
- The docker-compose.yml on the server pulls images from GHCR

Commands to run on server:
  cd /opt/cbms
  git pull origin develop
  docker-compose pull
  docker-compose up -d
  docker-compose ps

Phase 5 — Production Deployment with Manual Approval¶

Target: Week 3–4 Owner: Team Lead

Production deployments require manual approval from the Team Lead before the pipeline proceeds. This prevents accidental deployments.

What Gets Created¶

File: .github/workflows/deploy-prod.yml

How It Works¶

Push to main
      │
      ▼
Docker images built and pushed
      │
      ▼
GitHub sends approval request to Team Lead (email)
      │
      ▼
Team Lead reviews and clicks Approve on GitHub
      │
      ▼
Pipeline SSHs into production server
      │
      ▼
docker-compose pull + docker-compose up -d

AI Prompt for This Phase¶

Create a GitHub Actions workflow for production deployment with manual approval.

Requirements:
- Trigger on push to 'main' branch only
- Require manual approval from Team Lead before deploying
  (Use GitHub Environments with required reviewers)
- Environment name: 'production'
- SSH into production server
- Production server IP in secret: PROD_SERVER_IP
- SSH key in secret: SSH_PROD_SERVER_KEY
- Run same Docker Compose commands as dev deployment
- Send deployment notification on success
- On failure: alert immediately and do not proceed

Phase 6 — Notifications and Monitoring¶

Target: Week 4 Owner: Java Developer + Team Lead

The team gets notified of build results, deployment status, and service health without checking GitHub manually.

Notifications Setup¶

Option A — Email (simplest) GitHub Actions sends email on build failure automatically if configured in the workflow.

Option B — Microsoft Teams / Slack webhook

AI Prompt:
Add Microsoft Teams notification to our GitHub Actions workflow.
Send a card message on:
1. Build failure — red card, show which service failed
2. Deployment success — green card, show environment and version deployed
3. Deployment failure — red card, show error

Teams webhook URL stored in GitHub Secret: TEAMS_WEBHOOK_URL

Basic Health Check¶

After deployment, the pipeline verifies each service is running:

AI Prompt:
After docker-compose up -d in our deployment workflow,
add a health check step that:
1. Waits 30 seconds for services to start
2. Calls the /actuator/health endpoint of each Spring Boot service
3. Fails the pipeline if any service reports DOWN
4. Lists all service health statuses in the job summary

Services run on ports:
customer-service: 8081
deposit-service: 8082
transaction-service: 8083
product-service: 8084
generalledger-service: 8085
(add remaining services and ports)

Complete Pipeline Summary¶

Once all phases are complete, the full workflow looks like this:

Domain Expert finishes a screen
         │
         ▼
Shares files with Java Developer
         │
         ▼
Java Developer integrates, tests locally with Docker
         │
         ▼
git commit + git push origin feature/screen-name
         │
         ▼
Java Developer merges to develop
         │
         ▼
────────────── AUTOMATIC FROM HERE ──────────────
         │
         ▼
GitHub Actions: Build all services (2–3 min)
         │
         ▼
GitHub Actions: Build Docker images (3–5 min)
         │
         ▼
GitHub Actions: Push images to GHCR
         │
         ▼
GitHub Actions: Deploy to development server (1–2 min)
         │
         ▼
Teams notification: "Development deployment successful"
         │
         ▼
Team Lead reviews development environment
         │
         ▼
git merge develop → main
         │
         ▼
GitHub Actions: Build + Docker (same as above)
         │
         ▼
GitHub sends approval request to Team Lead
         │
         ▼
Team Lead approves on GitHub
         │
         ▼
GitHub Actions: Deploy to production server
         │
         ▼
Teams notification: "Production deployment successful"

Total time from code push to development server: ~10 minutes, fully automated.

GitHub Secrets Required¶

Set these in GitHub → Repository → Settings → Secrets and Variables → Actions

Secret Name	Value	Who Sets It
`SSH_DEV_SERVER_KEY`	Private SSH key for dev server	Team Lead
`DEV_SERVER_IP`	Development server IP address	Team Lead
`DEV_SERVER_USER`	SSH username on dev server	Team Lead
`SSH_PROD_SERVER_KEY`	Private SSH key for prod server	Team Lead
`PROD_SERVER_IP`	Production server IP address	Team Lead
`PROD_SERVER_USER`	SSH username on prod server	Team Lead
`TEAMS_WEBHOOK_URL`	Microsoft Teams webhook URL	Team Lead

Responsibilities Summary¶

Task	Domain Expert	Java Developer	Team Lead
Create GitHub repository			✓
Push initial project		✓
Set branch protection rules			✓
Write CI workflow		With AI	Reviews
Write Docker build workflow		With AI	Reviews
Write deploy-dev workflow			With AI
Write deploy-prod workflow			With AI
Set up development server			✓
Set up production server			✓
Add GitHub Secrets			✓
Daily Git operations	Share files only	✓	Merge to main
Monitor pipelines		Watches build	Approves prod

Phase Timeline¶

Phase	What	Timeline	Owner
Phase 1	Git repository setup	Day 1–2	Java Dev + Team Lead
Phase 2	Automated build on push	Day 3–5	Java Dev + Team Lead
Phase 3	Docker image build and push	Week 2	Java Dev + Team Lead
Phase 4	Auto deploy to dev server	Week 2–3	Team Lead
Phase 5	Production deploy with approval	Week 3–4	Team Lead
Phase 6	Notifications and health checks	Week 4	Java Dev + Team Lead

AI Prompts — Troubleshooting¶

When something does not work, use these prompts with the AI:

Build failure:

My GitHub Actions build is failing. Here is the error log:
[paste the error from GitHub Actions]
The project is Spring Boot (Java 17, Maven) with React.js frontend.
Explain the error and suggest a fix.
Do not make code changes.

Deployment failure:

My GitHub Actions deployment to the server failed. Here is the error:
[paste the error]
The deployment uses SSH to connect to a Ubuntu server
and runs docker-compose up -d.
Explain the error and suggest a fix.

Docker Compose not starting after deployment:

After deployment, docker-compose up -d runs but services are not healthy.
Here are the logs: [paste docker logs output]
Suggest what is wrong and how to fix it.

Internal Document — Team Implementation Guide CBMS Project · 2026-06-10 For detailed architecture context refer to: docs/Architecture_Decision_DB_Functions_vs_Java.md

CI/CD and Git Implementation Roadmap¶

What This Document Covers¶

Plain English — What These Terms Mean¶

Tool Selection¶

Environment Strategy¶

Git Branch Strategy¶

Rules¶

Daily Git Workflow — Per Role¶

Domain Expert (working with AI on a screen)¶

Java Developer (integrator and Git manager)¶

Team Lead (production releases)¶

CI/CD Pipeline Design¶

Implementation Roadmap¶

Phase 1 — Git Setup¶

Steps¶

AI Prompt for This Phase¶

Phase 2 — Basic CI (Automated Build)¶

What Gets Created¶

What It Does¶

AI Prompt for This Phase¶

Phase 3 — Docker Image Build and Push¶

What Gets Created¶

What It Does¶

AI Prompt for This Phase¶

Phase 4 — Automated Deployment to Development Server¶

What Gets Created¶

Server Setup Required (One Time)¶

What the Pipeline Does on Each Push to develop¶

AI Prompt for This Phase¶

Phase 5 — Production Deployment with Manual Approval¶

What Gets Created¶

How It Works¶

AI Prompt for This Phase¶

Phase 6 — Notifications and Monitoring¶

Notifications Setup¶

Basic Health Check¶

Complete Pipeline Summary¶

GitHub Secrets Required¶

Responsibilities Summary¶

Phase Timeline¶

AI Prompts — Troubleshooting¶

What the Pipeline Does on Each Push to `develop`¶