Skip to content

CI/CD — GitHub Actions

Deployments are fully automated via GitHub Actions. Pushing to monitored branches triggers a pipeline that SSHes into the VPS and rebuilds only the services that changed.

Pipeline File

.github/workflows/deploy.yml

Trigger Conditions

Event Branches
Push main, master, newbranch
Manual trigger Any branch (via GitHub Actions UI → "Run workflow")

How It Works

The pipeline has two jobs that run sequentially.

Job 1: detect-changes

Uses dorny/paths-filter@v3 to detect which directories changed in the pushed commit.

Output variable Watches path
streamsearch backend-streamsearch/**
vectorindexing backend-vectorindexing/**
generatereport backend-generatereport/**
ragevaluation backend-ragevaluation/**
dailysummary backend-dailysummary/**
workflow backend-workflow/**
frontend_workflow frontend-workflow/**
accounts backend-accounts/**
agent backend-agent/**
pageindex backend-pageindex/**
docker_config docker-compose*.yml, monitoring/**, caddy/**

If none of these paths changed and the trigger is not a manual dispatch, the deploy job is skipped entirely.

Job 2: deploy

Only runs if at least one path changed (or triggered manually). Steps:

  1. SSH into the VPS using appleboy/ssh-action@v1.0.0
  2. cd $PROJECT_PATH && git pull — pull latest code
  3. For each changed service: docker-compose stop <service>
  4. For each changed service: docker build (or docker-compose build) to rebuild the image
  5. For each changed service: docker-compose up -d <service>
  6. Wait 30 seconds for services to start
  7. Run docker-compose ps to verify health
  8. docker system prune -f to clean up old images

docker_config changes

If only docker-compose.yml, monitoring configs, or Caddy config changed (no service code changed), all backend services are restarted.

Required GitHub Secrets

Go to GitHub repo → Settings → Secrets and variables → Actions to view/update these:

Secret Description
VPS_HOST VPS IP address (172.237.81.37)
VPS_USER SSH username (zygy)
SSH_PRIVATE_KEY Private SSH key that grants access to the VPS
VPS_PORT SSH port (defaults to 22 if not set)
PROJECT_PATH Absolute path to the project on the VPS (e.g. /home/zygy/docker)

On Handover

When the previous developer leaves, rotate the SSH key (SSH_PRIVATE_KEY) immediately. Generate a new key pair, add the public key to ~/.ssh/authorized_keys on the VPS, and update the secret.

Manual Deployment

To deploy manually without pushing code:

  1. Go to the GitHub repository
  2. Click Actions tab
  3. Select Deploy to VPS workflow
  4. Click Run workflow → choose branch → Run workflow

This is equivalent to a push and will deploy all services that have changed since the last deploy (or all services if triggered after a docker config change).

Deploying a Single Service Manually (SSH)

If you need to force-redeploy one service without a code change:

ssh zygy@172.237.81.37
cd $PROJECT_PATH

# Rebuild and restart one service (always use --build)
docker-compose stop backend-streamsearch
docker build -t backend-streamsearch -f ./backend-streamsearch/Dockerfile .
docker-compose up -d backend-streamsearch

Always use --build or explicit docker build

docker-compose restart does not rebuild the image. You must stop the container, build the image, then start it. See MODEL_CHANGER_GUIDE.md in the project root for why this matters.