🚀 CI/CD Setup Guide (For Developers)

This project uses a centralized CI/CD system. You only need to configure 1 workflow file + secrets.

---

📁 1. Add Workflow File

Create:

.gitea/workflows/ci.yml

Paste:

name: CI

on:
  push:
    branches: [main, beta, staging, testing]
  pull_request:

jobs:
  ci:
    # Prefer a commit SHA from wdipl-actions @main (see "stale reusable workflows" above).
    uses: http://git.wdipl.com/Rajendra.Reddy/wdipl-actions/.gitea/workflows/ci.yml@main

    with:
      tech_stack: node

      # Comma-separated: build, sonar, deploy (WDIPL-Runner only forwards one “flag” string reliably).
      ci_steps: 'build,sonar,deploy'
      wait_for_quality_gate: 'false'

      app_path_beta: /var/www/app-beta
      app_path_staging: /var/www/app-staging
      app_path_prod: /var/www/app-prod

      pm2_id: app

    secrets:
      SONARQUBE_HOST: ${{ secrets.SONARQUBE_HOST }}
      SONARQUBE_TOKEN: ${{ secrets.SONARQUBE_TOKEN }}

      BETA_SERVER_HOST: ${{ secrets.BETA_SERVER_HOST }}
      BETA_SERVER_PORT: ${{ secrets.BETA_SERVER_PORT }}
      BETA_SERVER_USERNAME: ${{ secrets.BETA_SERVER_USERNAME }}
      BETA_SERVER_PASSWORD: ${{ secrets.BETA_SERVER_PASSWORD }}
      BETA_SERVER_KEY: ${{ secrets.BETA_SERVER_KEY }}

      STAGING_SERVER_HOST: ${{ secrets.STAGING_SERVER_HOST }}
      STAGING_SERVER_PORT: ${{ secrets.STAGING_SERVER_PORT }}
      STAGING_SERVER_USERNAME: ${{ secrets.STAGING_SERVER_USERNAME }}
      STAGING_SERVER_PASSWORD: ${{ secrets.STAGING_SERVER_PASSWORD }}
      STAGING_SERVER_KEY: ${{ secrets.STAGING_SERVER_KEY }}

      PROD_SERVER_HOST: ${{ secrets.PROD_SERVER_HOST }}
      PROD_SERVER_PORT: ${{ secrets.PROD_SERVER_PORT }}
      PROD_SERVER_USERNAME: ${{ secrets.PROD_SERVER_USERNAME }}
      PROD_SERVER_PASSWORD: ${{ secrets.PROD_SERVER_PASSWORD }}
      PROD_SERVER_KEY: ${{ secrets.PROD_SERVER_KEY }}

---

🔐 2. Add Secrets (Repo → Settings → Secrets)

SonarQube

Name	Value
SONARQUBE_HOST	http://your-sonar-server
SONARQUBE_TOKEN	your sonar token

---

Beta / Testing Server

Name	Value
BETA_SERVER_HOST	server IP/domain
BETA_SERVER_PORT	22
BETA_SERVER_USERNAME	ssh user (ubuntu/root)
BETA_SERVER_PASSWORD	password (optional)
BETA_SERVER_KEY	private ssh key (optional)

---

Staging Server

Name	Value
STAGING_SERVER_HOST	server IP/domain
STAGING_SERVER_PORT	22
STAGING_SERVER_USERNAME	ssh user
STAGING_SERVER_PASSWORD	password (optional)
STAGING_SERVER_KEY	ssh key (optional)

---

Production Server

Name	Value
PROD_SERVER_HOST	server IP/domain
PROD_SERVER_PORT	22
PROD_SERVER_USERNAME	ssh user
PROD_SERVER_PASSWORD	password (optional)
PROD_SERVER_KEY	ssh key (optional)

---

⚙️ 3. Variables (Edit in ci.yml)

Variable	What to set
tech_stack	node / react / nestjs
ci_steps	e.g. build,sonar,deploy — no spaces (runner has no replace())
wait_for_quality_gate	'true' / 'false' (quoted)
app_path_beta	path on beta server
app_path_staging	path on staging server
app_path_prod	path on prod server
pm2_id	pm2 app name

---

🌿 4. Branch Behavior

Branch	Action
feature/*	Build + Sonar
develop	Build + Sonar
testing	Deploy to Beta
beta	Deploy to Beta
staging	Deploy to Staging
main / prod	Deploy to Production

---

⚙️ 5. What Happens on Deploy

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

npm install
npm run build
pm2 reload <pm2_id>

---

WDIPL-Runner: stale reusable workflows (uses: ...@main)

The runner caches clones under /root/.cache/act/ (e.g. Rajendra.Reddy-wdipl-actions@main). After you change wdipl-actions, consumers may still execute an old ci.yml (wrong if: / missing ci_steps).

Central ci.yml includes a meta job that writes ci_steps to $GITHUB_OUTPUT so needs.meta.outputs.cs stays available for Sonar/Deploy: WDIPL-Runner clears inputs.ci_steps after the Build reusable workflow runs.

Fix one of:

1. Pin uses: to a commit SHA from wdipl-actions, e.g.
   uses: .../ci.yml@08e779fe5701557b6a589308816be97c20d78dbb
   Bump the SHA whenever you change central CI.
2. On the runner host, delete that cache folder and re-run the workflow.
3. Upgrade the runner if a newer release fixes cache invalidation.

---

Gitea MCP + Actions API (Cursor)

Official gitea-mcp (and the Go SDK it uses) calls GET /api/v1/repos/{owner}/{repo}/actions/runs to list workflow runs and job logs.

• Gitea 1.24.x exposes /actions/tasks for the same data but does not register /actions/runs (returns 404 page not found). Tools like actions_run_read → list_runs / list_jobs will fail until the server is updated or a proxy workaround is applied.
• Gitea 1.25+ includes ListWorkflowRuns at /actions/runs — upgrade git.wdipl.com to 1.25 or newer so MCP can list runs and fetch logs without hacks.

Reverse-proxy workaround (until upgrade): map list-runs requests to tasks (response shape is compatible for listing):

# Only for the repository runs list endpoint (no trailing /{run})
location ~ ^/api/v1/repos/([^/]+)/([^/]+)/actions/runs$ {
  proxy_pass http://127.0.0.1:3000/api/v1/repos/$1/$2/actions/tasks$is_args$args;
  # ... usual proxy headers to your Gitea backend
}

Adjust proxy_pass to your Gitea HTTP upstream. Redeploy/reload nginx, then restart Cursor.

Cursor: set a user or system environment variable GITEA_ACCESS_TOKEN (PAT with repo + Actions read scope) and use ${env:GITEA_ACCESS_TOKEN} in ~/.cursor/mcp.json — do not store tokens in that file.

---

⚠️ Notes

• Use either password OR SSH key

• Ensure server has:

  • Node.js
  • PM2

• Paths must exist on server

• Deployment runs only if ci_steps includes deploy (comma‑bounded token)

---

✅ Summary

1. Add ci.yml
2. Add secrets
3. Set paths

Done.

---