GitLab Flow Strategy — Branching Model for Production Deployments

A Git workflow strategy supporting 5 parallel work streams, multiple environments, and a monthly review process — using GitLab Flow with feature branches for domain-driven development.

Overview

GitLab Flow Strategy for the Lakehouse project is designed to support 5 parallel work streams, multiple environments, and a monthly review process.

Branch Strategy

Core Branches

main (production)
├── staging 
├── develop
└── feature branches

Branch Purposes

Branch	Purpose	Environment	Auto Deploy
`main`	Production ready code	Production	Yes
`staging`	Release candidate testing	Staging	Yes
`develop`	Integration branch	Development	Yes
`feature/*`	Work stream development	Local/Dev	No

Work Stream Branch Mapping

Phase 01 Work Streams

develop
├── feature/ws1-infrastructure-devops
├── feature/ws2-data-engineering-platform  
├── feature/ws3-customer-domain-data
├── feature/ws4-data-catalog-governance
└── feature/ws5-analytics-api-layer

Domain-Specific Branches (Future Phases)

develop
├── feature/domain-01-customer
├── feature/domain-02-lending
├── feature/domain-03-risk
├── feature/domain-04-finance
└── feature/domain-xx-[domain-name]

Deployment Pipeline

Environment Flow

Feature Branch → Develop → Staging → Main (Production)
     ↓             ↓         ↓         ↓
   Local Dev   → Dev Env  → Staging → Production

Deployment Triggers

Develop: Auto-deploy on merge
Staging: Auto-deploy on PR to staging
Main: Auto-deploy on merge (with approval)

Monthly Review Integration

Month-End Process

Week 4: Feature freeze for current month
Month End: Merge develop → staging
Review Week: Stakeholder testing on staging
Approval: Merge staging → main (production)

Monthly Branches

release/2025-07-phase01-month1
release/2025-08-phase01-month2  
release/2025-09-phase01-month3

Branch Protection Rules

Main Branch Protection

Require pull request reviews (2 reviewers)
Require status checks to pass
Require branches to be up to date
Restrict pushes to admins only
Require conversation resolution

Staging Branch Protection

Require pull request reviews (1 reviewer)
Require status checks to pass
Allow force pushes for hotfixes

Develop Branch Protection

Require status checks to pass
Allow direct pushes for integration

Team Workflow

Work Stream Leads

Each work stream lead manages their feature branch:

# WS1: Infrastructure & DevOps
git checkout -b feature/ws1-infrastructure-devops develop
 
# WS2: Data Engineering Platform  
git checkout -b feature/ws2-data-engineering-platform develop
 
# WS3: Customer Domain Sample Data
git checkout -b feature/ws3-customer-domain-data develop
 
# WS4: Data Catalog & Governance
git checkout -b feature/ws4-data-catalog-governance develop
 
# WS5: Analytics & API Layer
git checkout -b feature/ws5-analytics-api-layer develop

Daily Development Workflow

# 1. Start work on feature
git checkout feature/ws1-infrastructure-devops
git pull origin feature/ws1-infrastructure-devops
 
# 2. Create sub-feature for specific task
git checkout -b feature/ws1-docker-compose
 
# 3. Develop and commit
git add .
git commit -m "feat(ws1): add docker-compose for spark cluster"
 
# 4. Push and create PR to work stream branch
git push origin feature/ws1-docker-compose
# Create PR: feature/ws1-docker-compose → feature/ws1-infrastructure-devops

Integration Workflow

# Weekly integration to develop
git checkout develop
git pull origin develop
 
# Merge work stream progress
git merge feature/ws1-infrastructure-devops
git merge feature/ws2-data-engineering-platform
# ... other work streams
 
git push origin develop

CI/CD Integration

Pipeline Configuration

# .gitlab-ci.yml or .github/workflows/
stages:
  - test
  - build
  - deploy
 
# Environment-specific deployments
deploy-dev:
  stage: deploy
  script: docker-compose -f docker-compose.dev.yml up -d
  only: [develop]
 
deploy-staging:
  stage: deploy  
  script: docker-compose -f docker-compose.staging.yml up -d
  only: [staging]
 
deploy-prod:
  stage: deploy
  script: docker-compose -f docker-compose.prod.yml up -d
  only: [main]
  when: manual

Docker Environment Configs

docker-compose.dev.yml      # Development environment
docker-compose.staging.yml  # Staging environment  
docker-compose.prod.yml     # Production environment

Commit Message Convention

Format

<type>(<scope>): <description>

[optional body]

[optional footer]

Types

