🚀 CI/CD Deployment Guide (Template)

📌 This is a ready-to-use template. Replace example values with your own before using.

---

📦 Overview

This CI/CD setup automatically deploys your application when code is merged into environment branches.

---

🔁 Workflow (How Deployment Happens)

feature/* → PR → main → PR → (beta/testing/staging/production) → 🚀 deploy

Steps:

1. Create feature branch → feature/xyz
2. Raise PR → main
3. Merge into main
4. Raise PR → main → target environment branch
5. Merge → Deployment runs automatically

---

🌿 Branch Strategy

Branch	Purpose
main	Stable code
beta	Internal testing
testing	QA testing
staging	Pre-production
production	Live

---

⚙️ Environment Configuration

Each branch deploys to a different server.

Example Mapping

Branch	Folder Path Example	PM2_ID Example
beta	/home/user/app-beta	app-beta[3000]
testing	/home/user/app-testing	app-testing[3001]
staging	/var/www/app-staging	app-staging[4000]
production	/var/www/app-prod	app-prod[5000]

---

⚠️ PM2 Naming (VERY IMPORTANT)

Your PM2 process should be named like:

app-name[port]

✅ Example

app-backend[3000]

❌ Do NOT confuse with:

app-name[1234]   ← random ID (WRONG)

---

⚠️ IMPORTANT RULE (Shell Safety)

Always wrap PM2_ID in quotes:

pm2 reload "$PM2_ID"
pm2 logs "$PM2_ID" --lines 50 --nostream

---

⚡ What the Deployment Does

On every deploy:

cd <PROJECT_FOLDER>

git fetch
git reset --hard origin/<BRANCH_NAME>
git pull origin <BRANCH_NAME>

git log --oneline -5

npm install

pm2 reload "<PM2_ID>"

pm2 logs "<PM2_ID>" --lines 50 --nostream

---

🔐 Required Secrets (VERY IMPORTANT)

You MUST configure these in your CI/CD (Gitea → Repository → Settings → Secrets)

---

🟡 For Beta / Testing (Password-based SSH)

Required Secrets:

BETA_SERVER_HOST=1.2.3.4
BETA_SERVER_USERNAME=your-user
BETA_SERVER_PASSWORD=your-password
BETA_SERVER_PORT=22

👉 Used for:

• beta
• testing

---

🔵 For Staging (SSH Key-based)

Required Secrets:

STAGING_SERVER_HOST=1.2.3.5
STAGING_SERVER_USERNAME=ubuntu
STAGING_SERVER_KEY=<private-key-content>
STAGING_SERVER_PORT=22

---

🔴 For Production (SSH Key-based)

Required Secrets:

PRODUCTION_SERVER_HOST=1.2.3.6
PRODUCTION_SERVER_USERNAME=ubuntu
PRODUCTION_SERVER_KEY=<private-key-content>
PRODUCTION_SERVER_PORT=22

---

🔑 How to Add SSH Key

1. On your server:

   cat ~/.ssh/id_rsa
   

2. Copy the full private key:

   -----BEGIN OPENSSH PRIVATE KEY-----
   ...
   -----END OPENSSH PRIVATE KEY-----
   

3. Paste into:

   STAGING_SERVER_KEY / PRODUCTION_SERVER_KEY
   

---

🚀 How to Deploy

Deploy to Beta

• Create PR → main → beta
• Merge → auto deploy

Deploy to Testing

• PR → main → testing

Deploy to Staging

• PR → main → staging

Deploy to Production

• PR → main → production

---

🛠️ Debugging

Check CI Logs

• Gitea → Actions → Logs

SSH into Server

ssh user@server-ip
cd /your/project/path

Check PM2

pm2 list
pm2 logs

---

⚠️ Common Mistakes

❌ Using wrong PM2 ID

app-name[1234]  ← dynamic ID

❌ Not quoting PM2_ID

pm2 reload $PM2_ID   ❌

❌ Manual changes on server

git reset --hard will delete them

---

📈 Recommended Improvements

• Add npm run build
• Add health check
• Add rollback strategy
• Add notifications (Slack/Email)
• Add caching

---

🧑‍💻 TL;DR

• Always deploy via PR
• Use PM2 format: app-name[port]
• Always wrap in quotes
• Set correct secrets
• Never edit server manually

---

✅ Copy → Update values → Ready to use