How-To: The Git & Deployment Workflow

This guide outlines the complete workflow for contributing code, from local development to production deployment on the VPS.

Overview

The process is designed to be safe and structured, using a dev branch for integration and a main branch for production-ready code. Most steps are automated via scripts and GitHub Actions.

graph TD
    subgraph "Local Machine"
        A(Your Feature Branch) --> B{Commit & Run Script};
        B --> C[scripts/local-sync-dev.sh];
    end
    
    C -->|Pushes to| D[origin/dev];
    
    subgraph "GitHub Repository"
        D --> E{Automated PR};
        E -- "PR to main" --> F[Pull Request];
        F -- "Manual Review & Merge" --> G[origin/main];
    end
    
    subgraph "Production VPS"
        G -->|Triggers| H[GitHub Action: Deploy];
        H --> I[scripts/vps-deploy.sh];
        I --> J[Live Application];
    end

    style F fill:#00A,color:#fff
    style G fill:#080,color:#fff

---

Step 1: Local Development

All new work should be done on a local feature branch created from the dev branch.

# Ensure you have the latest dev branch
git checkout dev
git pull origin dev

# Create your new feature branch
git checkout -b my-new-feature

Make your code changes, commit them to your feature branch, and then merge your changes back into your local dev branch when ready.

Step 2: Push to the dev Branch

Instead of manually pushing, use the provided helper script. This script ensures your local dev branch is up-to-date before pushing your changes.

From the project root, run:

./scripts/local-sync-dev.sh "Your meaningful commit message here"

This script will:

1. Stage all your current changes.
2. Commit them with the message you provided.
3. Pull the latest changes from the remote dev branch.
4. Rebase your new commit on top of the remote changes.
5. Push the final result to origin/dev.

(View the script: ./scripts/local-sync-dev.sh)

Step 3: Create a Pull Request (Automated)

When changes are pushed to the dev branch, a GitHub Action is automatically triggered to create a Pull Request from dev to main.

• Action File: .github/workflows/dev-to-main-pr.yml

This PR must be reviewed and approved by at least one other team member before it can be merged. This ensures code quality and prevents accidental changes from reaching production.

Step 4: Deploy to Production (Automated)

Once the Pull Request is approved and merged into the main branch, another GitHub Action automatically triggers the deployment to the production VPS.

• Action File: .github/workflows/deploy.yml

This action securely connects to the VPS and executes the deployment script, which handles fetching the latest code, installing dependencies, running migrations, and clearing caches.

• Deployment Script: ./scripts/vps-deploy.sh

The deployment is zero-downtime and includes health checks and automatic rollback procedures if any step fails.