feat: New feature
fix: Bug fix
docs: Documentation
style: Code style changes
refactor: Code refactoring
test: Adding tests
chore: Maintenance tasks

Scopes (Work Streams)

ws1: Infrastructure & DevOps
ws2: Data Engineering Platform
ws3: Customer Domain Data
ws4: Data Catalog & Governance
ws5: Analytics & API Layer

Examples

git commit -m "feat(ws1): add docker-compose for complete lakehouse stack"
git commit -m "fix(ws3): resolve customer data generation script encoding issue"
git commit -m "docs(ws4): add data catalog setup instructions"

Hotfix Process

Critical Production Issues

# 1. Create hotfix from main
git checkout main
git checkout -b hotfix/critical-security-patch
 
# 2. Apply fix
git add .
git commit -m "hotfix: patch critical security vulnerability"
 
# 3. Merge to main and staging
git checkout main
git merge hotfix/critical-security-patch
git push origin main
 
git checkout staging  
git merge hotfix/critical-security-patch
git push origin staging
 
# 4. Clean up
git branch -d hotfix/critical-security-patch

Monitoring & Metrics

Branch Health Metrics

Merge Frequency: Target daily merges to develop
PR Review Time: <24 hours average
Build Success Rate: >95% on all branches
Deploy Success Rate: >99% on staging/main

Git Flow Metrics

# Check branch status
git branch -r --merged develop    # Merged branches
git branch -r --no-merged develop # Active branches
 
# Check commit activity
git log --oneline --since="1 week ago" --graph

Setup Commands

Initial Repository Setup

# Clone repository
git clone <repository-url>
cd <project-root>
 
# Create and push core branches
git checkout -b develop
git push -u origin develop
 
git checkout -b staging  
git push -u origin staging
 
# Create work stream branches
git checkout develop
git checkout -b feature/ws1-infrastructure-devops
git push -u origin feature/ws1-infrastructure-devops
 
git checkout develop
git checkout -b feature/ws2-data-engineering-platform
git push -u origin feature/ws2-data-engineering-platform
 
git checkout develop
git checkout -b feature/ws3-customer-domain-data
git push -u origin feature/ws3-customer-domain-data
 
git checkout develop
git checkout -b feature/ws4-data-catalog-governance
git push -u origin feature/ws4-data-catalog-governance
 
git checkout develop
git checkout -b feature/ws5-analytics-api-layer
git push -u origin feature/ws5-analytics-api-layer

Best Practices

Do's

Keep feature branches focused and short-lived
Merge work stream progress to develop weekly
Use descriptive commit messages with work stream scope
Test thoroughly before merging to staging
Coordinate with other work stream leads for integration

Don'ts

Don't push directly to main or staging
Don't merge broken code to develop
Don't create long-lived feature branches (>2 weeks)
Don't skip code reviews
Don't ignore merge conflicts

Git Configuration

Local Git Setup

# Set user info
git config user.name "Your Name"
git config user.email "your.email@company.com"
 
# Set default branch
git config init.defaultBranch main
 
# Enable auto-rebase for pulls
git config pull.rebase true
 
# Set up aliases
git config alias.st status
git config alias.co checkout
git config alias.br branch
git config alias.lg "log --oneline --graph --decorate"

VS Code Git Settings

{
  "git.enableSmartCommit": true,
  "git.autofetch": true,
  "git.autoStash": true,
  "git.confirmSync": false,
  "git.defaultCloneDirectory": "./workspaces",
  "git.fetchOnPull": true
}

Resources

Git Commands Cheat Sheet

# Daily workflow
git status                          # Check working directory
git add .                          # Stage all changes
git commit -m "message"            # Commit changes
git push origin branch-name        # Push to remote
 
# Branch management
git branch                         # List local branches
git branch -r                      # List remote branches
git checkout -b new-branch         # Create and switch branch
git merge branch-name              # Merge branch
 
# Synchronization
git fetch origin                   # Fetch remote changes
git pull origin branch-name        # Pull and merge
git rebase origin/develop          # Rebase on develop

Troubleshooting

# Resolve merge conflicts
git status                         # See conflicted files
# Edit files to resolve conflicts
git add conflicted-file.txt
git commit -m "resolve merge conflict"
 
# Undo last commit (local only)
git reset --soft HEAD~1
 
# Force sync with remote (DANGER)
git reset --hard origin/branch-name

Next Steps:

Setup branch protection rules in GitLab/GitHub
Configure CI/CD pipeline with environment-specific deployments
Train team on GitLab Flow workflow
Establish code review process
Begin Phase 01 development with work stream branches