Git Workflow

The Release Train Model

Eli Health uses a Release Train deployment model. Code flows through environments in a predictable, linear sequence:

Key Principle: Board the Train

Once your code is merged to development, it's on the train. All changes move together through staging to production—no cherry-picking, no skipping releases.

development → A → B → C → D → E → F → G  (all new work)
staging     → A → B → C → D → E          (tested subset)
production  → A → B → C                  (live)

Pull Request Workflow

All PRs Target Development

Every pull request goes against the development branch. No exceptions.

Branch Naming Conventions

Type	Pattern	Example
Feature	feature/description	feature/add-hormone-chart
Bug Fix	bugfix/description	bugfix/login-crash
Hotfix	hotfix/description	hotfix/critical-auth-bug

Environment Promotion

How Changes Move Through Environments

Promotion Commands

Development → Staging:

git checkout staging
git merge --ff-only development
git push origin staging

Staging → Production:

git checkout production
git merge --ff-only staging
git push origin production

The --ff-only flag ensures linear history and fails if branches have diverged (which shouldn't happen in our workflow).

The Complete Picture

Repositories Using This Workflow

All Eli Health repositories follow this branching strategy:

Repository	Description
eli-app	Mobile application (React Native)
eli-backend-api	Backend API service
eli_hae_api	HAE (Hormone Analysis Engine) API
eli-kpi	KPI Dashboard

Branch Strategy Details

Fast-Forward Merges Between Environments

Environment branches (staging, production) should never diverge. We use fast-forward merges to maintain linear history:

Before promotion:

After fast-forward:

Commits D, E, F keep their exact same Git hashes—no merge commits, no history rewriting.

Feature Branch Merging

When merging feature branches to development:

Squash Merge (Recommended):

• All feature commits become one clean commit
• Keeps development history readable
• PR description becomes commit message

# Via GitHub PR: Choose "Squash and merge"

Rebase + Fast-Forward:

• Preserves individual commits
• Useful for larger features with logical commit breakdown

Hotfix Process

Sometimes bugs need faster resolution than the normal release train allows.

Hotfix Levels

Level	When to Use	Speed	Branch From
Standard	Can wait for next release	Normal	development
Urgent	Critical, needs staging test	Fast	staging
Emergency	Production is broken	Immediate	production

Standard Hotfix (Normal Flow)

Urgent Hotfix (Skip Dev Testing)

After deploying to production, back-merge to development to keep branches in sync.

Emergency Hotfix (Production is Down)

Important: Emergency hotfixes should be rare. Always back-merge to keep all branches synchronized.

Quick Reference

Do's ✅

• Create feature branches from development
• Open all PRs against development
• Use squash merges for clean history
• Let all changes flow through the train together
• Back-merge hotfixes to keep branches synchronized

Don'ts ❌

• Never commit directly to staging or production
• Never cherry-pick individual commits between environments
• Never skip the staging environment for normal releases
• Never force push to shared branches

Summary

The Release Train model ensures:

1. Predictable releases - Changes flow in one direction
2. Quality gates - All code is tested on staging before production
3. Simple history - Linear git log, easy to understand
4. Team alignment - Everyone's code moves together

All PRs → development → staging → production
              ↑
         You are here