feat: Update CI workflows for Docker image build and deployment, enhance test configurations, and add testing documentation

.gitea/workflows/build-and-push.yml

@@ -1,11 +1,16 @@
 name: Build and Push Docker Image
 on:
-  push:
+  workflow_run:
+    workflows:
+      - Run Tests
     branches:
       - main
+    types:
+      - completed
 
 jobs:
   build-and-push:
+    if: ${{ github.event.workflow_run.conclusion == 'success' }}
     runs-on: ubuntu-latest
     env:
       DEFAULT_BRANCH: main
@@ -14,6 +19,8 @@ jobs:
       REGISTRY_URL: ${{ secrets.REGISTRY_URL }}
       REGISTRY_USERNAME: ${{ secrets.REGISTRY_USERNAME }}
       REGISTRY_PASSWORD: ${{ secrets.REGISTRY_PASSWORD }}
+      WORKFLOW_RUN_HEAD_BRANCH: ${{ github.event.workflow_run.head_branch }}
+      WORKFLOW_RUN_HEAD_SHA: ${{ github.event.workflow_run.head_sha }}
     steps:
       - name: Checkout code
         uses: actions/checkout@v4
@@ -26,6 +33,14 @@ jobs:
           event_name="${GITHUB_EVENT_NAME:-}"
           sha="${GITHUB_SHA:-}"
 
+          if [ -z "$ref_name" ] && [ -n "${WORKFLOW_RUN_HEAD_BRANCH:-}" ]; then
+            ref_name="${WORKFLOW_RUN_HEAD_BRANCH}"
+          fi
+
+          if [ -z "$sha" ] && [ -n "${WORKFLOW_RUN_HEAD_SHA:-}" ]; then
+            sha="${WORKFLOW_RUN_HEAD_SHA}"
+          fi
+
           if [ "$ref_name" = "${DEFAULT_BRANCH:-main}" ]; then
             echo "on_default=true" >> "$GITHUB_OUTPUT"
           else

.gitea/workflows/deploy.yml

@@ -1,11 +1,16 @@
 name: Deploy to Server
 on:
-  push:
+  workflow_run:
+    workflows:
+      - Build and Push Docker Image
     branches:
       - main
+    types:
+      - completed
 
 jobs:
   deploy:
+    if: ${{ github.event.workflow_run.conclusion == 'success' }}
     runs-on: ubuntu-latest
     env:
       DEFAULT_BRANCH: main
@@ -14,6 +19,8 @@ jobs:
       REGISTRY_URL: ${{ secrets.REGISTRY_URL }}
       REGISTRY_USERNAME: ${{ secrets.REGISTRY_USERNAME }}
       REGISTRY_PASSWORD: ${{ secrets.REGISTRY_PASSWORD }}
+      WORKFLOW_RUN_HEAD_BRANCH: ${{ github.event.workflow_run.head_branch }}
+      WORKFLOW_RUN_HEAD_SHA: ${{ github.event.workflow_run.head_sha }}
     steps:
       - name: SSH and deploy
         uses: appleboy/ssh-action@master
@@ -22,7 +29,15 @@ jobs:
           username: ${{ secrets.SSH_USERNAME }}
           key: ${{ secrets.SSH_PRIVATE_KEY }}
           script: |
-            docker pull ${{ env.REGISTRY_URL }}/${{ env.REGISTRY_ORG }}/${{ env.REGISTRY_IMAGE_NAME }}:latest
+            IMAGE_SHA="${{ env.WORKFLOW_RUN_HEAD_SHA }}"
+            IMAGE_PATH="${{ env.REGISTRY_URL }}/${{ env.REGISTRY_ORG }}/${{ env.REGISTRY_IMAGE_NAME }}"
+
+            if [ -z "$IMAGE_SHA" ]; then
+              echo "Missing workflow run head SHA; aborting deployment." >&2
+              exit 1
+            fi
+
+            docker pull "$IMAGE_PATH:$IMAGE_SHA"
             docker stop calminer || true
             docker rm calminer || true
             docker run -d --name calminer -p 8000:8000 \
@@ -33,4 +48,4 @@ jobs:
               -e DATABASE_PASSWORD=${{ secrets.DATABASE_PASSWORD }} \
               -e DATABASE_NAME=${{ secrets.DATABASE_NAME }} \
               -e DATABASE_SCHEMA=${{ secrets.DATABASE_SCHEMA }} \
-              ${{ secrets.REGISTRY_URL }}/${{ secrets.REGISTRY_USERNAME }}/calminer:latest
+              "$IMAGE_PATH:$IMAGE_SHA"

.gitea/workflows/test.yml

@@ -2,7 +2,13 @@ name: Run Tests
 on: [push]
 
 jobs:
-  test:
+  tests:
+    name: ${{ matrix.target }} tests
+    runs-on: ubuntu-latest
+    strategy:
+      fail-fast: false
+      matrix:
+        target: [unit, e2e]
     services:
       postgres:
         image: postgres:16-alpine
@@ -10,14 +16,11 @@ jobs:
           POSTGRES_DB: calminer_ci
           POSTGRES_USER: calminer
           POSTGRES_PASSWORD: secret
-        ports:
-          - 5432:5432
         options: >-
           --health-cmd "pg_isready -U calminer -d calminer_ci"
           --health-interval 10s
           --health-timeout 5s
           --health-retries 10
-    runs-on: ubuntu-latest
     steps:
       - name: Checkout code
         uses: actions/checkout@v4
@@ -54,6 +57,7 @@ jobs:
           pip install -r requirements.txt
           pip install -r requirements-test.txt
       - name: Install Playwright browsers
+        if: ${{ matrix.target == 'e2e' }}
         run: |
           python -m playwright install --with-deps
       - name: Wait for database service
@@ -122,4 +126,9 @@ jobs:
         env:
           DATABASE_URL: postgresql+psycopg2://calminer:secret@postgres:5432/calminer_ci
           DATABASE_SCHEMA: public
-        run: pytest
+        run: |
+          if [ "${{ matrix.target }}" = "unit" ]; then
+            pytest tests/unit
+          else
+            pytest tests/e2e
+          fi