Skip to main content

Git Workflow Guide

Branch Structure​

  • main - Primary branch, contains production-ready code
    • Feature branches merge here
    • Automatically deploys to staging on merge
    • Production deployment requires manual trigger with approval
  • develop - DEPRECATED: No longer used for deployments (kept for reference)
  • feature/* - Feature branches for new development
  • release/* - Release branches for version preparation (optional)
  • hotfix/* - Hotfix branches for critical production fixes

Workflow Steps​

1. Feature Development​

# Create a feature branch from main
git checkout main
git pull origin main
git checkout -b feature/your-feature-name

# Work on your feature...

# Keep your feature branch up to date
git checkout main
git pull origin main
git checkout feature/your-feature-name
git merge main

# Push your feature branch
git push origin feature/your-feature-name

# Create a pull request to main branch

2. Staging Deployment​

The main branch automatically deploys to the staging environment when PRs are merged.

# After PR approval, merge feature into main
# (Done via GitHub PR merge button)
# Staging deployment triggers automatically

3. Release Process (Optional)​

# Create a release branch from main
git checkout main
git pull origin main
git checkout -b release/v1.x.x

# Make release-specific changes (version numbers, etc.)
# Test thoroughly in staging

# Merge to main
git checkout main
git merge release/v1.x.x
git tag -a v1.x.x -m "Release v1.x.x"
git push origin main --tags

# Delete release branch
git branch -d release/v1.x.x
git push origin --delete release/v1.x.x

4. Hotfix Process​

# Create hotfix branch from main
git checkout main
git pull origin main
git checkout -b hotfix/issue-description

# Make fixes...

# Create PR to main
# After merge, staging deploys automatically
# Test in staging, then manually trigger production deployment

# Tag the release
git checkout main
git tag -a v1.x.x -m "Hotfix v1.x.x"
git push origin main --tags

# Delete hotfix branch
git branch -d hotfix/issue-description
git push origin --delete hotfix/issue-description

Environment Configuration​

Staging Environment​

  • Automatically deployed from main branch (on PR merge)
  • Uses staging-specific environment variables from GitHub Environment
  • Enables testing of new features
  • No approval required

Production Environment​

  • Deployed from main branch (manual trigger)
  • Uses production environment variables from GitHub Environment
  • Requires deployment approval (GitHub Environments protection)
  • Only deploys after staging is verified

Commit Guidelines​

  1. Use conventional commit messages:

    feat: add new feature
    fix: resolve bug
    docs: update documentation
    style: format code
    refactor: restructure code
    test: add tests
    chore: update dependencies

  2. Include ticket/issue numbers in commits when applicable:

    feat(FLOW-123): implement user authentication

Branch Protection Rules​

Main Branch (main)​

  • Requires pull request approvals
  • Requires passing CI checks (pre-merge validation)
  • No direct pushes
  • Accepts merges from feature, release, or hotfix branches

Develop Branch (develop)​

  • DEPRECATED: No longer used for deployments
  • Can be kept for reference or removed

CI/CD Pipeline​

Pull Request Checks​

  • Lint code
  • Run unit tests
  • Run integration tests
  • Build check
  • Code coverage check

Staging Deployment​

  • Automatic deployment on merge to main
  • Only changed applications are deployed
  • Uses staging GitHub Environment secrets
  • All validation steps run (Firebase, database, etc.)

Production Deployment​

  • Manual trigger via GitHub Actions (workflow_dispatch)
  • Requires approval through GitHub Environments
  • Only changed applications are deployed
  • Uses production GitHub Environment secrets
  • All validation steps run
  • Can deploy specific commit SHA if needed

Best Practices​

  1. Keep feature branches short-lived
  2. Regularly sync with develop branch
  3. Write clear commit messages
  4. Review code before creating pull requests
  5. Delete merged feature branches
  6. Tag all production releases
  7. Document significant changes in CHANGELOG.md

Monorepo Considerations​

When working with packages in the monorepo:

  1. Specify affected packages in commit messages:

    feat(web-app,backend): implement user authentication

  2. Use pnpm commands for package-specific operations:

    pnpm --filter web-app build
    pnpm --filter backend test

  3. Ensure changes don't break other packages by running:

    pnpm run build
    pnpm run test