fix: resume interrupted jobs after startup (not only at boot) (#297)

The previous middleware logic gated recovery behind a
once-per-process flag. After the first request handled the boot-time
recovery check, the resume codepath never fired again — even when
new interruptions appeared later in the process lifetime.

Symptom: a sync that started after server boot, crashed mid-flight
(deadlock retry hitting maxRetries, network blip, container
restart of an upstream service, etc.) and never reached the resume
codepath would sit at `inProgress=true, lastCheckpoint=never`
forever. The periodic detector kept finding the stuck row and
logging `Found 1 interrupted jobs:` on every poll (driven by the
health endpoint via `hasJobsNeedingRecovery`), but the resumer
(`resumeInterruptedJob`) was only invoked from `initializeRecovery`
which the middleware never re-called.

Fix: replace the one-shot gate with an in-flight latch
(`recoveryInFlight`) that's released in a `finally` block. Throttling
of actual recovery work is delegated to the existing 5-minute
`skipIfRecentAttempt` check inside `initializeRecovery()`, which is
the right place for it. `recoveryInitialized` is kept and only used
to control whether the "first run" log lines fire.

Secondary fix: `findInterruptedJobs` previously logged
`Found N interrupted jobs:` unconditionally on every call, including
from passive polls in `hasJobsNeedingRecovery` (which the health
endpoint and middleware probe call frequently). That produced one
log line per poll per stuck job for as long as the job stayed stuck.
Make logging opt-in via a `logFound` parameter, default off; the
active recovery cycle in `initializeRecovery()` opts in so the
operator-facing log still surfaces which jobs are being worked on.

Related: #268 (partially addressed). The PR #280 / v3.15.7 fix was
about a JS scoping bug that made the *initial* migrate call's
catch path crash before transitioning the repo to `failed`. That
was one cause of stuck `mirroring` state; this PR addresses the
follow-on issue that even when a job *is* correctly detectable as
interrupted, the post-startup recovery path never re-engages.

Adds `orchestrator-resume-after-startup.test.ts` using the
structural-source test pattern from
`gitea-mirror-failure-recovery.test.ts` so the four guarantees
(no static gate; in-flight latch released in finally; logging
opt-in; active path opts in) are enforced without heavy mocks.

.env.example

@@ -9,6 +9,8 @@
 NODE_ENV=production
 HOST=0.0.0.0
 PORT=4321
+# Optional application base path (use "/" for root, or "/mirror" for subpath deployments)
+BASE_URL=/
 
 # Database Configuration
 # For self-hosted, SQLite is used by default
@@ -18,9 +20,40 @@ DATABASE_URL=sqlite://data/gitea-mirror.db
 # Generate with: openssl rand -base64 32
 BETTER_AUTH_SECRET=change-this-to-a-secure-random-string-in-production
 BETTER_AUTH_URL=http://localhost:4321
-# PUBLIC_BETTER_AUTH_URL=https://your-domain.com  # Optional: Set this if accessing from different origins (e.g., IP and domain)
 # ENCRYPTION_SECRET=optional-encryption-key-for-token-encryption # Generate with: openssl rand -base64 48
 
+# ===========================================
+# REVERSE PROXY CONFIGURATION
+# ===========================================
+# REQUIRED when accessing Gitea Mirror through a reverse proxy (Nginx, Caddy, Traefik, etc.).
+# Without these, sign-in will fail with "invalid origin" errors and pages may appear blank.
+#
+# Set all three to your external URL, e.g.:
+#   BETTER_AUTH_URL=https://gitea-mirror.example.com
+#   PUBLIC_BETTER_AUTH_URL=https://gitea-mirror.example.com
+#   BETTER_AUTH_TRUSTED_ORIGINS=https://gitea-mirror.example.com
+#
+# If your app is served from a path prefix (e.g. https://git.example.com/mirror), set:
+#   BASE_URL=/mirror
+#   BETTER_AUTH_URL=https://git.example.com
+#   PUBLIC_BETTER_AUTH_URL=https://git.example.com
+#   BETTER_AUTH_TRUSTED_ORIGINS=https://git.example.com
+#
+# BETTER_AUTH_URL            - Used server-side for auth callbacks and redirects
+# PUBLIC_BETTER_AUTH_URL     - Used client-side (browser) for auth API calls
+# BETTER_AUTH_TRUSTED_ORIGINS - Comma-separated list of origins allowed to make auth requests
+#                               (e.g. https://gitea-mirror.example.com,https://alt.example.com)
+PUBLIC_BETTER_AUTH_URL=http://localhost:4321
+# BETTER_AUTH_TRUSTED_ORIGINS=
+
+# ===========================================
+# HTTPS / TLS (Optional)
+# ===========================================
+# Set BOTH to have the server terminate TLS directly (no reverse proxy needed).
+# Leave unset when TLS is handled upstream by Nginx/Traefik/Caddy.
+# SERVER_CERT_PATH=/etc/ssl/gitea-mirror/cert.pem
+# SERVER_KEY_PATH=/etc/ssl/gitea-mirror/key.pem
+
 # ===========================================
 # DOCKER CONFIGURATION (Optional)
 # ===========================================
@@ -40,12 +73,19 @@ DOCKER_TAG=latest
 # GITHUB_TOKEN=your-github-personal-access-token
 # GITHUB_TYPE=personal  # Options: personal, organization
 
+# GitHub Enterprise (GHES / GHEC with data residency)
+# Leave unset for standard github.com. Examples:
+#   GHES (self-hosted):       https://ghe.example.com/api/v3
+#   GHEC data residency:      https://api.TENANT.ghe.com
+# GH_API_URL=https://ghe.example.com/api/v3
+
 # Repository Selection
 # PRIVATE_REPOSITORIES=false
 # PUBLIC_REPOSITORIES=true
 # INCLUDE_ARCHIVED=false
 # SKIP_FORKS=false
 # MIRROR_STARRED=false
+# MIRROR_STARRED_LISTS=homelab,dottools  # Optional: comma-separated star list names; empty = all starred repos
 # STARRED_REPOS_ORG=starred  # Organization name for starred repos
 # STARRED_REPOS_MODE=dedicated-org  # dedicated-org | preserve-owner
 

.github/workflows/README.md

@@ -43,6 +43,9 @@ This workflow builds Docker images on pushes and pull requests, and pushes to Gi
 - Skips registry push for fork PRs (avoids package write permission failures)
 - Uses build caching to speed up builds
 - Creates multiple tags for each image (latest, semver, sha)
+- Auto-syncs `package.json` version from `v*` tags during release builds
+- Validates release tags use semver format before building
+- After tag builds succeed, writes the same version back to `main/package.json`
 
 ### Docker Security Scan (`docker-scan.yml`)
 

.github/workflows/astro-build-test.yml

@@ -6,11 +6,15 @@ on:
     paths-ignore:
       - 'README.md'
       - 'docs/**'
+      - 'www/**'
+      - 'helm/**'
   pull_request:
     branches: [ '*' ]
     paths-ignore:
       - 'README.md'
       - 'docs/**'
+      - 'www/**'
+      - 'helm/**'
 
 permissions:
   contents: read
@@ -20,6 +24,7 @@ jobs:
   build-and-test:
     name: Build and Test Astro Project
     runs-on: ubuntu-latest
+    timeout-minutes: 25
 
     steps:
       - name: Checkout repository
@@ -28,7 +33,7 @@ jobs:
       - name: Setup Bun
         uses: oven-sh/setup-bun@v1
         with:
-          bun-version: '1.2.16'
+          bun-version: '1.3.13'
 
       - name: Check lockfile and install dependencies
         run: |
@@ -43,6 +48,12 @@ jobs:
 
       - name: Run tests
         run: bun test --coverage
+      
+      - name: Check Drizzle migrations
+        run: bun run db:check
+
+      - name: Validate migrations (SQLite lint + upgrade path)
+        run: bun test:migrations
 
       - name: Build Astro project
         run: bunx --bun astro build

.github/workflows/docker-build.yml

@@ -36,6 +36,7 @@ env:
 jobs:
   docker:
     runs-on: ubuntu-latest
+    timeout-minutes: 25
 
     permissions:
       contents: write
@@ -50,13 +51,13 @@ jobs:
           ref: ${{ env.SHA }}
 
       - name: Set up Docker Buildx
-        uses: docker/setup-buildx-action@v3
+        uses: docker/setup-buildx-action@8d2750c68a42422c14e847fe6c8ac0403b4cbd6f # v3.12.0
         with:
           driver-opts: network=host
 
       - name: Log into registry
         if: github.event_name != 'pull_request' || github.event.pull_request.head.repo.full_name == github.repository
-        uses: docker/login-action@v3
+        uses: docker/login-action@c94ce9fb468520275223c153574b00df6fe4bcc9 # v3.7.0
         with:
           registry: ${{ env.REGISTRY }}
           username: ${{ github.actor }}
@@ -65,7 +66,7 @@ jobs:
       # Login to Docker Hub for Docker Scout (optional - provides better vulnerability data)
       # Add DOCKERHUB_USERNAME and DOCKERHUB_TOKEN secrets to enable this
       - name: Log into Docker Hub
-        uses: docker/login-action@v3
+        uses: docker/login-action@c94ce9fb468520275223c153574b00df6fe4bcc9 # v3.7.0
         continue-on-error: true
         with:
           username: ${{ secrets.DOCKERHUB_USERNAME }}
@@ -76,17 +77,38 @@ jobs:
         id: tag_version
         run: |
           if [[ $GITHUB_REF == refs/tags/v* ]]; then
-            echo "VERSION=${GITHUB_REF#refs/tags/}" >> $GITHUB_OUTPUT
-            echo "Using version tag: ${GITHUB_REF#refs/tags/}"
+            TAG_VERSION="${GITHUB_REF#refs/tags/}"
+            if [[ ! "$TAG_VERSION" =~ ^v[0-9]+\.[0-9]+\.[0-9]+([.-][0-9A-Za-z.-]+)?(\+[0-9A-Za-z.-]+)?$ ]]; then
+              echo "::error::Release tag '${TAG_VERSION}' is invalid. Expected semver tag format like v1.2.3 or v1.2.3-rc.1"
+              exit 1
+            fi
+            APP_VERSION="${TAG_VERSION#v}"
+            echo "VERSION=${TAG_VERSION}" >> $GITHUB_OUTPUT
+            echo "APP_VERSION=${APP_VERSION}" >> $GITHUB_OUTPUT
+            echo "Using version tag: ${TAG_VERSION}"
           else
             echo "VERSION=latest" >> $GITHUB_OUTPUT
+            echo "APP_VERSION=dev" >> $GITHUB_OUTPUT
             echo "No version tag, using 'latest'"
           fi
 
+      # Keep version files aligned automatically for tag-based releases
+      - name: Sync app version from release tag
+        if: startsWith(github.ref, 'refs/tags/v')
+        run: |
+          VERSION="${{ steps.tag_version.outputs.APP_VERSION }}"
+          echo "Syncing package.json version to ${VERSION}"
+
+          jq --arg version "${VERSION}" '.version = $version' package.json > package.json.tmp
+          mv package.json.tmp package.json
+
+          echo "Version sync diff (package.json):"
+          git --no-pager diff -- package.json
+
       # Extract metadata for Docker
       - name: Extract Docker metadata
         id: meta
-        uses: docker/metadata-action@v5
+        uses: docker/metadata-action@c299e40c65443455700f0fdfc63efafe5b349051 # v5.10.0
         with:
           images: ${{ env.REGISTRY }}/${{ env.IMAGE }}
           labels: |
@@ -102,7 +124,7 @@ jobs:
       # Build and push Docker image
       - name: Build and push Docker image
         id: build-and-push
-        uses: docker/build-push-action@v6
+        uses: docker/build-push-action@10e90e3645eae34f1e60eeb005ba3a3d33f178e8 # v6.19.2
         with:
           context: .
           platforms: linux/amd64,linux/arm64
@@ -117,7 +139,7 @@ jobs:
       # Load image locally for security scanning (PRs only)
       - name: Load image for scanning
         if: github.event_name == 'pull_request'
-        uses: docker/build-push-action@v6
+        uses: docker/build-push-action@10e90e3645eae34f1e60eeb005ba3a3d33f178e8 # v6.19.2
         with:
           context: .
           platforms: linux/amd64
@@ -190,7 +212,7 @@ jobs:
 
       # Docker Scout comprehensive security analysis
       - name: Docker Scout - Vulnerability Analysis & Recommendations
-        uses: docker/scout-action@v1
+        uses: docker/scout-action@bacf462e8d090c09660de30a6ccc718035f961e3 # v1.20.4
         if: github.event_name != 'pull_request'
         with:
           command: cves,recommendations
@@ -204,7 +226,7 @@ jobs:
 
       # Docker Scout for Pull Requests (using local image)
       - name: Docker Scout - Vulnerability Analysis (PR)
-        uses: docker/scout-action@v1
+        uses: docker/scout-action@bacf462e8d090c09660de30a6ccc718035f961e3 # v1.20.4
         if: github.event_name == 'pull_request'
         with:
           command: cves,recommendations
@@ -218,7 +240,7 @@ jobs:
 
       # Compare to latest for PRs and pushes
       - name: Docker Scout - Compare to Latest
-        uses: docker/scout-action@v1
+        uses: docker/scout-action@bacf462e8d090c09660de30a6ccc718035f961e3 # v1.20.4
         if: github.event_name == 'pull_request'
         with:
           command: compare
@@ -231,8 +253,49 @@ jobs:
 
       # Upload security scan results to GitHub Security tab
       - name: Upload Docker Scout scan results to GitHub Security tab
-        uses: github/codeql-action/upload-sarif@v3
+        uses: github/codeql-action/upload-sarif@v4
         if: always()
         continue-on-error: true
         with:
           sarif_file: scout-results.sarif
+
+  sync-version-main:
+    name: Sync package.json version back to main
+    if: startsWith(github.ref, 'refs/tags/v')
+    runs-on: ubuntu-latest
+    needs: docker
+    permissions:
+      contents: write
+
+    steps:
+      - name: Checkout default branch
+        uses: actions/checkout@v4
+        with:
+          ref: ${{ github.event.repository.default_branch }}
+
+      - name: Update package.json version on main
+        env:
+          TAG_VERSION: ${{ github.ref_name }}
+          TARGET_BRANCH: ${{ github.event.repository.default_branch }}
+        run: |
+          if [[ ! "$TAG_VERSION" =~ ^v[0-9]+\.[0-9]+\.[0-9]+([.-][0-9A-Za-z.-]+)?(\+[0-9A-Za-z.-]+)?$ ]]; then
+            echo "::error::Release tag '${TAG_VERSION}' is invalid. Expected semver tag format like v1.2.3 or v1.2.3-rc.1"
+            exit 1
+          fi
+
+          APP_VERSION="${TAG_VERSION#v}"
+          echo "Syncing ${TARGET_BRANCH}/package.json to ${APP_VERSION}"
+
+          jq --arg version "${APP_VERSION}" '.version = $version' package.json > package.json.tmp
+          mv package.json.tmp package.json
+
+          if git diff --quiet -- package.json; then
+            echo "package.json on ${TARGET_BRANCH} already at ${APP_VERSION}; nothing to commit."
+            exit 0
+          fi
+
+          git config user.name "github-actions[bot]"
+          git config user.email "41898282+github-actions[bot]@users.noreply.github.com"
+          git add package.json
+          git commit -m "chore: sync version to ${APP_VERSION}"
+          git push origin "HEAD:${TARGET_BRANCH}"

.github/workflows/e2e-tests.yml

@@ -0,0 +1,285 @@
+name: E2E Integration Tests
+
+on:
+  push:
+    branches: ["*"]
+    paths-ignore:
+      - "README.md"
+      - "docs/**"
+      - "CHANGELOG.md"
+      - "LICENSE"
+      - "www/**"
+      - "helm/**"
+  pull_request:
+    branches: ["*"]
+    paths-ignore:
+      - "README.md"
+      - "docs/**"
+      - "CHANGELOG.md"
+      - "LICENSE"
+      - "www/**"
+      - "helm/**"
+  workflow_dispatch:
+    inputs:
+      debug_enabled:
+        description: "Enable debug logging"
+        required: false
+        default: "false"
+        type: boolean
+
+permissions:
+  contents: read
+  actions: read
+
+concurrency:
+  group: e2e-${{ github.ref }}
+  cancel-in-progress: true
+
+env:
+  GITEA_PORT: 3333
+  FAKE_GITHUB_PORT: 4580
+  GIT_SERVER_PORT: 4590
+  APP_PORT: 4321
+  BUN_VERSION: "1.3.13"
+
+jobs:
+  e2e-tests:
+    name: E2E Integration Tests
+    runs-on: ubuntu-latest
+    timeout-minutes: 25
+
+    steps:
+      - name: Checkout repository
+        uses: actions/checkout@v4
+
+      - name: Setup Bun
+        uses: oven-sh/setup-bun@v1
+        with:
+          bun-version: ${{ env.BUN_VERSION }}
+
+      - name: Setup Node.js
+        uses: actions/setup-node@v4
+        with:
+          node-version: "22"
+
+      - name: Install dependencies
+        run: |
+          bun install
+          echo "✓ Dependencies installed"
+
+      - name: Install Playwright
+        run: |
+          npx playwright install chromium
+          npx playwright install-deps chromium
+          echo "✓ Playwright ready"
+
+      - name: Create test git repositories
+        run: |
+          echo "Creating bare git repos for E2E testing..."
+          bun run tests/e2e/create-test-repos.ts --output-dir tests/e2e/git-repos
+
+          if [ ! -f tests/e2e/git-repos/manifest.json ]; then
+            echo "ERROR: Test git repos were not created (manifest.json missing)"
+            exit 1
+          fi
+
+          echo "✓ Test repos created:"
+          cat tests/e2e/git-repos/manifest.json | jq -r '.repos[] | "  • \(.owner)/\(.name) — \(.description)"'
+
+      - name: Start Gitea and git-server containers
+        run: |
+          echo "Starting containers via docker compose..."
+          docker compose -f tests/e2e/docker-compose.e2e.yml up -d
+
+          # Wait for git-server
+          echo "Waiting for git HTTP server..."
+          for i in $(seq 1 30); do
+            if curl -sf http://localhost:${{ env.GIT_SERVER_PORT }}/manifest.json > /dev/null 2>&1; then
+              echo "✓ Git HTTP server is ready"
+              break
+            fi
+            if [ $i -eq 30 ]; then
+              echo "ERROR: Git HTTP server did not start"
+              docker compose -f tests/e2e/docker-compose.e2e.yml logs git-server
+              exit 1
+            fi
+            sleep 1
+          done
+
+          # Wait for Gitea
+          echo "Waiting for Gitea to be ready..."
+          for i in $(seq 1 60); do
+            if curl -sf http://localhost:${{ env.GITEA_PORT }}/api/v1/version > /dev/null 2>&1; then
+              version=$(curl -sf http://localhost:${{ env.GITEA_PORT }}/api/v1/version | jq -r '.version // "unknown"')
+              echo "✓ Gitea is ready (version: $version)"
+              break
+            fi
+            if [ $i -eq 60 ]; then
+              echo "ERROR: Gitea did not become healthy within 120s"
+              docker compose -f tests/e2e/docker-compose.e2e.yml logs gitea-e2e --tail=30
+              exit 1
+            fi
+            sleep 2
+          done
+
+      - name: Initialize database
+        run: |
+          bun run manage-db init
+          echo "✓ Database initialized"
+
+      - name: Build application
+        env:
+          GH_API_URL: http://localhost:4580
+          BETTER_AUTH_SECRET: e2e-test-secret
+        run: |
+          bun run build
+          echo "✓ Build complete"
+
+      - name: Start fake GitHub API server
+        run: |
+          # Start with GIT_SERVER_URL pointing to the git-server container name
+          # (Gitea will resolve it via Docker networking)
+          PORT=${{ env.FAKE_GITHUB_PORT }} GIT_SERVER_URL="http://git-server" \
+            npx tsx tests/e2e/fake-github-server.ts &
+          echo $! > /tmp/fake-github.pid
+
+          echo "Waiting for fake GitHub API..."
+          for i in $(seq 1 30); do
+            if curl -sf http://localhost:${{ env.FAKE_GITHUB_PORT }}/___mgmt/health > /dev/null 2>&1; then
+              echo "✓ Fake GitHub API is ready"
+              break
+            fi
+            if [ $i -eq 30 ]; then
+              echo "ERROR: Fake GitHub API did not start"
+              exit 1
+            fi
+            sleep 1
+          done
+
+          # Ensure clone URLs are set for the git-server container
+          curl -sf -X POST http://localhost:${{ env.FAKE_GITHUB_PORT }}/___mgmt/set-clone-url \
+            -H "Content-Type: application/json" \
+            -d '{"url": "http://git-server"}' || true
+          echo "✓ Clone URLs configured for git-server container"
+
+      - name: Start gitea-mirror application
+        env:
+          GH_API_URL: http://localhost:4580
+          BETTER_AUTH_SECRET: e2e-test-secret
+          BETTER_AUTH_URL: http://localhost:4321
+          DATABASE_URL: file:data/gitea-mirror.db
+          HOST: 0.0.0.0
+          PORT: ${{ env.APP_PORT }}
+          NODE_ENV: production
+          PRE_SYNC_BACKUP_ENABLED: "false"
+          ENCRYPTION_SECRET: "e2e-encryption-secret-32char!!"
+        run: |
+          # Re-init DB in case build step cleared it
+          bun run manage-db init 2>/dev/null || true
+
+          bun run start &
+          echo $! > /tmp/app.pid
+
+          echo "Waiting for gitea-mirror app..."
+          for i in $(seq 1 90); do
+            if curl -sf http://localhost:${{ env.APP_PORT }}/api/health > /dev/null 2>&1 || \
+               curl -sf -o /dev/null -w "%{http_code}" http://localhost:${{ env.APP_PORT }}/ 2>/dev/null | grep -q "^[23]"; then
+              echo "✓ gitea-mirror app is ready"
+              break
+            fi
+            if ! kill -0 $(cat /tmp/app.pid) 2>/dev/null; then
+              echo "ERROR: App process died"
+              exit 1
+            fi
+            if [ $i -eq 90 ]; then
+              echo "ERROR: gitea-mirror app did not start within 180s"
+              exit 1
+            fi
+            sleep 2
+          done
+
+      - name: Run E2E tests
+        env:
+          APP_URL: http://localhost:${{ env.APP_PORT }}
+          GITEA_URL: http://localhost:${{ env.GITEA_PORT }}
+          FAKE_GITHUB_URL: http://localhost:${{ env.FAKE_GITHUB_PORT }}
+          GIT_SERVER_URL: http://localhost:${{ env.GIT_SERVER_PORT }}
+          CI: true
+        run: |
+          mkdir -p tests/e2e/test-results
+          npx playwright test \
+            --config tests/e2e/playwright.config.ts \
+            --reporter=github,html
+
+      - name: Diagnostic info on failure
+        if: failure()
+        run: |
+          echo "═══════════════════════════════════════════════════════════"
+          echo " Diagnostic Information"
+          echo "═══════════════════════════════════════════════════════════"
+
+          echo ""
+          echo "── Git server status ──"
+          curl -sf http://localhost:${{ env.GIT_SERVER_PORT }}/manifest.json 2>/dev/null | jq . || echo "(unreachable)"
+
+          echo ""
+          echo "── Gitea status ──"
+          curl -sf http://localhost:${{ env.GITEA_PORT }}/api/v1/version 2>/dev/null || echo "(unreachable)"
+
+          echo ""
+          echo "── Fake GitHub status ──"
+          curl -sf http://localhost:${{ env.FAKE_GITHUB_PORT }}/___mgmt/health 2>/dev/null | jq . || echo "(unreachable)"
+
+          echo ""
+          echo "── App status ──"
+          curl -sf http://localhost:${{ env.APP_PORT }}/api/health 2>/dev/null || echo "(unreachable)"
+
+          echo ""
+          echo "── Docker containers ──"
+          docker compose -f tests/e2e/docker-compose.e2e.yml ps 2>/dev/null || true
+
+          echo ""
+          echo "── Gitea container logs (last 50 lines) ──"
+          docker compose -f tests/e2e/docker-compose.e2e.yml logs gitea-e2e --tail=50 2>/dev/null || echo "(no container)"
+
+          echo ""
+          echo "── Git server logs (last 20 lines) ──"
+          docker compose -f tests/e2e/docker-compose.e2e.yml logs git-server --tail=20 2>/dev/null || echo "(no container)"
+
+          echo ""
+          echo "── Running processes ──"
+          ps aux | grep -E "(fake-github|astro|bun|node)" | grep -v grep || true
+
+      - name: Upload Playwright report
+        uses: actions/upload-artifact@v4
+        if: always()
+        with:
+          name: e2e-playwright-report
+          path: tests/e2e/playwright-report/
+          retention-days: 14
+
+      - name: Upload test results
+        uses: actions/upload-artifact@v4
+        if: always()
+        with:
+          name: e2e-test-results
+          path: tests/e2e/test-results/
+          retention-days: 14
+
+      - name: Cleanup
+        if: always()
+        run: |
+          # Stop background processes
+          if [ -f /tmp/fake-github.pid ]; then
+            kill $(cat /tmp/fake-github.pid) 2>/dev/null || true
+            rm -f /tmp/fake-github.pid
+          fi
+          if [ -f /tmp/app.pid ]; then
+            kill $(cat /tmp/app.pid) 2>/dev/null || true
+            rm -f /tmp/app.pid
+          fi
+
+          # Stop containers
+          docker compose -f tests/e2e/docker-compose.e2e.yml down --volumes --remove-orphans 2>/dev/null || true
+
+          echo "✓ Cleanup complete"

.github/workflows/helm-test.yml

@@ -21,6 +21,7 @@ jobs:
   yamllint:
     name: Lint YAML
     runs-on: ubuntu-latest
+    timeout-minutes: 25
     steps:
       - uses: actions/checkout@v4
       - uses: actions/setup-python@v5
@@ -35,6 +36,7 @@ jobs:
   helm-template:
     name: Helm lint & template
     runs-on: ubuntu-latest
+    timeout-minutes: 25
     steps:
       - uses: actions/checkout@v4
       - name: Setup Helm

.github/workflows/nix-build.yml

@@ -5,41 +5,53 @@ on:
     branches: [main, nix]
     tags:
       - 'v*'
+    paths:
+      - 'flake.nix'
+      - 'flake.lock'
+      - 'bun.nix'
+      - 'bun.lock'
+      - 'package.json'
+      - '.github/workflows/nix-build.yml'
   pull_request:
     branches: [main]
+    paths:
+      - 'flake.nix'
+      - 'flake.lock'
+      - 'bun.nix'
+      - 'bun.lock'
+      - 'package.json'
+      - '.github/workflows/nix-build.yml'
 
 permissions:
   contents: read
 
 jobs:
   check:
-    strategy:
-      matrix:
-        os: [ubuntu-latest, macos-latest]
-    runs-on: ${{ matrix.os }}
+    runs-on: ubuntu-latest
+    timeout-minutes: 45
+    env:
+      NIX_CONFIG: |
+        accept-flake-config = true
+        access-tokens = github.com=${{ secrets.GITHUB_TOKEN }}
 
     steps:
       - uses: actions/checkout@v4
 
       - name: Install Nix
-        uses: DeterminateSystems/nix-installer-action@main
+        uses: DeterminateSystems/nix-installer-action@ef8a148080ab6020fd15196c2084a2eea5ff2d25 # v22
 
       - name: Setup Nix Cache
-        uses: DeterminateSystems/magic-nix-cache-action@main
+        uses: DeterminateSystems/magic-nix-cache-action@565684385bcd71bad329742eefe8d12f2e765b39 # v13
+
+      - name: Regenerate bun.nix from bun.lock
+        run: nix run --accept-flake-config github:nix-community/bun2nix -- -o bun.nix
 
       - name: Check flake
-        run: nix flake check
+        run: nix flake check --accept-flake-config
 
       - name: Show flake info
-        run: nix flake show
+        run: nix flake show --accept-flake-config
 
-      - name: Evaluate package
-        run: |
-          # Evaluate the derivation without building (validates the Nix expression)
-          nix eval .#packages.$(nix eval --impure --expr 'builtins.currentSystem').default.name
-          echo "Flake evaluation successful"
-
-      # Note: Full build requires network access for bun install.
-      # Nix sandboxed builds block network access.
-      # To build locally: nix build --option sandbox false
-      # Or use: nix develop && bun install && bun run build
+      - name: Build package
+        if: github.ref == 'refs/heads/main' || startsWith(github.ref, 'refs/tags/v')
+        run: nix build --print-build-logs --accept-flake-config

.gitignore

@@ -37,3 +37,18 @@ result
 result-*
 .direnv/
 
+# E2E test artifacts
+tests/e2e/test-results/
+tests/e2e/playwright-report/
+tests/e2e/.auth/
+tests/e2e/e2e-storage-state.json
+tests/e2e/.fake-github.pid
+tests/e2e/.app.pid
+tests/e2e/git-repos/
+
+# Playwright
+/test-results/
+/playwright-report/
+/blob-report/
+/playwright/.cache/
+/playwright/.auth/

DISTRIBUTION_SUMMARY.md

@@ -1,169 +0,0 @@
-# Nix Distribution - Ready to Use!
-
-## Current Status: WORKS NOW
-
-Your Nix package is **already distributable**! Users can run it directly from GitHub without any additional setup on your end.
-
-## How Users Will Use It
-
-### Simple: Just Run From GitHub
-
-```bash
-nix run --extra-experimental-features 'nix-command flakes' github:RayLabsHQ/gitea-mirror
-```
-
-That's it! No releases, no CI, no infrastructure needed. It works right now.
-
----
-
-## What Happens When They Run This?
-
-1. **Nix fetches** your repo from GitHub
-2. **Nix reads** `flake.nix` and `flake.lock`
-3. **Nix builds** the package on their machine
-4. **Nix runs** the application
-5. **Result cached** in `/nix/store` for reuse
-
----
-
-## Do You Need CI or Releases?
-
-### For Basic Usage: **NO**
-Users can already use it from GitHub. No CI or releases required.
-
-### For CI Validation: **Already Set Up**
-GitHub Actions validates builds on every push with Magic Nix Cache (free, no setup).
-
----
-
-## Next Steps (Optional)
-
-### Option 1: Release Versioning (2 minutes)
-
-**Why:** Users can pin to specific versions
-
-**How:**
-```bash
-# When ready to release
-git tag v3.8.11
-git push origin v3.8.11
-
-# Users can then pin to this version
-nix run github:RayLabsHQ/gitea-mirror/v3.8.11
-```
-
-No additional CI needed - tags work automatically with flakes!
-
-### Option 2: Submit to nixpkgs (Long Term)
-
-**Why:** Maximum discoverability and trust
-
-**When:** After package is stable and well-tested
-
-**How:** Submit PR to https://github.com/NixOS/nixpkgs
-
----
-
-## Files Created
-
-### Essential (Already Working)
-- `flake.nix` - Package definition
-- `flake.lock` - Dependency lock file
-- `.envrc` - direnv integration
-
-### Documentation
-- `NIX.md` - Quick reference for users
-- `docs/NIX_DEPLOYMENT.md` - Complete deployment guide
-- `docs/NIX_DISTRIBUTION.md` - Distribution guide for you (maintainer)
-- `README.md` - Updated with Nix instructions
-
-### CI (Already Set Up)
-- `.github/workflows/nix-build.yml` - Builds and validates on Linux + macOS
-
-### Updated
-- `.gitignore` - Added Nix artifacts
-
----
-
-## Comparison: Your Distribution Options
-
-| Setup | Time | User Experience | What You Need |
-|-------|------|----------------|---------------|
-| **Direct GitHub** | 0 min | Slow (build from source) | Nothing! Works now |
-| **+ Git Tags** | 2 min | Versionable | Just push tags |
-| **+ nixpkgs** | Hours | Official/Trusted | PR review process |
-
-**Recommendation:** Direct GitHub works now. Add git tags for versioning. Consider nixpkgs submission once stable.
-
----
-
-## Testing Your Distribution
-
-You can test it right now:
-
-```bash
-# Test direct GitHub usage
-nix run --extra-experimental-features 'nix-command flakes' github:RayLabsHQ/gitea-mirror
-
-# Test with specific commit
-nix run github:RayLabsHQ/gitea-mirror/$(git rev-parse HEAD)
-
-# Validate flake
-nix flake check
-```
-
----
-
-## User Documentation Locations
-
-Users will find instructions in:
-1. **README.md** - Installation section (already updated)
-2. **NIX.md** - Quick reference
-3. **docs/NIX_DEPLOYMENT.md** - Detailed guide
-
-All docs include the correct commands with experimental features flags.
-
----
-
-## When to Release New Versions
-
-### For Git Tag Releases:
-```bash
-# 1. Update version in package.json
-vim package.json
-
-# 2. Update version in flake.nix (line 17)
-vim flake.nix  # version = "3.8.12";
-
-# 3. Commit and tag
-git add package.json flake.nix
-git commit -m "chore: bump version to v3.8.12"
-git tag v3.8.12
-git push origin main
-git push origin v3.8.12
-```
-
-Users can then use: `nix run github:RayLabsHQ/gitea-mirror/v3.8.12`
-
-### No Release Needed For:
-- Bug fixes
-- Small changes
-- Continuous updates
-
-Users can always use latest from main: `nix run github:RayLabsHQ/gitea-mirror`
-
----
-
-## Summary
-
-**Ready to distribute RIGHT NOW**
-- Just commit and push your `flake.nix`
-- Users can run directly from GitHub
-- CI validates builds automatically
-
-**Optional: Submit to nixpkgs**
-- Maximum discoverability
-- Official Nix repository
-- Do this once package is stable
-
-See `docs/NIX_DISTRIBUTION.md` for complete details!

Dockerfile

@@ -1,8 +1,8 @@
 # syntax=docker/dockerfile:1.4
 
-FROM oven/bun:1.3.9-debian AS base
+FROM oven/bun:1.3.14-debian@sha256:9dba1a1b43ce28c9d7931bfc4eb00feb63b0114720a0277a8f939ae4dfc9db6f AS base
 WORKDIR /app
-RUN apt-get update && apt-get install -y --no-install-recommends \
+RUN apt-get update && apt-get -y upgrade && apt-get install -y --no-install-recommends \
   python3 make g++ gcc wget sqlite3 openssl ca-certificates \
   && rm -rf /var/lib/apt/lists/*
 
@@ -16,6 +16,7 @@ COPY . .
 RUN bun run build
 RUN mkdir -p dist/scripts && \
   for script in scripts/*.ts; do \
+  if [ "$(basename "$script")" = "runtime-server.ts" ]; then continue; fi; \
   bun build "$script" --target=bun --outfile=dist/scripts/$(basename "${script%.ts}.js"); \
   done
 
@@ -26,21 +27,55 @@ COPY bun.lock* ./
 RUN bun install --production --omit=peer --frozen-lockfile
 
 # ----------------------------
-FROM oven/bun:1.3.9-debian AS runner
-WORKDIR /app
-RUN apt-get update && apt-get install -y --no-install-recommends \
-  wget sqlite3 openssl ca-certificates \
+# Build git-lfs from source with patched Go to resolve Go stdlib CVEs
+FROM debian:trixie-slim AS git-lfs-builder
+RUN apt-get update && apt-get -y upgrade && apt-get install -y --no-install-recommends \
+  wget ca-certificates git make \
   && rm -rf /var/lib/apt/lists/*
+ARG GO_VERSION=1.25.9
+ARG GIT_LFS_VERSION=3.7.1
+RUN ARCH="$(dpkg --print-architecture)" \
+  && wget -qO /tmp/go.tar.gz "https://go.dev/dl/go${GO_VERSION}.linux-${ARCH}.tar.gz" \
+  && tar -C /usr/local -xzf /tmp/go.tar.gz \
+  && rm /tmp/go.tar.gz
+ENV PATH="/usr/local/go/bin:/root/go/bin:${PATH}"
+# Force using our installed Go (not the version in go.mod toolchain directive)
+ENV GOTOOLCHAIN=local
+RUN git clone --branch "v${GIT_LFS_VERSION}" --depth 1 https://github.com/git-lfs/git-lfs.git /tmp/git-lfs \
+  && cd /tmp/git-lfs \
+  && go get golang.org/x/crypto@latest \
+  && go mod tidy \
+  && make \
+  && install -m 755 /tmp/git-lfs/bin/git-lfs /usr/local/bin/git-lfs
+
+# ----------------------------
+FROM oven/bun:1.3.14-debian@sha256:9dba1a1b43ce28c9d7931bfc4eb00feb63b0114720a0277a8f939ae4dfc9db6f AS runner
+WORKDIR /app
+RUN apt-get update && apt-get -y upgrade && apt-get install -y --no-install-recommends \
+  git wget sqlite3 openssl ca-certificates \
+  && rm -rf /var/lib/apt/lists/*
+COPY --from=git-lfs-builder /usr/local/bin/git-lfs /usr/local/bin/git-lfs
+RUN git lfs install
 COPY --from=pruner /app/node_modules ./node_modules
 COPY --from=builder /app/dist ./dist
 COPY --from=builder /app/package.json ./package.json
 COPY --from=builder /app/docker-entrypoint.sh ./docker-entrypoint.sh
+COPY --from=builder /app/scripts/runtime-server.ts ./scripts/runtime-server.ts
 COPY --from=builder /app/drizzle ./drizzle
 
+# Remove build-only packages that are not needed at runtime
+# (esbuild, vite, rollup, tailwind, svgo — all only used during `astro build`)
+RUN rm -rf node_modules/esbuild node_modules/@esbuild \
+  node_modules/rollup node_modules/@rollup \
+  node_modules/vite node_modules/svgo \
+  node_modules/@tailwindcss/vite \
+  node_modules/tailwindcss
+
 ENV NODE_ENV=production
 ENV HOST=0.0.0.0
 ENV PORT=4321
 ENV DATABASE_URL=file:data/gitea-mirror.db
+ENV BASE_URL=/
 
 # Create directories and setup permissions
 RUN mkdir -p /app/certs && \
@@ -58,6 +93,6 @@ VOLUME /app/data
 EXPOSE 4321
 
 HEALTHCHECK --interval=30s --timeout=5s --start-period=5s --retries=3 \
-  CMD wget --no-verbose --tries=1 --spider http://localhost:4321/api/health || exit 1
+  CMD sh -c 'BASE="${BASE_URL:-/}"; if [ "$BASE" = "/" ]; then BASE=""; else BASE="${BASE%/}"; fi; wget --no-verbose --tries=1 --spider "http://localhost:4321${BASE}/api/health" || exit 1'
 
 ENTRYPOINT ["./docker-entrypoint.sh"]

NIX.md

@@ -24,7 +24,7 @@ Secrets auto-generate, database auto-initializes, and the web UI starts at http:
 nix run --extra-experimental-features 'nix-command flakes' github:RayLabsHQ/gitea-mirror
 
 # Pin to specific version
-nix run github:RayLabsHQ/gitea-mirror/v3.8.11
+nix run github:RayLabsHQ/gitea-mirror/vX.Y.Z
 ```
 
 ### 2. Install to Profile

README.md

@@ -1,7 +1,7 @@
 <p align="center">
   <img src=".github/assets/logo.png" alt="Gitea Mirror Logo" width="120" />
   <h1>Gitea Mirror</h1>
-  <p><i>Automatically mirror repositories from GitHub to your self-hosted Gitea instance.</i></p>
+  <p><i>Automatically mirror repositories from GitHub to your self-hosted Gitea/Forgejo instance.</i></p>
   <p align="center">
     <a href="https://github.com/RayLabsHQ/gitea-mirror/releases/latest"><img src="https://img.shields.io/github/v/tag/RayLabsHQ/gitea-mirror?label=release" alt="release"/></a>
     <a href="https://github.com/RayLabsHQ/gitea-mirror/actions/workflows/astro-build-test.yml"><img src="https://img.shields.io/github/actions/workflow/status/RayLabsHQ/gitea-mirror/astro-build-test.yml?branch=main" alt="build"/></a>
@@ -19,7 +19,7 @@ docker compose -f docker-compose.alt.yml up -d
 # Access at http://localhost:4321
 ```
 
-First user signup becomes admin. Configure GitHub and Gitea through the web interface!
+First user signup becomes admin. Configure GitHub and Gitea/Forgejo through the web interface!
 
 <p align="center">
   <img src=".github/assets/dashboard.png" alt="Dashboard" width="600" />
@@ -28,7 +28,8 @@ First user signup becomes admin. Configure GitHub and Gitea through the web inte
 
 ## ✨ Features
 
-- 🔁 Mirror public, private, and starred GitHub repos to Gitea
+- 🔁 Mirror public, private, and starred GitHub repos to Gitea/Forgejo
+- 🏛️ **GitHub Enterprise support** - Works with GHES and GHEC with data residency via `GH_API_URL`
 - 🏢 Mirror entire organizations with flexible strategies
 - 🎯 Custom destination control for repos and organizations
 - 📦 **Git LFS support** - Mirror large files with Git LFS
@@ -40,6 +41,7 @@ First user signup becomes admin. Configure GitHub and Gitea through the web inte
 - 🔄 **Auto-discovery** - Automatically import new GitHub repositories (v3.4.0+)
 - 🧹 **Repository cleanup** - Auto-remove repos deleted from GitHub (v3.4.0+)
 - 🎯 **Proper mirror intervals** - Respects configured sync intervals (v3.4.0+)
+- 🛡️ **[Force-push protection](docs/FORCE_PUSH_PROTECTION.md)** - Smart detection with backup-on-demand or block-and-approve modes (Beta)
 - 🗑️ Automatic database cleanup with configurable retention
 - 🐳 Dockerized with multi-arch support (AMD64/ARM64)
 
@@ -112,7 +114,7 @@ docker compose up -d
 #### Using Pre-built Image Directly
 
 ```bash
-docker pull ghcr.io/raylabshq/gitea-mirror:v3.1.1
+docker pull ghcr.io/raylabshq/gitea-mirror:latest
 ```
 
 ### Configuration Options
@@ -198,12 +200,12 @@ bun run dev
 1. **First Time Setup**
    - Navigate to http://localhost:4321
    - Create admin account (first user signup)
-   - Configure GitHub and Gitea connections
+   - Configure GitHub and Gitea/Forgejo connections
 
 2. **Mirror Strategies**
    - **Preserve Structure**: Maintains GitHub organization structure
-   - **Single Organization**: All repos go to one Gitea organization
-   - **Flat User**: All repos under your Gitea user account
+   - **Single Organization**: All repos go to one Gitea/Forgejo organization
+   - **Flat User**: All repos under your Gitea/Forgejo user account
    - **Mixed Mode**: Personal repos in one org, organization repos preserve structure
 
 3. **Customization**
@@ -216,13 +218,13 @@ bun run dev
 ### Git LFS (Large File Storage)
 Mirror Git LFS objects along with your repositories:
 - Enable "Mirror LFS" option in Settings → Mirror Options
-- Requires Gitea server with LFS enabled (`LFS_START_SERVER = true`)
+- Requires Gitea/Forgejo server with LFS enabled (`LFS_START_SERVER = true`)
 - Requires Git v2.1.2+ on the server
 
 ### Metadata Mirroring
-Transfer complete repository metadata from GitHub to Gitea:
+Transfer complete repository metadata from GitHub to Gitea/Forgejo:
 - **Issues** - Mirror all issues with comments and labels
-- **Pull Requests** - Transfer PR discussions to Gitea
+- **Pull Requests** - Transfer PR discussions to Gitea/Forgejo
 - **Labels** - Preserve repository labels
 - **Milestones** - Keep project milestones
 - **Wiki** - Mirror wiki content
@@ -242,7 +244,7 @@ Gitea Mirror provides powerful automatic synchronization features:
 #### Features (v3.4.0+)
 - **Auto-discovery**: Automatically discovers and imports new GitHub repositories
 - **Repository cleanup**: Removes repositories that no longer exist in GitHub
-- **Proper intervals**: Mirrors respect your configured sync intervals (not Gitea's default 24h)
+- **Proper intervals**: Mirrors respect your configured sync intervals (not Gitea/Forgejo's default 24h)
 - **Smart scheduling**: Only syncs repositories that need updating
 - **Auto-start on boot** (v3.5.3+): Automatically imports and mirrors all repositories when `SCHEDULE_ENABLED=true` or `GITEA_MIRROR_INTERVAL` is set - no manual clicks required!
 
@@ -253,7 +255,7 @@ Navigate to the Configuration page and enable "Automatic Syncing" with your pref
 
 **🚀 Set it and forget it!** With these environment variables, Gitea Mirror will automatically:
 1. **Import** all your GitHub repositories on startup (no manual import needed!)
-2. **Mirror** them to Gitea immediately  
+2. **Mirror** them to Gitea/Forgejo immediately  
 3. **Keep them synchronized** based on your interval
 4. **Auto-discover** new repos you create/star on GitHub
 5. **Clean up** repos you delete from GitHub
@@ -283,23 +285,52 @@ CLEANUP_DRY_RUN=false                 # Set to true to test without changes
 - **Auto-Start**: When `SCHEDULE_ENABLED=true` or `GITEA_MIRROR_INTERVAL` is set, the service automatically imports all GitHub repositories and mirrors them on startup. No manual "Import" or "Mirror" button clicks required!
 - The scheduler checks every minute for tasks to run. The `GITEA_MIRROR_INTERVAL` determines how often each repository is actually synced. For example, with `8h`, each repo syncs every 8 hours from its last successful sync.
 - **Large repo bootstrap**: For first-time mirroring of large repositories (especially with metadata/LFS), avoid very short intervals (for example `5m`). Start with a longer interval (`1h` to `8h`) or temporarily disable scheduling during the initial import/mirror run, then enable your regular interval after the first pass completes.
-- **Why this matters**: If your Gitea instance takes a long time to complete migrations/imports, aggressive schedules can cause repeated retries and duplicate-looking mirror attempts.
+- **Why this matters**: If your Gitea/Forgejo instance takes a long time to complete migrations/imports, aggressive schedules can cause repeated retries and duplicate-looking mirror attempts.
 
 **🛡️ Backup Protection Features**:
 - **No Accidental Deletions**: Repository cleanup is automatically skipped if GitHub is inaccessible (account deleted, banned, or API errors)
 - **Archive Never Deletes Data**: The `archive` action preserves all repository data:
-  - Regular repositories: Made read-only using Gitea's archive feature
-  - Mirror repositories: Renamed with `archived-` prefix (Gitea API limitation prevents archiving mirrors)
+  - Regular repositories: Made read-only using Gitea/Forgejo's archive feature
+  - Mirror repositories: Renamed with `archived-` prefix (Gitea/Forgejo API limitation prevents archiving mirrors)
   - Failed operations: Repository remains fully accessible even if marking as archived fails
-- **Manual Sync on Demand**: Archived mirrors stay in Gitea with automatic syncs disabled; trigger `Manual Sync` from the Repositories page whenever you need fresh data.
-- **The Whole Point of Backups**: Your Gitea mirrors are preserved even when GitHub sources disappear - that's why you have backups!
+- **Manual Sync on Demand**: Archived mirrors stay in Gitea/Forgejo with automatic syncs disabled; trigger `Manual Sync` from the Repositories page whenever you need fresh data.
+- **The Whole Point of Backups**: Your Gitea/Forgejo mirrors are preserved even when GitHub sources disappear - that's why you have backups!
 - **Strongly Recommended**: Always use `CLEANUP_ORPHANED_REPO_ACTION=archive` (default) instead of `delete`
 
+### GitHub Enterprise (GHES / GHEC with Data Residency)
+
+Gitea Mirror works with non-`github.com` GitHub deployments. Point the client at your Enterprise API via the `GH_API_URL` environment variable:
+
+```bash
+# GitHub Enterprise Server (self-hosted)
+GH_API_URL=https://ghe.example.com/api/v3
+
+# GitHub Enterprise Cloud with data residency
+GH_API_URL=https://api.TENANT.ghe.com
+```
+
+Standard GitHub Enterprise Cloud on `github.com` needs no override. Use a token issued by the target Enterprise instance for `GITHUB_TOKEN`.
+
 ## Troubleshooting
 
 ### Reverse Proxy Configuration
 
-If using a reverse proxy (e.g., nginx proxy manager) and experiencing issues with JavaScript files not loading properly, try enabling HTTP/2 support in your proxy configuration. While not required by the application, some proxy configurations may have better compatibility with HTTP/2 enabled. See [issue #43](https://github.com/RayLabsHQ/gitea-mirror/issues/43) for reference.
+If you run behind a reverse proxy on a subpath (for example `https://git.example.com/mirror`), configure:
+
+```bash
+# BASE_URL handles the path prefix — auth URLs stay as origin only
+BASE_URL=/mirror
+BETTER_AUTH_URL=https://git.example.com
+PUBLIC_BETTER_AUTH_URL=https://git.example.com
+BETTER_AUTH_TRUSTED_ORIGINS=https://git.example.com
+# → Auth endpoints resolve to: https://git.example.com/mirror/api/auth/*
+```
+
+Notes:
+- `BASE_URL` sets the application path prefix.
+- `BETTER_AUTH_URL` and `PUBLIC_BETTER_AUTH_URL` should be **origin only** (e.g. `https://git.example.com`). Do not include the base path — it is applied automatically from `BASE_URL`. Any path accidentally included is stripped.
+- `BETTER_AUTH_TRUSTED_ORIGINS` should also contain origins only (no path).
+- `BASE_URL` is runtime configuration, so prebuilt registry images can be reused across different subpaths.
 
 ### Mirror Token Rotation (GitHub Token Changed)
 
@@ -308,7 +339,7 @@ For existing pull-mirror repositories, changing the GitHub token in Gitea Mirror
 If sync logs show authentication failures (for example `terminal prompts disabled`), do one of the following:
 
 1. In Gitea/Forgejo, open repository **Settings → Mirror Settings** and update the mirror authorization password/token.
-2. Or delete and re-mirror the repository from Gitea Mirror so it is recreated with current credentials.
+2. Or delete and re-mirror the repository so it is recreated with current credentials.
 
 ### Re-sync Metadata After Changing Mirror Options
 
@@ -333,7 +364,7 @@ If your Gitea/Forgejo server has `mirror.MIN_INTERVAL` set to a higher value (fo
 To avoid this:
 
 1. Set Gitea Mirror interval to a value greater than or equal to your server `MIN_INTERVAL`.
-2. Do not rely on manual per-repository mirror interval edits in Gitea/Forgejo, because Gitea Mirror will overwrite them on sync.
+2. Do not rely on manual per-repository mirror interval edits in Gitea/Forgejo, as they will be overwritten on sync.
 
 ## Development
 
@@ -355,13 +386,13 @@ bun run build
 
 - **Frontend**: Astro, React, Shadcn UI, Tailwind CSS v4
 - **Backend**: Bun runtime, SQLite, Drizzle ORM
-- **APIs**: GitHub (Octokit), Gitea REST API
+- **APIs**: GitHub (Octokit), Gitea/Forgejo REST API
 - **Auth**: Better Auth with session-based authentication
 
 ## Security
 
 ### Token Encryption
-- All GitHub and Gitea API tokens are encrypted at rest using AES-256-GCM
+- All GitHub and Gitea/Forgejo API tokens are encrypted at rest using AES-256-GCM
 - Encryption is automatic and transparent to users
 - Set `ENCRYPTION_SECRET` environment variable for production deployments
 - Falls back to `BETTER_AUTH_SECRET` if not set
@@ -455,13 +486,13 @@ Gitea Mirror can also act as an OIDC provider for other applications. Register O
 ## Known Limitations
 
 ### Pull Request Mirroring Implementation
-Pull requests **cannot be created as actual PRs** in Gitea due to API limitations. Instead, they are mirrored as **enriched issues** with comprehensive metadata.
+Pull requests **cannot be created as actual PRs** in Gitea/Forgejo due to API limitations. Instead, they are mirrored as **enriched issues** with comprehensive metadata.
 
 **Why real PR mirroring isn't possible:**
-- Gitea's API doesn't support creating pull requests from external sources
+- Gitea/Forgejo's API doesn't support creating pull requests from external sources
 - Real PRs require actual Git branches with commits to exist in the repository
 - Would require complex branch synchronization and commit replication
-- The mirror relationship is one-way (GitHub → Gitea) for repository content
+- The mirror relationship is one-way (GitHub → Gitea/Forgejo) for repository content
 
 **How we handle Pull Requests:**
 PRs are mirrored as issues with rich metadata including:
@@ -475,7 +506,7 @@ PRs are mirrored as issues with rich metadata including:
 - 🔀 Base and head branch information
 - ✅ Merge status tracking
 
-This approach preserves all important PR information while working within Gitea's API constraints. The PRs appear in Gitea's issue tracker with clear visual distinction and comprehensive details.
+This approach preserves all important PR information while working within Gitea/Forgejo's API constraints. The PRs appear in the issue tracker with clear visual distinction and comprehensive details.
 
 ## Contributing
 
@@ -483,7 +514,7 @@ Contributions are welcome! Please read our [Contributing Guidelines](CONTRIBUTIN
 
 ## License
 
-GNU General Public License v3.0 - see [LICENSE](LICENSE) file for details.
+GNU Affero General Public License v3.0 (AGPL-3.0) - see [LICENSE](LICENSE) file for details.
 
 ## Star History
 
@@ -498,7 +529,8 @@ GNU General Public License v3.0 - see [LICENSE](LICENSE) file for details.
 ## Support
 
 - 📖 [Documentation](https://github.com/RayLabsHQ/gitea-mirror/tree/main/docs)
-- 🔐 [Custom CA Certificates](docs/CA_CERTIFICATES.md)
+- 🔐 [Environment Variables](docs/ENVIRONMENT_VARIABLES.md)
+- 🛡️ [Force-Push Protection](docs/FORCE_PUSH_PROTECTION.md)
 - 🐛 [Report Issues](https://github.com/RayLabsHQ/gitea-mirror/issues)
 - 💬 [Discussions](https://github.com/RayLabsHQ/gitea-mirror/discussions)
 - 🔧 [Proxmox VE Script](https://community-scripts.github.io/ProxmoxVE/scripts?id=gitea-mirror)

bunfig.toml

@@ -3,4 +3,7 @@
 timeout = 5000
 
 # Preload the setup file
-preload = ["./src/tests/setup.bun.ts"]
+preload = ["./src/tests/setup.bun.ts"]
+
+# Only run tests in src/ directory (excludes tests/e2e/ which are Playwright tests)
+root = "./src/"

design/giteamirror.pen

@@ -0,0 +1,804 @@
+{
+  "version": "2.9",
+  "children": [
+    {
+      "type": "frame",
+      "id": "eIiDx",
+      "x": 0,
+      "y": 0,
+      "name": "Scheduling Settings - Redesign",
+      "width": 1080,
+      "fill": "#09090B",
+      "cornerRadius": 16,
+      "gap": 24,
+      "padding": 32,
+      "children": [
+        {
+          "type": "frame",
+          "id": "7r0Wv",
+          "name": "Automatic Syncing Card",
+          "clip": true,
+          "width": "fill_container",
+          "fill": "#18181B",
+          "cornerRadius": 12,
+          "stroke": {
+            "align": "inside",
+            "thickness": 1,
+            "fill": "#27272A"
+          },
+          "layout": "vertical",
+          "children": [
+            {
+              "type": "frame",
+              "id": "gyCPG",
+              "name": "Header",
+              "width": "fill_container",
+              "gap": 12,
+              "padding": [
+                20,
+                24
+              ],
+              "alignItems": "center",
+              "children": [
+                {
+                  "type": "icon_font",
+                  "id": "OunzZ",
+                  "name": "headerIcon",
+                  "width": 20,
+                  "height": 20,
+                  "iconFontName": "refresh-cw",
+                  "iconFontFamily": "lucide",
+                  "fill": "#A1A1AA"
+                },
+                {
+                  "type": "text",
+                  "id": "fMdlX",
+                  "name": "headerTitle",
+                  "fill": "#FAFAFA",
+                  "content": "Automatic Syncing",
+                  "fontFamily": "Inter",
+                  "fontSize": 16,
+                  "fontWeight": "600"
+                }
+              ]
+            },
+            {
+              "type": "rectangle",
+              "id": "4cX02",
+              "name": "divider1",
+              "fill": "#27272A",
+              "width": "fill_container",
+              "height": 1
+            },
+            {
+              "type": "frame",
+              "id": "Kiezh",
+              "name": "Toggle Section",
+              "width": "fill_container",
+              "gap": 14,
+              "padding": [
+                20,
+                24
+              ],
+              "children": [
+                {
+                  "type": "frame",
+                  "id": "QCPzN",
+                  "name": "Checkbox",
+                  "width": 20,
+                  "height": 20,
+                  "fill": "#6366F1",
+                  "cornerRadius": 4,
+                  "layout": "none",
+                  "children": [
+                    {
+                      "type": "icon_font",
+                      "id": "4FTax",
+                      "x": 3,
+                      "y": 3,
+                      "name": "checkIcon",
+                      "width": 14,
+                      "height": 14,
+                      "iconFontName": "check",
+                      "iconFontFamily": "lucide",
+                      "fill": "#FFFFFF"
+                    }
+                  ]
+                },
+                {
+                  "type": "frame",
+                  "id": "FTzs6",
+                  "name": "toggleText",
+                  "width": "fill_container",
+                  "layout": "vertical",
+                  "gap": 4,
+                  "children": [
+                    {
+                      "type": "text",
+                      "id": "1nJKC",
+                      "name": "toggleLabel",
+                      "fill": "#FAFAFA",
+                      "content": "Enable automatic repository syncing",
+                      "fontFamily": "Inter",
+                      "fontSize": 14,
+                      "fontWeight": "500"
+                    },
+                    {
+                      "type": "text",
+                      "id": "r1O5t",
+                      "name": "toggleDesc",
+                      "fill": "#71717A",
+                      "textGrowth": "fixed-width",
+                      "width": "fill_container",
+                      "content": "Periodically sync GitHub changes to Gitea",
+                      "fontFamily": "Inter",
+                      "fontSize": 13
+                    }
+                  ]
+                }
+              ]
+            },
+            {
+              "type": "rectangle",
+              "id": "nvQ6R",
+              "name": "divider2",
+              "fill": "#27272A",
+              "width": "fill_container",
+              "height": 1
+            },
+            {
+              "type": "frame",
+              "id": "FOoBn",
+              "name": "Schedule Builder",
+              "width": "fill_container",
+              "layout": "vertical",
+              "gap": 20,
+              "padding": 24,
+              "children": [
+                {
+                  "type": "frame",
+                  "id": "IqHEu",
+                  "name": "schedHeader",
+                  "width": "fill_container",
+                  "justifyContent": "space_between",
+                  "alignItems": "center",
+                  "children": [
+                    {
+                      "type": "text",
+                      "id": "RnVoM",
+                      "name": "schedTitle",
+                      "fill": "#A1A1AA",
+                      "content": "SCHEDULE",
+                      "fontFamily": "Inter",
+                      "fontSize": 12,
+                      "fontWeight": "600",
+                      "letterSpacing": 1
+                    },
+                    {
+                      "type": "frame",
+                      "id": "aVtIZ",
+                      "name": "tzBadge",
+                      "fill": "#27272A",
+                      "cornerRadius": 20,
+                      "gap": 6,
+                      "padding": [
+                        4,
+                        10
+                      ],
+                      "alignItems": "center",
+                      "children": [
+                        {
+                          "type": "icon_font",
+                          "id": "iXpYV",
+                          "name": "tzIcon",
+                          "width": 12,
+                          "height": 12,
+                          "iconFontName": "globe",
+                          "iconFontFamily": "lucide",
+                          "fill": "#71717A"
+                        },
+                        {
+                          "type": "text",
+                          "id": "WjPMl",
+                          "name": "tzText",
+                          "fill": "#A1A1AA",
+                          "content": "UTC",
+                          "fontFamily": "Inter",
+                          "fontSize": 11,
+                          "fontWeight": "500"
+                        }
+                      ]
+                    }
+                  ]
+                },
+                {
+                  "type": "frame",
+                  "id": "P02fk",
+                  "name": "formRow",
+                  "width": "fill_container",
+                  "gap": 12,
+                  "children": [
+                    {
+                      "type": "frame",
+                      "id": "kcYK5",
+                      "name": "Frequency",
+                      "width": "fill_container",
+                      "layout": "vertical",
+                      "gap": 6,
+                      "children": [
+                        {
+                          "type": "text",
+                          "id": "vMvsN",
+                          "name": "label2",
+                          "fill": "#A1A1AA",
+                          "content": "Frequency",
+                          "fontFamily": "Inter",
+                          "fontSize": 12,
+                          "fontWeight": "500"
+                        },
+                        {
+                          "type": "frame",
+                          "id": "3prth",
+                          "name": "select2",
+                          "width": "fill_container",
+                          "height": 40,
+                          "fill": "#27272A",
+                          "cornerRadius": 8,
+                          "stroke": {
+                            "align": "inside",
+                            "thickness": 1,
+                            "fill": "#3F3F46"
+                          },
+                          "padding": [
+                            0,
+                            12
+                          ],
+                          "justifyContent": "space_between",
+                          "alignItems": "center",
+                          "children": [
+                            {
+                              "type": "text",
+                              "id": "ANY36",
+                              "name": "sel2Text",
+                              "fill": "#FAFAFA",
+                              "content": "Daily",
+                              "fontFamily": "Inter",
+                              "fontSize": 13
+                            },
+                            {
+                              "type": "icon_font",
+                              "id": "GUWfd",
+                              "name": "sel2Icon",
+                              "width": 16,
+                              "height": 16,
+                              "iconFontName": "chevron-down",
+                              "iconFontFamily": "lucide",
+                              "fill": "#71717A"
+                            }
+                          ]
+                        }
+                      ]
+                    },
+                    {
+                      "type": "frame",
+                      "id": "xphp0",
+                      "name": "Start Time",
+                      "width": "fill_container",
+                      "layout": "vertical",
+                      "gap": 6,
+                      "children": [
+                        {
+                          "type": "text",
+                          "id": "l6VkR",
+                          "name": "label3",
+                          "fill": "#A1A1AA",
+                          "content": "Start Time",
+                          "fontFamily": "Inter",
+                          "fontSize": 12,
+                          "fontWeight": "500"
+                        },
+                        {
+                          "type": "frame",
+                          "id": "lWBDi",
+                          "name": "timeInput",
+                          "width": "fill_container",
+                          "height": 40,
+                          "fill": "#27272A",
+                          "cornerRadius": 8,
+                          "stroke": {
+                            "align": "inside",
+                            "thickness": 1,
+                            "fill": "#3F3F46"
+                          },
+                          "padding": [
+                            0,
+                            12
+                          ],
+                          "justifyContent": "space_between",
+                          "alignItems": "center",
+                          "children": [
+                            {
+                              "type": "text",
+                              "id": "fbuMi",
+                              "name": "timeText",
+                              "fill": "#FAFAFA",
+                              "content": "10:00 PM",
+                              "fontFamily": "Inter",
+                              "fontSize": 13
+                            },
+                            {
+                              "type": "icon_font",
+                              "id": "5xKW7",
+                              "name": "timeIcon",
+                              "width": 16,
+                              "height": 16,
+                              "iconFontName": "clock-4",
+                              "iconFontFamily": "lucide",
+                              "fill": "#71717A"
+                            }
+                          ]
+                        }
+                      ]
+                    }
+                  ]
+                }
+              ]
+            },
+            {
+              "type": "rectangle",
+              "id": "BtYt7",
+              "name": "divider3",
+              "fill": "#27272A",
+              "width": "fill_container",
+              "height": 1
+            },
+            {
+              "type": "frame",
+              "id": "520Kb",
+              "name": "Status Bar",
+              "width": "fill_container",
+              "padding": [
+                16,
+                24
+              ],
+              "justifyContent": "space_between",
+              "alignItems": "center",
+              "children": [
+                {
+                  "type": "frame",
+                  "id": "J8JzX",
+                  "name": "lastSync",
+                  "gap": 8,
+                  "alignItems": "center",
+                  "children": [
+                    {
+                      "type": "icon_font",
+                      "id": "MS5VM",
+                      "name": "lastIcon",
+                      "width": 14,
+                      "height": 14,
+                      "iconFontName": "history",
+                      "iconFontFamily": "lucide",
+                      "fill": "#52525B"
+                    },
+                    {
+                      "type": "text",
+                      "id": "8KJHY",
+                      "name": "lastLabel",
+                      "fill": "#52525B",
+                      "content": "Last sync",
+                      "fontFamily": "Inter",
+                      "fontSize": 12
+                    },
+                    {
+                      "type": "text",
+                      "id": "Fz116",
+                      "name": "lastValue",
+                      "fill": "#A1A1AA",
+                      "content": "Never",
+                      "fontFamily": "Inter",
+                      "fontSize": 12,
+                      "fontWeight": "500"
+                    }
+                  ]
+                },
+                {
+                  "type": "frame",
+                  "id": "ZbRFN",
+                  "name": "nextSync",
+                  "gap": 8,
+                  "alignItems": "center",
+                  "children": [
+                    {
+                      "type": "icon_font",
+                      "id": "wIKSk",
+                      "name": "nextIcon",
+                      "width": 14,
+                      "height": 14,
+                      "iconFontName": "calendar",
+                      "iconFontFamily": "lucide",
+                      "fill": "#52525B"
+                    },
+                    {
+                      "type": "text",
+                      "id": "ejqSP",
+                      "name": "nextLabel",
+                      "fill": "#52525B",
+                      "content": "Next sync",
+                      "fontFamily": "Inter",
+                      "fontSize": 12
+                    },
+                    {
+                      "type": "text",
+                      "id": "M4oJ7",
+                      "name": "nextValue",
+                      "fill": "#6366F1",
+                      "content": "Calculating...",
+                      "fontFamily": "Inter",
+                      "fontSize": 12,
+                      "fontWeight": "500"
+                    }
+                  ]
+                }
+              ]
+            }
+          ]
+        },
+        {
+          "type": "frame",
+          "id": "7PK7H",
+          "name": "Database Maintenance Card",
+          "clip": true,
+          "width": "fill_container",
+          "height": "fill_container",
+          "fill": "#18181B",
+          "cornerRadius": 12,
+          "stroke": {
+            "align": "inside",
+            "thickness": 1,
+            "fill": "#27272A"
+          },
+          "layout": "vertical",
+          "children": [
+            {
+              "type": "frame",
+              "id": "FAaon",
+              "name": "Header",
+              "width": "fill_container",
+              "gap": 12,
+              "padding": [
+                20,
+                24
+              ],
+              "alignItems": "center",
+              "children": [
+                {
+                  "type": "icon_font",
+                  "id": "64CaE",
+                  "name": "rHeaderIcon",
+                  "width": 20,
+                  "height": 20,
+                  "iconFontName": "database",
+                  "iconFontFamily": "lucide",
+                  "fill": "#A1A1AA"
+                },
+                {
+                  "type": "text",
+                  "id": "rvZlC",
+                  "name": "rHeaderTitle",
+                  "fill": "#FAFAFA",
+                  "content": "Database Maintenance",
+                  "fontFamily": "Inter",
+                  "fontSize": 16,
+                  "fontWeight": "600"
+                }
+              ]
+            },
+            {
+              "type": "rectangle",
+              "id": "nsM0M",
+              "name": "rDivider1",
+              "fill": "#27272A",
+              "width": "fill_container",
+              "height": 1
+            },
+            {
+              "type": "frame",
+              "id": "8zhPi",
+              "name": "Toggle Section",
+              "width": "fill_container",
+              "gap": 14,
+              "padding": [
+                20,
+                24
+              ],
+              "children": [
+                {
+                  "type": "frame",
+                  "id": "eQbZk",
+                  "name": "Checkbox",
+                  "width": 20,
+                  "height": 20,
+                  "fill": "#6366F1",
+                  "cornerRadius": 4,
+                  "layout": "none",
+                  "children": [
+                    {
+                      "type": "icon_font",
+                      "id": "t6PbY",
+                      "x": 3,
+                      "y": 3,
+                      "name": "rCheckIcon",
+                      "width": 14,
+                      "height": 14,
+                      "iconFontName": "check",
+                      "iconFontFamily": "lucide",
+                      "fill": "#FFFFFF"
+                    }
+                  ]
+                },
+                {
+                  "type": "frame",
+                  "id": "lpBPI",
+                  "name": "rToggleText",
+                  "width": "fill_container",
+                  "layout": "vertical",
+                  "gap": 4,
+                  "children": [
+                    {
+                      "type": "text",
+                      "id": "Kuy1S",
+                      "name": "rToggleLabel",
+                      "fill": "#FAFAFA",
+                      "content": "Enable automatic database cleanup",
+                      "fontFamily": "Inter",
+                      "fontSize": 14,
+                      "fontWeight": "500"
+                    },
+                    {
+                      "type": "text",
+                      "id": "OviVY",
+                      "name": "rToggleDesc",
+                      "fill": "#71717A",
+                      "textGrowth": "fixed-width",
+                      "width": "fill_container",
+                      "content": "Remove old activity logs to optimize storage",
+                      "fontFamily": "Inter",
+                      "fontSize": 13
+                    }
+                  ]
+                }
+              ]
+            },
+            {
+              "type": "rectangle",
+              "id": "1og3D",
+              "name": "rDivider2",
+              "fill": "#27272A",
+              "width": "fill_container",
+              "height": 1
+            },
+            {
+              "type": "frame",
+              "id": "J7576",
+              "name": "Retention Section",
+              "width": "fill_container",
+              "layout": "vertical",
+              "gap": 16,
+              "padding": 24,
+              "children": [
+                {
+                  "type": "frame",
+                  "id": "JZA6R",
+                  "name": "retLabelRow",
+                  "gap": 6,
+                  "alignItems": "center",
+                  "children": [
+                    {
+                      "type": "text",
+                      "id": "Diiak",
+                      "name": "retLabel",
+                      "fill": "#FAFAFA",
+                      "content": "Data retention period",
+                      "fontFamily": "Inter",
+                      "fontSize": 14,
+                      "fontWeight": "500"
+                    },
+                    {
+                      "type": "icon_font",
+                      "id": "1qqCe",
+                      "name": "retInfoIcon",
+                      "width": 14,
+                      "height": 14,
+                      "iconFontName": "info",
+                      "iconFontFamily": "lucide",
+                      "fill": "#52525B"
+                    }
+                  ]
+                },
+                {
+                  "type": "frame",
+                  "id": "kfUjs",
+                  "name": "retRow",
+                  "width": "fill_container",
+                  "gap": 16,
+                  "alignItems": "center",
+                  "children": [
+                    {
+                      "type": "frame",
+                      "id": "9bhls",
+                      "name": "retSelect",
+                      "width": 180,
+                      "height": 40,
+                      "fill": "#27272A",
+                      "cornerRadius": 8,
+                      "stroke": {
+                        "align": "inside",
+                        "thickness": 1,
+                        "fill": "#3F3F46"
+                      },
+                      "padding": [
+                        0,
+                        12
+                      ],
+                      "justifyContent": "space_between",
+                      "alignItems": "center",
+                      "children": [
+                        {
+                          "type": "text",
+                          "id": "3NOod",
+                          "name": "retSelText",
+                          "fill": "#FAFAFA",
+                          "content": "1 month",
+                          "fontFamily": "Inter",
+                          "fontSize": 13
+                        },
+                        {
+                          "type": "icon_font",
+                          "id": "8QBA8",
+                          "name": "retSelIcon",
+                          "width": 16,
+                          "height": 16,
+                          "iconFontName": "chevron-down",
+                          "iconFontFamily": "lucide",
+                          "fill": "#71717A"
+                        }
+                      ]
+                    },
+                    {
+                      "type": "text",
+                      "id": "GA6ye",
+                      "name": "retHelper",
+                      "fill": "#52525B",
+                      "content": "Cleanup runs every 2 days",
+                      "fontFamily": "Inter",
+                      "fontSize": 12
+                    }
+                  ]
+                }
+              ]
+            },
+            {
+              "type": "rectangle",
+              "id": "WfXVB",
+              "name": "rDivider3",
+              "fill": "#27272A",
+              "width": "fill_container",
+              "height": 1
+            },
+            {
+              "type": "frame",
+              "id": "WpXnI",
+              "name": "Cleanup Status",
+              "width": "fill_container",
+              "layout": "vertical",
+              "gap": 12,
+              "padding": [
+                16,
+                24
+              ],
+              "children": [
+                {
+                  "type": "frame",
+                  "id": "fbpm5",
+                  "name": "lastCleanup",
+                  "width": "fill_container",
+                  "justifyContent": "space_between",
+                  "alignItems": "center",
+                  "children": [
+                    {
+                      "type": "frame",
+                      "id": "DdLix",
+                      "name": "lastCleanupLeft",
+                      "gap": 8,
+                      "alignItems": "center",
+                      "children": [
+                        {
+                          "type": "icon_font",
+                          "id": "FN2cj",
+                          "name": "lastCleanIcon",
+                          "width": 14,
+                          "height": 14,
+                          "iconFontName": "history",
+                          "iconFontFamily": "lucide",
+                          "fill": "#52525B"
+                        },
+                        {
+                          "type": "text",
+                          "id": "JjmMa",
+                          "name": "lastCleanLabel",
+                          "fill": "#52525B",
+                          "content": "Last cleanup",
+                          "fontFamily": "Inter",
+                          "fontSize": 12
+                        }
+                      ]
+                    },
+                    {
+                      "type": "text",
+                      "id": "l1Kph",
+                      "name": "lastCleanValue",
+                      "fill": "#A1A1AA",
+                      "content": "Never",
+                      "fontFamily": "Inter",
+                      "fontSize": 12,
+                      "fontWeight": "500"
+                    }
+                  ]
+                },
+                {
+                  "type": "frame",
+                  "id": "AWHY8",
+                  "name": "nextCleanup",
+                  "width": "fill_container",
+                  "justifyContent": "space_between",
+                  "alignItems": "center",
+                  "children": [
+                    {
+                      "type": "frame",
+                      "id": "sj0qN",
+                      "name": "nextCleanupLeft",
+                      "gap": 8,
+                      "alignItems": "center",
+                      "children": [
+                        {
+                          "type": "icon_font",
+                          "id": "V6RTK",
+                          "name": "nextCleanIcon",
+                          "width": 14,
+                          "height": 14,
+                          "iconFontName": "calendar",
+                          "iconFontFamily": "lucide",
+                          "fill": "#52525B"
+                        },
+                        {
+                          "type": "text",
+                          "id": "wf0b4",
+                          "name": "nextCleanLabel",
+                          "fill": "#52525B",
+                          "content": "Next cleanup",
+                          "fontFamily": "Inter",
+                          "fontSize": 12
+                        }
+                      ]
+                    },
+                    {
+                      "type": "text",
+                      "id": "YWZGH",
+                      "name": "nextCleanValue",
+                      "fill": "#6366F1",
+                      "content": "March 20, 2026 at 12:19 AM",
+                      "fontFamily": "Inter",
+                      "fontSize": 12,
+                      "fontWeight": "500"
+                    }
+                  ]
+                }
+              ]
+            }
+          ]
+        }
+      ]
+    }
+  ]
+}

docker-compose.alt.yml

@@ -18,6 +18,11 @@ services:
       - BETTER_AUTH_SECRET=${BETTER_AUTH_SECRET}  # Min 32 chars, required for sessions
       - BETTER_AUTH_URL=${BETTER_AUTH_URL:-http://localhost:4321}
       - BETTER_AUTH_TRUSTED_ORIGINS=${BETTER_AUTH_TRUSTED_ORIGINS:-http://localhost:4321}
+      # REVERSE PROXY: If accessing via a reverse proxy, set all three to your external URL:
+      #   BETTER_AUTH_URL=https://gitea-mirror.example.com
+      #   PUBLIC_BETTER_AUTH_URL=https://gitea-mirror.example.com
+      #   BETTER_AUTH_TRUSTED_ORIGINS=https://gitea-mirror.example.com
+      # Path-prefix deployments (e.g. /mirror) are supported at runtime via BASE_URL.
       
       # === CORE SETTINGS ===
       # These are technically required but have working defaults
@@ -25,6 +30,7 @@ services:
       - DATABASE_URL=file:data/gitea-mirror.db
       - HOST=0.0.0.0
       - PORT=4321
+      - BASE_URL=${BASE_URL:-/}
       - PUBLIC_BETTER_AUTH_URL=${PUBLIC_BETTER_AUTH_URL:-http://localhost:4321}
       # Optional concurrency controls (defaults match in-app defaults)
       # If you want perfect ordering of issues and PRs, set these at 1
@@ -32,7 +38,11 @@ services:
       - MIRROR_PULL_REQUEST_CONCURRENCY=${MIRROR_PULL_REQUEST_CONCURRENCY:-5}
       
     healthcheck:
-      test: ["CMD", "wget", "--no-verbose", "--tries=3", "--spider", "http://localhost:4321/api/health"]
+      test:
+        [
+          "CMD-SHELL",
+          "BASE=\"${BASE_URL:-/}\"; if [ \"$${BASE}\" = \"/\" ]; then BASE=\"\"; else BASE=\"$${BASE%/}\"; fi; wget --no-verbose --tries=3 --spider \"http://localhost:4321$${BASE}/api/health\"",
+        ]
       interval: 30s
       timeout: 10s
       retries: 5

docker-compose.dev.yml

@@ -66,6 +66,7 @@ services:
       - DATABASE_URL=file:data/gitea-mirror.db
       - HOST=0.0.0.0
       - PORT=4321
+      - BASE_URL=${BASE_URL:-/}
       - BETTER_AUTH_SECRET=dev-secret-key
       # GitHub/Gitea Mirror Config
       - GITHUB_USERNAME=${GITHUB_USERNAME:-your-github-username}
@@ -89,7 +90,11 @@ services:
       # Optional: Skip TLS verification (insecure, use only for testing)
       # - GITEA_SKIP_TLS_VERIFY=${GITEA_SKIP_TLS_VERIFY:-false}
     healthcheck:
-      test: ["CMD", "wget", "--no-verbose", "--tries=1", "--spider", "http://localhost:4321/api/health"]
+      test:
+        [
+          "CMD-SHELL",
+          "BASE=\"${BASE_URL:-/}\"; if [ \"$${BASE}\" = \"/\" ]; then BASE=\"\"; else BASE=\"$${BASE%/}\"; fi; wget --no-verbose --tries=1 --spider \"http://localhost:4321$${BASE}/api/health\"",
+        ]
       interval: 30s
       timeout: 5s
       retries: 3

docker-compose.yml

@@ -30,8 +30,21 @@ services:
       - DATABASE_URL=file:data/gitea-mirror.db
       - HOST=0.0.0.0
       - PORT=4321
+      - BASE_URL=${BASE_URL:-/}
       - BETTER_AUTH_SECRET=${BETTER_AUTH_SECRET:-your-secret-key-change-this-in-production}
       - BETTER_AUTH_URL=${BETTER_AUTH_URL:-http://localhost:4321}
+      # REVERSE PROXY: If you access Gitea Mirror through a reverse proxy (e.g. Nginx, Caddy, Traefik),
+      # you MUST set these three variables to your external URL. Example:
+      #   BETTER_AUTH_URL=https://gitea-mirror.example.com
+      #   PUBLIC_BETTER_AUTH_URL=https://gitea-mirror.example.com
+      #   BETTER_AUTH_TRUSTED_ORIGINS=https://gitea-mirror.example.com
+      # If deployed under a path prefix (e.g. https://git.example.com/mirror), also set:
+      #   BASE_URL=/mirror
+      #   BETTER_AUTH_URL=https://git.example.com
+      #   PUBLIC_BETTER_AUTH_URL=https://git.example.com
+      #   BETTER_AUTH_TRUSTED_ORIGINS=https://git.example.com
+      - PUBLIC_BETTER_AUTH_URL=${PUBLIC_BETTER_AUTH_URL:-http://localhost:4321}
+      - BETTER_AUTH_TRUSTED_ORIGINS=${BETTER_AUTH_TRUSTED_ORIGINS:-}
       # Optional: ENCRYPTION_SECRET will be auto-generated if not provided
       # - ENCRYPTION_SECRET=${ENCRYPTION_SECRET:-}
       # GitHub/Gitea Mirror Config
@@ -74,7 +87,11 @@ services:
       - HEADER_AUTH_AUTO_PROVISION=${HEADER_AUTH_AUTO_PROVISION:-false}
       - HEADER_AUTH_ALLOWED_DOMAINS=${HEADER_AUTH_ALLOWED_DOMAINS:-}
     healthcheck:
-      test: ["CMD", "wget", "--no-verbose", "--tries=3", "--spider", "http://localhost:4321/api/health"]
+      test:
+        [
+          "CMD-SHELL",
+          "BASE=\"${BASE_URL:-/}\"; if [ \"$${BASE}\" = \"/\" ]; then BASE=\"\"; else BASE=\"$${BASE%/}\"; fi; wget --no-verbose --tries=3 --spider \"http://localhost:4321$${BASE}/api/health\"",
+        ]
       interval: 30s
       timeout: 10s
       retries: 5

docker-entrypoint.sh

@@ -139,16 +139,29 @@ fi
 
 # Initialize configuration from environment variables if provided
 echo "Checking for environment configuration..."
-if [ -f "dist/scripts/startup-env-config.js" ]; then
-  echo "Loading configuration from environment variables..."
-  bun dist/scripts/startup-env-config.js
-  ENV_CONFIG_EXIT_CODE=$?
-elif [ -f "scripts/startup-env-config.ts" ]; then
-  echo "Loading configuration from environment variables..."
-  bun scripts/startup-env-config.ts
-  ENV_CONFIG_EXIT_CODE=$?
+
+# Only run the env config script if relevant env vars are set
+# This avoids spawning a heavy Bun process on memory-constrained systems
+HAS_ENV_CONFIG=false
+if [ -n "$GITHUB_USERNAME" ] || [ -n "$GITHUB_TOKEN" ] || [ -n "$GITEA_URL" ] || [ -n "$GITEA_USERNAME" ] || [ -n "$GITEA_TOKEN" ]; then
+  HAS_ENV_CONFIG=true
+fi
+
+if [ "$HAS_ENV_CONFIG" = "true" ]; then
+  if [ -f "dist/scripts/startup-env-config.js" ]; then
+    echo "Loading configuration from environment variables..."
+    bun dist/scripts/startup-env-config.js || ENV_CONFIG_EXIT_CODE=$?
+    ENV_CONFIG_EXIT_CODE=${ENV_CONFIG_EXIT_CODE:-0}
+  elif [ -f "scripts/startup-env-config.ts" ]; then
+    echo "Loading configuration from environment variables..."
+    bun scripts/startup-env-config.ts || ENV_CONFIG_EXIT_CODE=$?
+    ENV_CONFIG_EXIT_CODE=${ENV_CONFIG_EXIT_CODE:-0}
+  else
+    echo "Environment configuration script not found. Skipping."
+    ENV_CONFIG_EXIT_CODE=0
+  fi
 else
-  echo "Environment configuration script not found. Skipping."
+  echo "No GitHub/Gitea environment variables found, skipping env config initialization."
   ENV_CONFIG_EXIT_CODE=0
 fi
 
@@ -161,17 +174,15 @@ fi
 
 # Run startup recovery to handle any interrupted jobs
 echo "Running startup recovery..."
+RECOVERY_EXIT_CODE=0
 if [ -f "dist/scripts/startup-recovery.js" ]; then
   echo "Running startup recovery using compiled script..."
-  bun dist/scripts/startup-recovery.js --timeout=30000
-  RECOVERY_EXIT_CODE=$?
+  bun dist/scripts/startup-recovery.js --timeout=30000 || RECOVERY_EXIT_CODE=$?
 elif [ -f "scripts/startup-recovery.ts" ]; then
   echo "Running startup recovery using TypeScript script..."
-  bun scripts/startup-recovery.ts --timeout=30000
-  RECOVERY_EXIT_CODE=$?
+  bun scripts/startup-recovery.ts --timeout=30000 || RECOVERY_EXIT_CODE=$?
 else
   echo "Warning: Startup recovery script not found. Skipping recovery."
-  RECOVERY_EXIT_CODE=0
 fi
 
 # Log recovery result
@@ -185,17 +196,15 @@ fi
 
 # Run repository status repair to fix any inconsistent mirroring states
 echo "Running repository status repair..."
+REPAIR_EXIT_CODE=0
 if [ -f "dist/scripts/repair-mirrored-repos.js" ]; then
   echo "Running repository repair using compiled script..."
-  bun dist/scripts/repair-mirrored-repos.js --startup
-  REPAIR_EXIT_CODE=$?
+  bun dist/scripts/repair-mirrored-repos.js --startup || REPAIR_EXIT_CODE=$?
 elif [ -f "scripts/repair-mirrored-repos.ts" ]; then
   echo "Running repository repair using TypeScript script..."
-  bun scripts/repair-mirrored-repos.ts --startup
-  REPAIR_EXIT_CODE=$?
+  bun scripts/repair-mirrored-repos.ts --startup || REPAIR_EXIT_CODE=$?
 else
   echo "Warning: Repository repair script not found. Skipping repair."
-  REPAIR_EXIT_CODE=0
 fi
 
 # Log repair result
@@ -220,7 +229,13 @@ trap 'shutdown_handler' TERM INT HUP
 
 # Start the application
 echo "Starting Gitea Mirror..."
-bun ./dist/server/entry.mjs &
+if [ -f "./scripts/runtime-server.ts" ]; then
+  bun ./scripts/runtime-server.ts &
+elif [ -f "./dist/scripts/runtime-server.js" ]; then
+  bun ./dist/scripts/runtime-server.js &
+else
+  bun ./dist/server/entry.mjs &
+fi
 APP_PID=$!
 
 # Wait for the application to finish

docs/DEVELOPMENT_WORKFLOW.md

@@ -310,26 +310,25 @@ bunx tsc --noEmit
 
 ## Release Process
 
-1. **Update version**:
-```bash
-npm version patch  # or minor/major
-```
+1. **Choose release version** (`X.Y.Z`) and update `CHANGELOG.md`
 
-2. **Update CHANGELOG.md**
-
-3. **Build and test**:
+2. **Build and test**:
 ```bash
 bun run build
 bun test
 ```
 
-4. **Create release**:
+3. **Create release tag** (semver format required):
 ```bash
-git tag v2.23.0
-git push origin v2.23.0
+git tag vX.Y.Z
+git push origin vX.Y.Z
 ```
 
-5. **Create GitHub release**
+4. **Create GitHub release**
+
+5. **CI version sync (automatic)**:
+- On `v*` tags, release CI updates `package.json` version in the build context from the tag (`vX.Y.Z` -> `X.Y.Z`), so Docker release images always report the correct app version.
+- After the release build succeeds, CI commits the same `package.json` version back to `main` automatically.
 
 ## Contributing
 
@@ -349,6 +348,6 @@ git push origin v2.23.0
 
 ## Getting Help
 
-- Check existing [issues](https://github.com/yourusername/gitea-mirror/issues)
-- Join [discussions](https://github.com/yourusername/gitea-mirror/discussions)
-- Read the [FAQ](./FAQ.md)
+- Check existing [issues](https://github.com/RayLabsHQ/gitea-mirror/issues)
+- Join [discussions](https://github.com/RayLabsHQ/gitea-mirror/discussions)
+- Review project docs in [docs/README.md](./README.md)

docs/ENVIRONMENT_VARIABLES.md

@@ -16,6 +16,7 @@ When environment variables are set:
 ## Table of Contents
 
 - [Core Configuration](#core-configuration)
+- [HTTPS / TLS](#https--tls)
 - [GitHub Configuration](#github-configuration)
 - [Gitea Configuration](#gitea-configuration)
 - [Mirror Options](#mirror-options)
@@ -33,13 +34,38 @@ Essential application settings required for running Gitea Mirror.
 | `NODE_ENV` | Application environment | `production` | No |
 | `HOST` | Server host binding | `0.0.0.0` | No |
 | `PORT` | Server port | `4321` | No |
+| `BASE_URL` | Application base path. Use `/` for root deployments, or a prefix such as `/mirror` when serving behind a reverse-proxy path prefix. | `/` | No |
 | `DATABASE_URL` | Database connection URL | `sqlite://data/gitea-mirror.db` | No |
 | `BETTER_AUTH_SECRET` | Secret key for session signing (generate with: `openssl rand -base64 32`) | - | Yes |
-| `BETTER_AUTH_URL` | Primary base URL for authentication. This should be the main URL where your application is accessed. | `http://localhost:4321` | No |
-| `PUBLIC_BETTER_AUTH_URL` | Client-side auth URL for multi-origin access. Set this to your primary domain when you need to access the app from different origins (e.g., both IP and domain). The client will use this URL for all auth requests instead of the current browser origin. | - | No |
+| `BETTER_AUTH_URL` | Authentication origin (scheme + host only, e.g. `https://git.example.com`). Do **not** include a path — any path is automatically stripped, and `BASE_URL` is applied separately. | `http://localhost:4321` | No |
+| `PUBLIC_BETTER_AUTH_URL` | Client-side auth origin for multi-origin access (same rule: origin only, no path). Set this to your primary domain when you need to access the app from different origins (e.g., both IP and domain). The client will use this URL for all auth requests instead of the current browser origin. | - | No |
 | `BETTER_AUTH_TRUSTED_ORIGINS` | Trusted origins for authentication requests. Comma-separated list of URLs. Use this to specify additional access URLs (e.g., local IP + domain: `http://10.10.20.45:4321,https://gitea-mirror.mydomain.tld`), SSO providers, reverse proxies, etc. | - | No |
 | `ENCRYPTION_SECRET` | Optional encryption key for tokens (generate with: `openssl rand -base64 48`) | - | No |
 
+## HTTPS / TLS
+
+Gitea Mirror can terminate TLS directly via the underlying `@astrojs/node` adapter — useful when you don't want a separate reverse proxy. When both variables below are set, the server starts as a real HTTPS listener instead of HTTP.
+
+| Variable | Description | Default | Required |
+|----------|-------------|---------|----------|
+| `SERVER_CERT_PATH` | Absolute path to the TLS certificate (PEM). Set together with `SERVER_KEY_PATH` to enable HTTPS. | - | No |
+| `SERVER_KEY_PATH` | Absolute path to the TLS private key (PEM). Set together with `SERVER_CERT_PATH` to enable HTTPS. | - | No |
+
+**Example (systemd or `.env`):**
+
+```bash
+SERVER_CERT_PATH=/etc/ssl/gitea-mirror/cert.pem
+SERVER_KEY_PATH=/etc/ssl/gitea-mirror/key.pem
+PORT=443
+BETTER_AUTH_URL=https://mirror.example.com
+BETTER_AUTH_TRUSTED_ORIGINS=https://mirror.example.com
+```
+
+Notes:
+- The process must have read access to both files. When binding to `PORT=443`, grant the binary the `CAP_NET_BIND_SERVICE` capability (or run as a user allowed to bind privileged ports) rather than running as root.
+- If you already terminate TLS at a reverse proxy (nginx, Traefik, Caddy), leave these unset and let the proxy handle certificates.
+- Works in Docker too — mount your certs and set both paths to locations inside the container.
+
 ## GitHub Configuration
 
 Settings for connecting to and configuring GitHub repository sources.
@@ -51,6 +77,21 @@ Settings for connecting to and configuring GitHub repository sources.
 | `GITHUB_USERNAME` | Your GitHub username | - | - |
 | `GITHUB_TOKEN` | GitHub personal access token (requires repo and admin:org scopes) | - | - |
 | `GITHUB_TYPE` | GitHub account type | `personal` | `personal`, `organization` |
+| `GH_API_URL` | GitHub API base URL. Override this to point at GitHub Enterprise Server or Enterprise Cloud with data residency. | `https://api.github.com` | e.g. `https://ghe.example.com/api/v3`, `https://api.TENANT.ghe.com` |
+
+### GitHub Enterprise (GHES / GHEC with data residency)
+
+Set `GH_API_URL` to point Octokit at a non-`github.com` API endpoint:
+
+```bash
+# GitHub Enterprise Server (self-hosted)
+GH_API_URL=https://ghe.example.com/api/v3
+
+# GitHub Enterprise Cloud with data residency
+GH_API_URL=https://api.TENANT.ghe.com
+```
+
+Standard GitHub Enterprise Cloud on `github.com` works with the default — no override needed. Use a personal access token issued by the target Enterprise instance for `GITHUB_TOKEN`.
 
 ### Repository Selection
 
@@ -59,8 +100,10 @@ Settings for connecting to and configuring GitHub repository sources.
 | `PRIVATE_REPOSITORIES` | Include private repositories | `false` | `true`, `false` |
 | `PUBLIC_REPOSITORIES` | Include public repositories | `true` | `true`, `false` |
 | `INCLUDE_ARCHIVED` | Include archived repositories | `false` | `true`, `false` |
+| `INCLUDE_COLLABORATOR_REPOS` | Include repositories where you are a collaborator (not just owned). Set to `false` to limit imports to repos you own. | `true` | `true`, `false` |
 | `SKIP_FORKS` | Skip forked repositories | `false` | `true`, `false` |
 | `MIRROR_STARRED` | Mirror starred repositories | `false` | `true`, `false` |
+| `MIRROR_STARRED_LISTS` | Optional comma-separated GitHub Star List names to mirror (only used when `MIRROR_STARRED=true`) | - | Comma-separated list names (empty = all starred repos) |
 | `STARRED_REPOS_ORG` | Organization name for starred repos | `starred` | Any string |
 | `STARRED_REPOS_MODE` | How starred repos are mirrored | `dedicated-org` | `dedicated-org`, `preserve-owner` |
 
@@ -78,6 +121,7 @@ Settings for connecting to and configuring GitHub repository sources.
 | Variable | Description | Default | Options |
 |----------|-------------|---------|---------|
 | `SKIP_STARRED_ISSUES` | Enable lightweight mode for starred repos (skip issues) | `false` | `true`, `false` |
+| `AUTO_MIRROR_STARRED` | Automatically mirror starred repos during scheduled syncs and "Mirror All". When `false`, starred repos are imported for browsing but must be mirrored individually. | `false` | `true`, `false` |
 
 ## Gitea Configuration
 
@@ -300,6 +344,7 @@ services:
     environment:
       # Core Configuration
       - NODE_ENV=production
+      - BASE_URL=/
       - DATABASE_URL=file:data/gitea-mirror.db
       - BETTER_AUTH_SECRET=your-secure-secret-here
       # Primary access URL:
@@ -368,6 +413,24 @@ This setup allows you to:
 
 **Important:** When accessing from different origins (IP vs domain), you'll need to log in separately on each origin as cookies cannot be shared across different origins for security reasons.
 
+### Path Prefix Deployments
+
+If you serve Gitea Mirror under a subpath such as `https://git.example.com/mirror`, set:
+
+```bash
+# BASE_URL handles the path prefix — auth URLs stay as origin only
+BASE_URL=/mirror
+BETTER_AUTH_URL=https://git.example.com
+PUBLIC_BETTER_AUTH_URL=https://git.example.com
+BETTER_AUTH_TRUSTED_ORIGINS=https://git.example.com
+# → Auth endpoints resolve to: https://git.example.com/mirror/api/auth/*
+```
+
+Notes:
+- `BETTER_AUTH_URL` and `PUBLIC_BETTER_AUTH_URL` must be **origin only** (scheme + host). Do not include the base path — it is applied automatically from `BASE_URL`. Any path accidentally included is stripped.
+- `BETTER_AUTH_TRUSTED_ORIGINS` must also contain origins only (no path).
+- `BASE_URL` is applied at runtime, so prebuilt images can be reused with different path prefixes.
+
 ### Trusted Origins
 
 The `BETTER_AUTH_TRUSTED_ORIGINS` variable serves multiple purposes:

docs/FORCE_PUSH_PROTECTION.md

@@ -0,0 +1,183 @@
+# Force-Push Protection
+
+This document describes the smart force-push protection system introduced in gitea-mirror v3.11.0+.
+
+## The Problem
+
+GitHub repositories can be force-pushed at any time — rewriting history, deleting branches, or replacing commits entirely. When gitea-mirror syncs a force-pushed repo, the old history in Gitea is silently overwritten. Files, commits, and branches disappear with no way to recover them.
+
+The original workaround (`backupBeforeSync: true`) created a full git bundle backup before **every** sync. This doesn't scale — a user with 100+ GiB of mirrors would need up to 2 TB of backup storage with default retention settings, even though force-pushes are rare.
+
+## Solution: Smart Detection
+
+Instead of backing up everything every time, the system detects force-pushes **before** they happen and only acts when needed.
+
+### How Detection Works
+
+Before each sync, the app compares branch SHAs between Gitea (the mirror) and GitHub (the source):
+
+1. **Fetch branches from both sides** — lightweight API calls to get branch names and their latest commit SHAs
+2. **Compare each branch**:
+   - SHAs match → nothing changed, no action needed
+   - SHAs differ → check if the change is a normal push or a force-push
+3. **Ancestry check** — for branches with different SHAs, call GitHub's compare API to determine if the new SHA is a descendant of the old one:
+   - **Fast-forward** (new SHA descends from old) → normal push, safe to sync
+   - **Diverged** (histories split) → force-push detected
+   - **404** (old SHA doesn't exist on GitHub anymore) → history was rewritten, force-push detected
+   - **Branch deleted on GitHub** → flagged as destructive change
+
+### What Happens on Detection
+
+Depends on the configured strategy (see below):
+- **Backup strategies** (`always`, `on-force-push`): create a git bundle snapshot, then sync
+- **Block strategy** (`block-on-force-push`): halt the sync, mark the repo as `pending-approval`, wait for user action
+
+### Fail-Open Design
+
+If detection itself fails (GitHub rate limits, network errors, API outages), sync proceeds normally. Detection never blocks a sync due to its own failure. Individual branch check failures are skipped — one flaky branch doesn't affect the others.
+
+## Backup Strategies
+
+Configure via **Settings → GitHub Configuration → Destructive Update Protection**.
+
+| Strategy | What It Does | Storage Cost | Best For |
+|---|---|---|---|
+| **Disabled** | No detection, no backups | Zero | Repos you don't care about losing |
+| **Always Backup** | Snapshot before every sync (original behavior) | High | Small mirror sets, maximum safety |
+| **Smart** (default) | Detect force-pushes, backup only when found | Near-zero normally | Most users — efficient protection |
+| **Block & Approve** | Detect force-pushes, block sync until approved | Zero | Critical repos needing manual review |
+
+### Strategy Details
+
+#### Disabled
+
+Syncs proceed without any detection or backup. If a force-push happens on GitHub, the mirror silently overwrites.
+
+#### Always Backup
+
+Creates a git bundle snapshot before every sync regardless of whether a force-push occurred. This is the legacy behavior (equivalent to the old `backupBeforeSync: true`). Safe but expensive for large mirror sets.
+
+#### Smart (`on-force-push`) — Recommended
+
+Runs the force-push detection before each sync. On normal days (no force-pushes), syncs proceed without any backup overhead. When a force-push is detected, a snapshot is created before the sync runs.
+
+This gives you protection when it matters with near-zero cost when it doesn't.
+
+#### Block & Approve (`block-on-force-push`)
+
+Runs detection and, when a force-push is found, **blocks the sync entirely**. The repository is marked as `pending-approval` and excluded from future scheduled syncs until you take action:
+
+- **Approve**: creates a backup first, then syncs (safe)
+- **Dismiss**: clears the flag and resumes normal syncing (no backup)
+
+Use this for repos where you want manual control over destructive changes.
+
+## Additional Settings
+
+These appear when any non-disabled strategy is selected:
+
+### Snapshot Retention Count
+
+How many backup snapshots to keep per repository. Oldest snapshots are deleted when this limit is exceeded. Default: **5**.
+
+### Snapshot Retention Days
+
+Maximum age (in days) for backup snapshots. Bundles older than this are deleted during retention enforcement, though at least one bundle is always kept. Set to `0` to disable time-based retention. Default: **30**.
+
+### Snapshot Directory
+
+Where git bundle backups are stored. Default: **`data/repo-backups`**. Bundles are organized as `<directory>/<owner>/<repo>/<timestamp>.bundle`.
+
+### Block Sync on Snapshot Failure
+
+Available for **Always Backup** and **Smart** strategies. When enabled, if the snapshot creation fails (disk full, permissions error, etc.), the sync is also blocked. When disabled, sync continues even if the snapshot couldn't be created.
+
+Recommended: **enabled** if you rely on backups for recovery.
+
+## Backward Compatibility
+
+The old `backupBeforeSync` boolean is still recognized:
+
+| Old Setting | New Equivalent |
+|---|---|
+| `backupBeforeSync: true` | `backupStrategy: "on-force-push"` |
+| `backupBeforeSync: false` | `backupStrategy: "disabled"` |
+| Neither set | `backupStrategy: "on-force-push"` (new default) |
+
+Existing configurations are automatically mapped. The old field is deprecated but will continue to work.
+
+## Environment Variables
+
+No new environment variables are required. The backup strategy is configured through the web UI and stored in the database alongside other config.
+
+## API
+
+### Approve/Dismiss Blocked Repos
+
+When using the `block-on-force-push` strategy, repos that are blocked can be managed via the API:
+
+```bash
+# Approve sync (creates backup first, then syncs)
+curl -X POST http://localhost:4321/api/job/approve-sync \
+  -H "Content-Type: application/json" \
+  -H "Cookie: <session>" \
+  -d '{"repositoryIds": ["<id>"], "action": "approve"}'
+
+# Dismiss (clear the block, resume normal syncing)
+curl -X POST http://localhost:4321/api/job/approve-sync \
+  -H "Content-Type: application/json" \
+  -H "Cookie: <session>" \
+  -d '{"repositoryIds": ["<id>"], "action": "dismiss"}'
+```
+
+Blocked repos also show an **Approve** / **Dismiss** button in the repository table UI.
+
+## Architecture
+
+### Key Files
+
+| File | Purpose |
+|---|---|
+| `src/lib/utils/force-push-detection.ts` | Core detection: fetch branches, compare SHAs, check ancestry |
+| `src/lib/repo-backup.ts` | Strategy resolver, backup decision logic, bundle creation |
+| `src/lib/gitea-enhanced.ts` | Sync flow integration (calls detection + backup before mirror-sync) |
+| `src/pages/api/job/approve-sync.ts` | Approve/dismiss API endpoint |
+| `src/components/config/GitHubConfigForm.tsx` | Strategy selector UI |
+| `src/components/repositories/RepositoryTable.tsx` | Pending-approval badge + action buttons |
+
+### Detection Flow
+
+```
+syncGiteaRepoEnhanced()
+  │
+  ├─ Resolve backup strategy (config → backupStrategy → backupBeforeSync → default)
+  │
+  ├─ If strategy needs detection ("on-force-push" or "block-on-force-push"):
+  │    │
+  │    ├─ fetchGiteaBranches() — GET /api/v1/repos/{owner}/{repo}/branches
+  │    ├─ fetchGitHubBranches() — octokit.paginate(repos.listBranches)
+  │    │
+  │    └─ For each Gitea branch where SHA differs:
+  │         └─ checkAncestry() — octokit.repos.compareCommits()
+  │              ├─ "ahead" or "identical" → fast-forward (safe)
+  │              ├─ "diverged" or "behind" → force-push detected
+  │              └─ 404/422 → old SHA gone → force-push detected
+  │
+  ├─ If "block-on-force-push" + detected:
+  │    └─ Set repo status to "pending-approval", return early
+  │
+  ├─ If backup needed (always, or on-force-push + detected):
+  │    └─ Create git bundle snapshot
+  │
+  └─ Proceed to mirror-sync
+```
+
+## Troubleshooting
+
+**Repos stuck in "pending-approval"**: Use the Approve or Dismiss buttons in the repository table, or call the approve-sync API endpoint.
+
+**Detection always skipped**: Check the activity log for skip reasons. Common causes: Gitea repo not yet mirrored (first sync), GitHub API rate limits, network errors. All are fail-open by design.
+
+**Backups consuming too much space**: Lower the retention count, or switch from "Always Backup" to "Smart" which only creates backups on actual force-pushes.
+
+**False positives**: The detection compares branch-by-branch. A rebase (which is a force-push) will correctly trigger detection. If you routinely rebase branches, consider using "Smart" instead of "Block & Approve" to avoid constant approval prompts.

docs/NIX_DISTRIBUTION.md

@@ -16,7 +16,7 @@ nix run --extra-experimental-features 'nix-command flakes' github:RayLabsHQ/gite
 nix run github:RayLabsHQ/gitea-mirror/abc123def
 
 # Pin to git tag
-nix run github:RayLabsHQ/gitea-mirror/v3.8.11
+nix run github:RayLabsHQ/gitea-mirror/vX.Y.Z
 ```
 
 **How it works:**
@@ -110,11 +110,11 @@ GitHub Actions workflow validates builds on every push/PR:
 Tag releases for version pinning:
 
 ```bash
-git tag v3.8.11
-git push origin v3.8.11
+git tag vX.Y.Z
+git push origin vX.Y.Z
 
 # Users can then pin:
-nix run github:RayLabsHQ/gitea-mirror/v3.8.11
+nix run github:RayLabsHQ/gitea-mirror/vX.Y.Z
 ```
 
 ### Phase 4: nixpkgs Submission (Long Term)
@@ -143,13 +143,13 @@ nix profile install --extra-experimental-features 'nix-command flakes' github:Ra
 
 ```bash
 # Pin to git tag
-nix run github:RayLabsHQ/gitea-mirror/v3.8.11
+nix run github:RayLabsHQ/gitea-mirror/vX.Y.Z
 
 # Pin to commit
 nix run github:RayLabsHQ/gitea-mirror/abc123def
 
 # Lock in flake.nix
-inputs.gitea-mirror.url = "github:RayLabsHQ/gitea-mirror/v3.8.11";
+inputs.gitea-mirror.url = "github:RayLabsHQ/gitea-mirror/vX.Y.Z";
 ```
 
 #### Option 3: NixOS Configuration
@@ -160,7 +160,7 @@ inputs.gitea-mirror.url = "github:RayLabsHQ/gitea-mirror/v3.8.11";
     nixpkgs.url = "github:NixOS/nixpkgs/nixos-unstable";
     gitea-mirror.url = "github:RayLabsHQ/gitea-mirror";
     # Or pin to version:
-    # gitea-mirror.url = "github:RayLabsHQ/gitea-mirror/v3.8.11";
+    # gitea-mirror.url = "github:RayLabsHQ/gitea-mirror/vX.Y.Z";
   };
 
   outputs = { nixpkgs, gitea-mirror, ... }: {
@@ -257,7 +257,7 @@ git tag -l
 git ls-remote --tags origin
 
 # Test specific tag
-nix run github:RayLabsHQ/gitea-mirror/v3.8.11
+nix run github:RayLabsHQ/gitea-mirror/vX.Y.Z
 ```
 
 ---

docs/NOTIFICATIONS.md

@@ -0,0 +1,88 @@
+# Notifications
+
+Gitea Mirror supports push notifications for mirror events. You can be alerted when jobs succeed, fail, or when new repositories are discovered.
+
+## Supported Providers
+
+### 1. Ntfy.sh (Direct)
+
+[Ntfy.sh](https://ntfy.sh) is a simple HTTP-based pub-sub notification service. You can use the public server at `https://ntfy.sh` or self-host your own instance.
+
+**Setup (public server):**
+1. Go to **Configuration > Notifications**
+2. Enable notifications and select **Ntfy.sh** as the provider
+3. Set the **Topic** to a unique name (e.g., `my-gitea-mirror-abc123`)
+4. Leave the Server URL as `https://ntfy.sh`
+5. Subscribe to the same topic on your phone or desktop using the [ntfy app](https://ntfy.sh/docs/subscribe/phone/)
+
+**Setup (self-hosted):**
+1. Deploy ntfy using Docker: `docker run -p 8080:80 binwiederhier/ntfy serve`
+2. Set the **Server URL** to your instance (e.g., `http://ntfy:8080`)
+3. If authentication is enabled, provide an **Access token**
+4. Set your **Topic** name
+
+**Priority levels:**
+- `min` / `low` / `default` / `high` / `urgent`
+- Error notifications automatically use `high` priority regardless of the default setting
+
+### 2. Apprise API (Aggregator)
+
+[Apprise](https://github.com/caronc/apprise-api) is a notification aggregator that supports 100+ services (Slack, Discord, Telegram, Email, Pushover, and many more) through a single API.
+
+**Setup:**
+1. Deploy the Apprise API server:
+   ```yaml
+   # docker-compose.yml
+   services:
+     apprise:
+       image: caronc/apprise:latest
+       ports:
+         - "8000:8000"
+       volumes:
+         - apprise-config:/config
+   volumes:
+     apprise-config:
+   ```
+2. Configure your notification services in Apprise (via its web UI at `http://localhost:8000` or API)
+3. Create a configuration token/key in Apprise
+4. In Gitea Mirror, go to **Configuration > Notifications**
+5. Enable notifications and select **Apprise API**
+6. Set the **Server URL** to your Apprise instance (e.g., `http://apprise:8000`)
+7. Enter the **Token/path** you created in step 3
+
+**Tag filtering:**
+- Optionally set a **Tag** to only notify specific Apprise services
+- Leave empty to notify all configured services
+
+## Event Types
+
+| Event | Default | Description |
+|-------|---------|-------------|
+| Sync errors | On | A mirror job failed |
+| Sync success | Off | A mirror job completed successfully |
+| New repo discovered | Off | A new GitHub repo was auto-imported during scheduled sync |
+
+## Testing
+
+Use the **Send Test Notification** button on the Notifications settings page to verify your configuration. The test sends a sample success notification to your configured provider.
+
+## Troubleshooting
+
+**Notifications not arriving:**
+- Check that notifications are enabled in the settings
+- Verify the provider configuration (URL, topic/token)
+- Use the Test button to check connectivity
+- Check the server logs for `[NotificationService]` messages
+
+**Ntfy authentication errors:**
+- Ensure your access token is correct
+- If self-hosting, verify the ntfy server allows the topic
+
+**Apprise connection refused:**
+- Verify the Apprise API server is running and accessible from the Gitea Mirror container
+- If using Docker, ensure both containers are on the same network
+- Check the Apprise server logs for errors
+
+**Tokens and security:**
+- Notification tokens (ntfy access tokens, Apprise tokens) are encrypted at rest using the same AES-256-GCM encryption as GitHub/Gitea tokens
+- Tokens are decrypted only when sending notifications or displaying in the settings UI

docs/README.md

@@ -7,6 +7,8 @@ This folder contains engineering and operations references for the open-source G
 ### Core workflow
 - **[DEVELOPMENT_WORKFLOW.md](./DEVELOPMENT_WORKFLOW.md)** – Set up a local environment, run scripts, and understand the repo layout (app + marketing site).
 - **[ENVIRONMENT_VARIABLES.md](./ENVIRONMENT_VARIABLES.md)** – Complete reference for every configuration flag supported by the app and Docker images.
+- **[NIX_DEPLOYMENT.md](./NIX_DEPLOYMENT.md)** – User-facing deployment guide for Nix and NixOS.
+- **[NIX_DISTRIBUTION.md](./NIX_DISTRIBUTION.md)** – Maintainer notes for packaging, releases, and distribution strategy.
 
 ### Reliability & recovery
 - **[GRACEFUL_SHUTDOWN.md](./GRACEFUL_SHUTDOWN.md)** – How signal handling, shutdown coordination, and job persistence work in v3.
@@ -32,8 +34,6 @@ The first user you create locally becomes the administrator. All other configura
 ## Contributing & support
 
 - 🎯 Contribution guide: [../CONTRIBUTING.md](../CONTRIBUTING.md)
-- 📘 Code of conduct: [../CODE_OF_CONDUCT.md](../CODE_OF_CONDUCT.md)
 - 🐞 Issues & feature requests: <https://github.com/RayLabsHQ/gitea-mirror/issues>
 - 💬 Discussions: <https://github.com/RayLabsHQ/gitea-mirror/discussions>
-
-Security disclosures should follow the process in [../SECURITY.md](../SECURITY.md).
+- 🔐 Security policy & advisories: <https://github.com/RayLabsHQ/gitea-mirror/security>

drizzle/0009_nervous_tyger_tiger.sql

@@ -0,0 +1,149 @@
+CREATE TABLE `__new_repositories` (
+	`id` text PRIMARY KEY NOT NULL,
+	`user_id` text NOT NULL,
+	`config_id` text NOT NULL,
+	`name` text NOT NULL,
+	`full_name` text NOT NULL,
+	`normalized_full_name` text NOT NULL,
+	`url` text NOT NULL,
+	`clone_url` text NOT NULL,
+	`owner` text NOT NULL,
+	`organization` text,
+	`mirrored_location` text DEFAULT '',
+	`is_private` integer DEFAULT false NOT NULL,
+	`is_fork` integer DEFAULT false NOT NULL,
+	`forked_from` text,
+	`has_issues` integer DEFAULT false NOT NULL,
+	`is_starred` integer DEFAULT false NOT NULL,
+	`is_archived` integer DEFAULT false NOT NULL,
+	`size` integer DEFAULT 0 NOT NULL,
+	`has_lfs` integer DEFAULT false NOT NULL,
+	`has_submodules` integer DEFAULT false NOT NULL,
+	`language` text,
+	`description` text,
+	`default_branch` text NOT NULL,
+	`visibility` text DEFAULT 'public' NOT NULL,
+	`status` text DEFAULT 'imported' NOT NULL,
+	`last_mirrored` integer,
+	`error_message` text,
+	`destination_org` text,
+	`metadata` text,
+	`imported_at` integer DEFAULT (unixepoch()) NOT NULL,
+	`created_at` integer DEFAULT (unixepoch()) NOT NULL,
+	`updated_at` integer DEFAULT (unixepoch()) NOT NULL,
+	FOREIGN KEY (`user_id`) REFERENCES `users`(`id`) ON UPDATE no action ON DELETE no action,
+	FOREIGN KEY (`config_id`) REFERENCES `configs`(`id`) ON UPDATE no action ON DELETE no action
+);
+--> statement-breakpoint
+INSERT INTO `__new_repositories` (
+	`id`,
+	`user_id`,
+	`config_id`,
+	`name`,
+	`full_name`,
+	`normalized_full_name`,
+	`url`,
+	`clone_url`,
+	`owner`,
+	`organization`,
+	`mirrored_location`,
+	`is_private`,
+	`is_fork`,
+	`forked_from`,
+	`has_issues`,
+	`is_starred`,
+	`is_archived`,
+	`size`,
+	`has_lfs`,
+	`has_submodules`,
+	`language`,
+	`description`,
+	`default_branch`,
+	`visibility`,
+	`status`,
+	`last_mirrored`,
+	`error_message`,
+	`destination_org`,
+	`metadata`,
+	`imported_at`,
+	`created_at`,
+	`updated_at`
+)
+SELECT
+	`repositories`.`id`,
+	`repositories`.`user_id`,
+	`repositories`.`config_id`,
+	`repositories`.`name`,
+	`repositories`.`full_name`,
+	`repositories`.`normalized_full_name`,
+	`repositories`.`url`,
+	`repositories`.`clone_url`,
+	`repositories`.`owner`,
+	`repositories`.`organization`,
+	`repositories`.`mirrored_location`,
+	`repositories`.`is_private`,
+	`repositories`.`is_fork`,
+	`repositories`.`forked_from`,
+	`repositories`.`has_issues`,
+	`repositories`.`is_starred`,
+	`repositories`.`is_archived`,
+	`repositories`.`size`,
+	`repositories`.`has_lfs`,
+	`repositories`.`has_submodules`,
+	`repositories`.`language`,
+	`repositories`.`description`,
+	`repositories`.`default_branch`,
+	`repositories`.`visibility`,
+	`repositories`.`status`,
+	`repositories`.`last_mirrored`,
+	`repositories`.`error_message`,
+	`repositories`.`destination_org`,
+	`repositories`.`metadata`,
+	COALESCE(
+		(
+			SELECT MIN(`mj`.`timestamp`)
+			FROM `mirror_jobs` `mj`
+			WHERE `mj`.`user_id` = `repositories`.`user_id`
+				AND `mj`.`status` = 'imported'
+				AND (
+					(`mj`.`repository_id` IS NOT NULL AND `mj`.`repository_id` = `repositories`.`id`)
+					OR (
+						`mj`.`repository_id` IS NULL
+						AND `mj`.`repository_name` IS NOT NULL
+						AND (
+							lower(trim(`mj`.`repository_name`)) = `repositories`.`normalized_full_name`
+							OR lower(trim(`mj`.`repository_name`)) = lower(trim(`repositories`.`name`))
+						)
+					)
+				)
+		),
+		`repositories`.`created_at`,
+		unixepoch()
+	) AS `imported_at`,
+	`repositories`.`created_at`,
+	`repositories`.`updated_at`
+FROM `repositories`;
+--> statement-breakpoint
+DROP TABLE `repositories`;
+--> statement-breakpoint
+ALTER TABLE `__new_repositories` RENAME TO `repositories`;
+--> statement-breakpoint
+CREATE INDEX `idx_repositories_user_id` ON `repositories` (`user_id`);
+--> statement-breakpoint
+CREATE INDEX `idx_repositories_config_id` ON `repositories` (`config_id`);
+--> statement-breakpoint
+CREATE INDEX `idx_repositories_status` ON `repositories` (`status`);
+--> statement-breakpoint
+CREATE INDEX `idx_repositories_owner` ON `repositories` (`owner`);
+--> statement-breakpoint
+CREATE INDEX `idx_repositories_organization` ON `repositories` (`organization`);
+--> statement-breakpoint
+CREATE INDEX `idx_repositories_is_fork` ON `repositories` (`is_fork`);
+--> statement-breakpoint
+CREATE INDEX `idx_repositories_is_starred` ON `repositories` (`is_starred`);
+--> statement-breakpoint
+CREATE INDEX `idx_repositories_user_imported_at` ON `repositories` (`user_id`,`imported_at`);
+--> statement-breakpoint
+CREATE UNIQUE INDEX `uniq_repositories_user_full_name` ON `repositories` (`user_id`,`full_name`);
+--> statement-breakpoint
+CREATE UNIQUE INDEX `uniq_repositories_user_normalized_full_name` ON `repositories` (`user_id`,`normalized_full_name`);

drizzle/0010_mirrored_location_index.sql

@@ -0,0 +1,9 @@
+-- Add index for mirroredLocation lookups (used by name collision detection)
+CREATE INDEX IF NOT EXISTS `idx_repositories_mirrored_location` ON `repositories` (`user_id`, `mirrored_location`);
+
+-- Add unique partial index to enforce that no two repos for the same user
+-- can claim the same non-empty mirroredLocation. This prevents race conditions
+-- during concurrent batch mirroring of starred repos with duplicate names.
+CREATE UNIQUE INDEX IF NOT EXISTS `uniq_repositories_user_mirrored_location`
+  ON `repositories` (`user_id`, `mirrored_location`)
+  WHERE `mirrored_location` != '';

drizzle/0011_notification_config.sql

@@ -0,0 +1 @@
+ALTER TABLE `configs` ADD `notification_config` text DEFAULT '{"enabled":false,"provider":"ntfy","notifyOnSyncError":true,"notifyOnSyncSuccess":false,"notifyOnNewRepo":false}' NOT NULL;

drizzle/meta/_journal.json

@@ -64,6 +64,27 @@
       "when": 1761802056073,
       "tag": "0008_serious_thena",
       "breakpoints": true
+    },
+    {
+      "idx": 9,
+      "version": "6",
+      "when": 1773542995732,
+      "tag": "0009_nervous_tyger_tiger",
+      "breakpoints": true
+    },
+    {
+      "idx": 10,
+      "version": "6",
+      "when": 1774054800000,
+      "tag": "0010_mirrored_location_index",
+      "breakpoints": true
+    },
+    {
+      "idx": 11,
+      "version": "6",
+      "when": 1774058400000,
+      "tag": "0011_notification_config",
+      "breakpoints": true
     }
   ]
-}
+}

flake.lock

@@ -1,8 +1,50 @@
 {
   "nodes": {
+    "bun2nix": {
+      "inputs": {
+        "flake-parts": "flake-parts",
+        "import-tree": "import-tree",
+        "nixpkgs": [
+          "nixpkgs"
+        ],
+        "systems": "systems",
+        "treefmt-nix": "treefmt-nix"
+      },
+      "locked": {
+        "lastModified": 1770895533,
+        "narHash": "sha256-v3QaK9ugy9bN9RXDnjw0i2OifKmz2NnKM82agtqm/UY=",
+        "owner": "nix-community",
+        "repo": "bun2nix",
+        "rev": "c843f477b15f51151f8c6bcc886954699440a6e1",
+        "type": "github"
+      },
+      "original": {
+        "owner": "nix-community",
+        "repo": "bun2nix",
+        "type": "github"
+      }
+    },
+    "flake-parts": {
+      "inputs": {
+        "nixpkgs-lib": "nixpkgs-lib"
+      },
+      "locked": {
+        "lastModified": 1769996383,
+        "narHash": "sha256-AnYjnFWgS49RlqX7LrC4uA+sCCDBj0Ry/WOJ5XWAsa0=",
+        "owner": "hercules-ci",
+        "repo": "flake-parts",
+        "rev": "57928607ea566b5db3ad13af0e57e921e6b12381",
+        "type": "github"
+      },
+      "original": {
+        "owner": "hercules-ci",
+        "repo": "flake-parts",
+        "type": "github"
+      }
+    },
     "flake-utils": {
       "inputs": {
-        "systems": "systems"
+        "systems": "systems_2"
       },
       "locked": {
         "lastModified": 1731533236,
@@ -18,6 +60,21 @@
         "type": "github"
       }
     },
+    "import-tree": {
+      "locked": {
+        "lastModified": 1763762820,
+        "narHash": "sha256-ZvYKbFib3AEwiNMLsejb/CWs/OL/srFQ8AogkebEPF0=",
+        "owner": "vic",
+        "repo": "import-tree",
+        "rev": "3c23749d8013ec6daa1d7255057590e9ca726646",
+        "type": "github"
+      },
+      "original": {
+        "owner": "vic",
+        "repo": "import-tree",
+        "type": "github"
+      }
+    },
     "nixpkgs": {
       "locked": {
         "lastModified": 1761672384,
@@ -34,8 +91,24 @@
         "type": "github"
       }
     },
+    "nixpkgs-lib": {
+      "locked": {
+        "lastModified": 1769909678,
+        "narHash": "sha256-cBEymOf4/o3FD5AZnzC3J9hLbiZ+QDT/KDuyHXVJOpM=",
+        "owner": "nix-community",
+        "repo": "nixpkgs.lib",
+        "rev": "72716169fe93074c333e8d0173151350670b824c",
+        "type": "github"
+      },
+      "original": {
+        "owner": "nix-community",
+        "repo": "nixpkgs.lib",
+        "type": "github"
+      }
+    },
     "root": {
       "inputs": {
+        "bun2nix": "bun2nix",
         "flake-utils": "flake-utils",
         "nixpkgs": "nixpkgs"
       }
@@ -54,6 +127,42 @@
         "repo": "default",
         "type": "github"
       }
+    },
+    "systems_2": {
+      "locked": {
+        "lastModified": 1681028828,
+        "narHash": "sha256-Vy1rq5AaRuLzOxct8nz4T6wlgyUR7zLU309k9mBC768=",
+        "owner": "nix-systems",
+        "repo": "default",
+        "rev": "da67096a3b9bf56a91d16901293e51ba5b49a27e",
+        "type": "github"
+      },
+      "original": {
+        "owner": "nix-systems",
+        "repo": "default",
+        "type": "github"
+      }
+    },
+    "treefmt-nix": {
+      "inputs": {
+        "nixpkgs": [
+          "bun2nix",
+          "nixpkgs"
+        ]
+      },
+      "locked": {
+        "lastModified": 1770228511,
+        "narHash": "sha256-wQ6NJSuFqAEmIg2VMnLdCnUc0b7vslUohqqGGD+Fyxk=",
+        "owner": "numtide",
+        "repo": "treefmt-nix",
+        "rev": "337a4fe074be1042a35086f15481d763b8ddc0e7",
+        "type": "github"
+      },
+      "original": {
+        "owner": "numtide",
+        "repo": "treefmt-nix",
+        "type": "github"
+      }
     }
   },
   "root": "root",

flake.nix

@@ -1,25 +1,43 @@
 {
   description = "Gitea Mirror - Self-hosted GitHub to Gitea mirroring service";
 
+  nixConfig = {
+    extra-substituters = [
+      "https://nix-community.cachix.org"
+    ];
+    extra-trusted-public-keys = [
+      "nix-community.cachix.org-1:mB9FSh9qf2dCimDSUo8Zy7bkq5CX+/rkCWyvRCYg3Fs="
+    ];
+  };
+
   inputs = {
     nixpkgs.url = "github:NixOS/nixpkgs/nixos-unstable";
     flake-utils.url = "github:numtide/flake-utils";
+    bun2nix = {
+      url = "github:nix-community/bun2nix";
+      inputs.nixpkgs.follows = "nixpkgs";
+    };
   };
 
-  outputs = { self, nixpkgs, flake-utils }:
-    flake-utils.lib.eachDefaultSystem (system:
+  outputs = { self, nixpkgs, flake-utils, bun2nix }:
+    let
+      forEachSystem = flake-utils.lib.eachDefaultSystem;
+    in
+    (forEachSystem (system:
       let
         pkgs = nixpkgs.legacyPackages.${system};
+        b2n = bun2nix.packages.${system}.default;
 
         # Build the application
         gitea-mirror = pkgs.stdenv.mkDerivation {
           pname = "gitea-mirror";
-          version = "3.8.11";
+          version = "3.14.1";
 
           src = ./.;
 
-          nativeBuildInputs = with pkgs; [
-            bun
+          nativeBuildInputs = [
+            pkgs.bun
+            b2n.hook
           ];
 
           buildInputs = with pkgs; [
@@ -27,21 +45,54 @@
             openssl
           ];
 
-          configurePhase = ''
-            export HOME=$TMPDIR
-            export BUN_INSTALL=$TMPDIR/.bun
-            export PATH=$BUN_INSTALL/bin:$PATH
-          '';
+          bunDeps = b2n.fetchBunDeps {
+            bunNix = ./bun.nix;
+          };
+
+          # bun2nix defaults to isolated installs on Linux, which can be
+          # very slow in CI for larger dependency trees and may appear stuck.
+          # Use hoisted linker and fail fast on lockfile drift.
+          bunInstallFlags = if pkgs.stdenv.hostPlatform.isDarwin then [
+            "--linker=hoisted"
+            "--backend=copyfile"
+            "--frozen-lockfile"
+            "--no-progress"
+          ] else [
+            "--linker=hoisted"
+            "--frozen-lockfile"
+            "--no-progress"
+          ];
+
+          # Let the bun2nix hook handle dependency installation via the
+          # pre-fetched cache, but skip its default build/check/install
+          # phases since we have custom ones.
+          dontUseBunBuild = true;
+          dontUseBunCheck = true;
+          dontUseBunInstall = true;
 
           buildPhase = ''
-            # Install dependencies
-            bun install --frozen-lockfile --no-progress
+            runHook preBuild
+            export HOME=$TMPDIR
 
-            # Build the application
+            # The bun2nix cache is in the read-only Nix store, but bunx/astro
+            # may try to write to it at build time. Copy the cache to a
+            # writable location.
+            if [ -n "$BUN_INSTALL_CACHE_DIR" ] && [ -d "$BUN_INSTALL_CACHE_DIR" ]; then
+              WRITABLE_CACHE="$TMPDIR/bun-cache"
+              cp -rL "$BUN_INSTALL_CACHE_DIR" "$WRITABLE_CACHE" 2>/dev/null || true
+              chmod -R u+w "$WRITABLE_CACHE" 2>/dev/null || true
+              export BUN_INSTALL_CACHE_DIR="$WRITABLE_CACHE"
+            fi
+
+            # Build the Astro application
             bun run build
+
+            runHook postBuild
           '';
 
           installPhase = ''
+            runHook preInstall
+
             mkdir -p $out/lib/gitea-mirror
             mkdir -p $out/bin
 
@@ -49,11 +100,14 @@
             cp -r dist $out/lib/gitea-mirror/
             cp -r node_modules $out/lib/gitea-mirror/
             cp -r scripts $out/lib/gitea-mirror/
+            cp -r src $out/lib/gitea-mirror/
+            cp -r drizzle $out/lib/gitea-mirror/
             cp package.json $out/lib/gitea-mirror/
+            cp tsconfig.json $out/lib/gitea-mirror/
 
             # Create entrypoint script that matches Docker behavior
             cat > $out/bin/gitea-mirror <<'EOF'
-#!/usr/bin/env bash
+#!${pkgs.bash}/bin/bash
 set -e
 
 # === DEFAULT CONFIGURATION ===
@@ -75,7 +129,19 @@ export MIRROR_PULL_REQUEST_CONCURRENCY=''${MIRROR_PULL_REQUEST_CONCURRENCY:-5}
 
 # Create data directory
 mkdir -p "$DATA_DIR"
-cd $out/lib/gitea-mirror
+SCRIPT_DIR="$(cd "$(dirname "$0")" && pwd)"
+APP_DIR="$SCRIPT_DIR/../lib/gitea-mirror"
+
+# The app uses process.cwd()/data for the database, but the Nix store
+# is read-only. Create a writable working directory with symlinks to
+# the app files and a real data directory.
+WORK_DIR="$DATA_DIR/.workdir"
+mkdir -p "$WORK_DIR"
+for item in dist node_modules scripts src drizzle package.json tsconfig.json; do
+  ln -sfn "$APP_DIR/$item" "$WORK_DIR/$item"
+done
+ln -sfn "$DATA_DIR" "$WORK_DIR/data"
+cd "$WORK_DIR"
 
 # === AUTO-GENERATE SECRETS ===
 BETTER_AUTH_SECRET_FILE="$DATA_DIR/.better_auth_secret"
@@ -112,7 +178,7 @@ if [ -z "$ENCRYPTION_SECRET" ]; then
 fi
 
 # === DATABASE INITIALIZATION ===
-DB_PATH=$(echo "$DATABASE_URL" | sed 's|^file:||')
+DB_PATH=$(echo "$DATABASE_URL" | ${pkgs.gnused}/bin/sed 's|^file:||')
 if [ ! -f "$DB_PATH" ]; then
   echo "Database not found. It will be created and initialized via Drizzle migrations on first app startup..."
   touch "$DB_PATH"
@@ -123,25 +189,25 @@ fi
 # === STARTUP SCRIPTS ===
 # Initialize configuration from environment variables
 echo "Checking for environment configuration..."
-if [ -f "dist/scripts/startup-env-config.js" ]; then
+if [ -f "scripts/startup-env-config.ts" ]; then
   echo "Loading configuration from environment variables..."
-  ${pkgs.bun}/bin/bun dist/scripts/startup-env-config.js && \
+  ${pkgs.bun}/bin/bun scripts/startup-env-config.ts && \
     echo "✅ Environment configuration loaded successfully" || \
     echo "⚠️  Environment configuration loading completed with warnings"
 fi
 
 # Run startup recovery
 echo "Running startup recovery..."
-if [ -f "dist/scripts/startup-recovery.js" ]; then
-  ${pkgs.bun}/bin/bun dist/scripts/startup-recovery.js --timeout=30000 && \
+if [ -f "scripts/startup-recovery.ts" ]; then
+  ${pkgs.bun}/bin/bun scripts/startup-recovery.ts --timeout=30000 && \
     echo "✅ Startup recovery completed successfully" || \
     echo "⚠️  Startup recovery completed with warnings"
 fi
 
 # Run repository status repair
 echo "Running repository status repair..."
-if [ -f "dist/scripts/repair-mirrored-repos.js" ]; then
-  ${pkgs.bun}/bin/bun dist/scripts/repair-mirrored-repos.js --startup && \
+if [ -f "scripts/repair-mirrored-repos.ts" ]; then
+  ${pkgs.bun}/bin/bun scripts/repair-mirrored-repos.ts --startup && \
     echo "✅ Repository status repair completed successfully" || \
     echo "⚠️  Repository status repair completed with warnings"
 fi
@@ -170,13 +236,16 @@ EOF
 
             # Create database management helper
             cat > $out/bin/gitea-mirror-db <<'EOF'
-#!/usr/bin/env bash
+#!${pkgs.bash}/bin/bash
 export DATA_DIR=''${DATA_DIR:-"$HOME/.local/share/gitea-mirror"}
 mkdir -p "$DATA_DIR"
-cd $out/lib/gitea-mirror
+SCRIPT_DIR="$(cd "$(dirname "$0")" && pwd)"
+cd "$SCRIPT_DIR/../lib/gitea-mirror"
 exec ${pkgs.bun}/bin/bun scripts/manage-db.ts "$@"
 EOF
             chmod +x $out/bin/gitea-mirror-db
+
+            runHook postInstall
           '';
 
           meta = with pkgs.lib; {
@@ -201,6 +270,7 @@ EOF
             bun
             sqlite
             openssl
+            b2n
           ];
 
           shellHook = ''
@@ -211,182 +281,185 @@ EOF
             echo "  bun run dev       # Start development server"
             echo "  bun run build     # Build for production"
             echo ""
+            echo "Nix packaging:"
+            echo "  bun2nix -o bun.nix  # Regenerate bun.nix after dependency changes"
+            echo "  nix build           # Build the package"
+            echo ""
             echo "Database:"
             echo "  bun run manage-db init   # Initialize database"
             echo "  bun run db:studio        # Open Drizzle Studio"
           '';
         };
 
-        # NixOS module
-        nixosModules.default = { config, lib, pkgs, ... }:
-          with lib;
-          let
-            cfg = config.services.gitea-mirror;
-          in {
-            options.services.gitea-mirror = {
-              enable = mkEnableOption "Gitea Mirror service";
+      }
+    )) // {
+      nixosModules.default = { config, lib, pkgs, ... }:
+        with lib;
+        let
+          cfg = config.services.gitea-mirror;
+        in {
+          options.services.gitea-mirror = {
+            enable = mkEnableOption "Gitea Mirror service";
 
-              package = mkOption {
-                type = types.package;
-                default = self.packages.${system}.default;
-                description = "The Gitea Mirror package to use";
-              };
-
-              dataDir = mkOption {
-                type = types.path;
-                default = "/var/lib/gitea-mirror";
-                description = "Directory to store data and database";
-              };
-
-              user = mkOption {
-                type = types.str;
-                default = "gitea-mirror";
-                description = "User account under which Gitea Mirror runs";
-              };
-
-              group = mkOption {
-                type = types.str;
-                default = "gitea-mirror";
-                description = "Group under which Gitea Mirror runs";
-              };
-
-              host = mkOption {
-                type = types.str;
-                default = "0.0.0.0";
-                description = "Host to bind to";
-              };
-
-              port = mkOption {
-                type = types.port;
-                default = 4321;
-                description = "Port to listen on";
-              };
-
-              betterAuthUrl = mkOption {
-                type = types.str;
-                default = "http://localhost:4321";
-                description = "Better Auth URL (external URL of the service)";
-              };
-
-              betterAuthTrustedOrigins = mkOption {
-                type = types.str;
-                default = "http://localhost:4321";
-                description = "Comma-separated list of trusted origins for Better Auth";
-              };
-
-              mirrorIssueConcurrency = mkOption {
-                type = types.int;
-                default = 3;
-                description = "Number of concurrent issue mirror operations (set to 1 for perfect ordering)";
-              };
-
-              mirrorPullRequestConcurrency = mkOption {
-                type = types.int;
-                default = 5;
-                description = "Number of concurrent PR mirror operations (set to 1 for perfect ordering)";
-              };
-
-              environmentFile = mkOption {
-                type = types.nullOr types.path;
-                default = null;
-                description = ''
-                  Path to file containing environment variables.
-                  Only needed if you want to set BETTER_AUTH_SECRET or ENCRYPTION_SECRET manually.
-                  Otherwise, secrets will be auto-generated and stored in the data directory.
-
-                  Example:
-                    BETTER_AUTH_SECRET=your-32-character-secret-here
-                    ENCRYPTION_SECRET=your-encryption-secret-here
-                '';
-              };
-
-              openFirewall = mkOption {
-                type = types.bool;
-                default = false;
-                description = "Open the firewall for the specified port";
-              };
+            package = mkOption {
+              type = types.package;
+              default = self.packages.${pkgs.system}.default;
+              description = "The Gitea Mirror package to use";
             };
 
-            config = mkIf cfg.enable {
-              users.users.${cfg.user} = {
-                isSystemUser = true;
-                group = cfg.group;
-                home = cfg.dataDir;
-                createHome = true;
-              };
+            dataDir = mkOption {
+              type = types.path;
+              default = "/var/lib/gitea-mirror";
+              description = "Directory to store data and database";
+            };
 
-              users.groups.${cfg.group} = {};
+            user = mkOption {
+              type = types.str;
+              default = "gitea-mirror";
+              description = "User account under which Gitea Mirror runs";
+            };
 
-              systemd.services.gitea-mirror = {
-                description = "Gitea Mirror - GitHub to Gitea mirroring service";
-                after = [ "network.target" ];
-                wantedBy = [ "multi-user.target" ];
+            group = mkOption {
+              type = types.str;
+              default = "gitea-mirror";
+              description = "Group under which Gitea Mirror runs";
+            };
 
-                environment = {
-                  DATA_DIR = cfg.dataDir;
-                  DATABASE_URL = "file:${cfg.dataDir}/gitea-mirror.db";
-                  HOST = cfg.host;
-                  PORT = toString cfg.port;
-                  NODE_ENV = "production";
-                  BETTER_AUTH_URL = cfg.betterAuthUrl;
-                  BETTER_AUTH_TRUSTED_ORIGINS = cfg.betterAuthTrustedOrigins;
-                  PUBLIC_BETTER_AUTH_URL = cfg.betterAuthUrl;
-                  MIRROR_ISSUE_CONCURRENCY = toString cfg.mirrorIssueConcurrency;
-                  MIRROR_PULL_REQUEST_CONCURRENCY = toString cfg.mirrorPullRequestConcurrency;
-                };
+            host = mkOption {
+              type = types.str;
+              default = "0.0.0.0";
+              description = "Host to bind to";
+            };
 
-                serviceConfig = {
-                  Type = "simple";
-                  User = cfg.user;
-                  Group = cfg.group;
-                  ExecStart = "${cfg.package}/bin/gitea-mirror";
-                  Restart = "always";
-                  RestartSec = "10s";
+            port = mkOption {
+              type = types.port;
+              default = 4321;
+              description = "Port to listen on";
+            };
 
-                  # Security hardening
-                  NoNewPrivileges = true;
-                  PrivateTmp = true;
-                  ProtectSystem = "strict";
-                  ProtectHome = true;
-                  ReadWritePaths = [ cfg.dataDir ];
+            betterAuthUrl = mkOption {
+              type = types.str;
+              default = "http://localhost:4321";
+              description = "Better Auth URL (external URL of the service)";
+            };
 
-                  # Load environment file if specified (optional)
-                  EnvironmentFile = mkIf (cfg.environmentFile != null) cfg.environmentFile;
+            betterAuthTrustedOrigins = mkOption {
+              type = types.str;
+              default = "http://localhost:4321";
+              description = "Comma-separated list of trusted origins for Better Auth";
+            };
 
-                  # Graceful shutdown
-                  TimeoutStopSec = "30s";
-                  KillMode = "mixed";
-                  KillSignal = "SIGTERM";
-                };
-              };
+            mirrorIssueConcurrency = mkOption {
+              type = types.int;
+              default = 3;
+              description = "Number of concurrent issue mirror operations (set to 1 for perfect ordering)";
+            };
 
-              # Health check timer (optional monitoring)
-              systemd.timers.gitea-mirror-healthcheck = mkIf cfg.enable {
-                description = "Gitea Mirror health check timer";
-                wantedBy = [ "timers.target" ];
-                timerConfig = {
-                  OnBootSec = "5min";
-                  OnUnitActiveSec = "5min";
-                };
-              };
+            mirrorPullRequestConcurrency = mkOption {
+              type = types.int;
+              default = 5;
+              description = "Number of concurrent PR mirror operations (set to 1 for perfect ordering)";
+            };
 
-              systemd.services.gitea-mirror-healthcheck = mkIf cfg.enable {
-                description = "Gitea Mirror health check";
-                after = [ "gitea-mirror.service" ];
-                serviceConfig = {
-                  Type = "oneshot";
-                  ExecStart = "${pkgs.curl}/bin/curl -f http://${cfg.host}:${toString cfg.port}/api/health || true";
-                  User = "nobody";
-                };
-              };
+            environmentFile = mkOption {
+              type = types.nullOr types.path;
+              default = null;
+              description = ''
+                Path to file containing environment variables.
+                Only needed if you want to set BETTER_AUTH_SECRET or ENCRYPTION_SECRET manually.
+                Otherwise, secrets will be auto-generated and stored in the data directory.
 
-              networking.firewall = mkIf cfg.openFirewall {
-                allowedTCPPorts = [ cfg.port ];
-              };
+                Example:
+                  BETTER_AUTH_SECRET=your-32-character-secret-here
+                  ENCRYPTION_SECRET=your-encryption-secret-here
+              '';
+            };
+
+            openFirewall = mkOption {
+              type = types.bool;
+              default = false;
+              description = "Open the firewall for the specified port";
             };
           };
-      }
-    ) // {
+
+          config = mkIf cfg.enable {
+            users.users.${cfg.user} = {
+              isSystemUser = true;
+              group = cfg.group;
+              home = cfg.dataDir;
+              createHome = true;
+            };
+
+            users.groups.${cfg.group} = {};
+
+            systemd.services.gitea-mirror = {
+              description = "Gitea Mirror - GitHub to Gitea mirroring service";
+              after = [ "network.target" ];
+              wantedBy = [ "multi-user.target" ];
+
+              environment = {
+                DATA_DIR = cfg.dataDir;
+                DATABASE_URL = "file:${cfg.dataDir}/gitea-mirror.db";
+                HOST = cfg.host;
+                PORT = toString cfg.port;
+                NODE_ENV = "production";
+                BETTER_AUTH_URL = cfg.betterAuthUrl;
+                BETTER_AUTH_TRUSTED_ORIGINS = cfg.betterAuthTrustedOrigins;
+                PUBLIC_BETTER_AUTH_URL = cfg.betterAuthUrl;
+                MIRROR_ISSUE_CONCURRENCY = toString cfg.mirrorIssueConcurrency;
+                MIRROR_PULL_REQUEST_CONCURRENCY = toString cfg.mirrorPullRequestConcurrency;
+              };
+
+              serviceConfig = {
+                Type = "simple";
+                User = cfg.user;
+                Group = cfg.group;
+                ExecStart = "${cfg.package}/bin/gitea-mirror";
+                Restart = "always";
+                RestartSec = "10s";
+
+                # Security hardening
+                NoNewPrivileges = true;
+                PrivateTmp = true;
+                ProtectSystem = "strict";
+                ProtectHome = true;
+                ReadWritePaths = [ cfg.dataDir ];
+
+                # Graceful shutdown
+                TimeoutStopSec = "30s";
+                KillMode = "mixed";
+                KillSignal = "SIGTERM";
+              } // optionalAttrs (cfg.environmentFile != null) {
+                EnvironmentFile = cfg.environmentFile;
+              };
+            };
+
+            # Health check timer (optional monitoring)
+            systemd.timers.gitea-mirror-healthcheck = {
+              description = "Gitea Mirror health check timer";
+              wantedBy = [ "timers.target" ];
+              timerConfig = {
+                OnBootSec = "5min";
+                OnUnitActiveSec = "5min";
+              };
+            };
+
+            systemd.services.gitea-mirror-healthcheck = {
+              description = "Gitea Mirror health check";
+              after = [ "gitea-mirror.service" ];
+              serviceConfig = {
+                Type = "oneshot";
+                ExecStart = "${pkgs.bash}/bin/bash -c '${pkgs.curl}/bin/curl -f http://127.0.0.1:${toString cfg.port}/api/health || true'";
+                User = "nobody";
+              };
+            };
+
+            networking.firewall = mkIf cfg.openFirewall {
+              allowedTCPPorts = [ cfg.port ];
+            };
+          };
+        };
+
       # Overlay for adding to nixpkgs
       overlays.default = final: prev: {
         gitea-mirror = self.packages.${final.system}.default;

package.json

@@ -1,7 +1,7 @@
 {
   "name": "gitea-mirror",
   "type": "module",
-  "version": "3.9.4",
+  "version": "3.16.0",
   "engines": {
     "bun": ">=1.2.9"
   },
@@ -31,23 +31,34 @@
     "test-shutdown": "bun scripts/test-graceful-shutdown.ts",
     "test-shutdown-cleanup": "bun scripts/test-graceful-shutdown.ts --cleanup",
     "preview": "bunx --bun astro preview",
-    "start": "bun dist/server/entry.mjs",
-    "start:fresh": "bun run cleanup-db && bun run manage-db init && bun dist/server/entry.mjs",
+    "start": "bun scripts/runtime-server.ts",
+    "start:fresh": "bun run cleanup-db && bun run manage-db init && bun scripts/runtime-server.ts",
     "test": "bun test",
+    "test:migrations": "bun scripts/validate-migrations.ts",
     "test:watch": "bun test --watch",
     "test:coverage": "bun test --coverage",
+    "test:e2e": "bash tests/e2e/run-e2e.sh",
+    "test:e2e:ci": "bash tests/e2e/run-e2e.sh --ci",
+    "test:e2e:keep": "bash tests/e2e/run-e2e.sh --keep",
+    "test:e2e:cleanup": "bash tests/e2e/cleanup.sh",
     "astro": "bunx --bun astro"
   },
   "overrides": {
     "@esbuild-kit/esm-loader": "npm:tsx@^4.21.0",
-    "devalue": "^5.5.0"
+    "@xmldom/xmldom": "^0.8.13",
+    "devalue": "^5.8.1",
+    "fast-uri": "^3.1.2",
+    "fast-xml-builder": "^1.1.7",
+    "kysely": "^0.28.17",
+    "lodash": "^4.18.1",
+    "picomatch": "^4.0.4"
   },
   "dependencies": {
-    "@astrojs/check": "^0.9.6",
-    "@astrojs/mdx": "4.3.13",
-    "@astrojs/node": "9.5.4",
-    "@astrojs/react": "^4.4.2",
-    "@better-auth/sso": "1.4.19",
+    "@astrojs/check": "^0.9.7",
+    "@astrojs/mdx": "5.0.0",
+    "@astrojs/node": "10.0.1",
+    "@astrojs/react": "^5.0.0",
+    "@better-auth/sso": "1.5.5",
     "@octokit/plugin-throttling": "^11.0.3",
     "@octokit/rest": "^22.0.1",
     "@radix-ui/react-accordion": "^1.2.12",
@@ -69,23 +80,25 @@
     "@radix-ui/react-tabs": "^1.1.13",
     "@radix-ui/react-tooltip": "^1.2.8",
     "@tailwindcss/vite": "^4.2.1",
+    "@tanstack/react-table": "^8.21.3",
     "@tanstack/react-virtual": "^3.13.19",
     "@types/canvas-confetti": "^1.9.0",
     "@types/react": "^19.2.14",
     "@types/react-dom": "^19.2.3",
-    "astro": "^5.17.3",
+    "astro": "^6.0.4",
     "bcryptjs": "^3.0.3",
+    "better-auth": "1.5.5",
     "buffer": "^6.0.3",
-    "better-auth": "1.4.19",
     "canvas-confetti": "^1.9.4",
     "class-variance-authority": "^0.7.1",
     "clsx": "^2.1.1",
     "cmdk": "^1.1.1",
     "dotenv": "^17.3.1",
-    "drizzle-orm": "^0.45.1",
+    "drizzle-orm": "^0.45.2",
     "fuse.js": "^7.1.0",
     "jsonwebtoken": "^9.0.3",
-    "lucide-react": "^0.575.0",
+    "lucide-react": "^0.577.0",
+    "nanoid": "^5.1.6",
     "next-themes": "^0.4.6",
     "react": "^19.2.4",
     "react-dom": "^19.2.4",
@@ -100,17 +113,19 @@
     "zod": "^4.3.6"
   },
   "devDependencies": {
+    "@playwright/test": "^1.58.2",
     "@testing-library/jest-dom": "^6.9.1",
     "@testing-library/react": "^16.3.2",
     "@types/bcryptjs": "^3.0.0",
-    "@types/bun": "^1.3.9",
+    "@types/bun": "^1.3.10",
     "@types/jsonwebtoken": "^9.0.10",
+    "@types/node": "^25.5.0",
     "@types/uuid": "^11.0.0",
-    "@vitejs/plugin-react": "^5.1.4",
+    "@vitejs/plugin-react": "^6.0.1",
     "drizzle-kit": "^0.31.9",
     "jsdom": "^28.1.0",
     "tsx": "^4.21.0",
-    "vitest": "^4.0.18"
+    "vitest": "^4.1.0"
   },
-  "packageManager": "bun@1.3.3"
+  "packageManager": "bun@1.3.10"
 }

scripts/repair-mirrored-repos.ts

@@ -15,33 +15,40 @@ import { repoStatusEnum } from "@/types/Repository";
 const isDryRun = process.argv.includes("--dry-run");
 const specificRepo = process.argv.find(arg => arg.startsWith("--repo-name="))?.split("=")[1];
 const isStartupMode = process.argv.includes("--startup");
+const requestTimeoutMs = parsePositiveInteger(process.env.GITEA_REPAIR_REQUEST_TIMEOUT_MS, 15000);
+const progressInterval = parsePositiveInteger(process.env.GITEA_REPAIR_PROGRESS_INTERVAL, 100);
 
-async function checkRepoInGitea(config: any, owner: string, repoName: string): Promise<boolean> {
-  try {
-    if (!config.giteaConfig?.url || !config.giteaConfig?.token) {
-      return false;
-    }
+type GiteaLookupResult = {
+  exists: boolean;
+  details: any | null;
+  timedOut: boolean;
+  error: string | null;
+};
 
-    const response = await fetch(
-      `${config.giteaConfig.url}/api/v1/repos/${owner}/${repoName}`,
-      {
-        headers: {
-          Authorization: `token ${config.giteaConfig.token}`,
-        },
-      }
-    );
-
-    return response.ok;
-  } catch (error) {
-    console.error(`Error checking repo ${owner}/${repoName} in Gitea:`, error);
-    return false;
+function parsePositiveInteger(value: string | undefined, fallback: number): number {
+  const parsed = Number.parseInt(value ?? "", 10);
+  if (!Number.isFinite(parsed) || parsed <= 0) {
+    return fallback;
   }
+  return parsed;
 }
 
-async function getRepoDetailsFromGitea(config: any, owner: string, repoName: string): Promise<any> {
+function isTimeoutError(error: unknown): boolean {
+  if (!(error instanceof Error)) {
+    return false;
+  }
+  return error.name === "TimeoutError" || error.name === "AbortError";
+}
+
+async function getRepoDetailsFromGitea(config: any, owner: string, repoName: string): Promise<GiteaLookupResult> {
   try {
     if (!config.giteaConfig?.url || !config.giteaConfig?.token) {
-      return null;
+      return {
+        exists: false,
+        details: null,
+        timedOut: false,
+        error: "Missing Gitea URL or token in config",
+      };
     }
 
     const response = await fetch(
@@ -50,16 +57,41 @@ async function getRepoDetailsFromGitea(config: any, owner: string, repoName: str
         headers: {
           Authorization: `token ${config.giteaConfig.token}`,
         },
+        signal: AbortSignal.timeout(requestTimeoutMs),
       }
     );
 
     if (response.ok) {
-      return await response.json();
+      return {
+        exists: true,
+        details: await response.json(),
+        timedOut: false,
+        error: null,
+      };
     }
-    return null;
+
+    if (response.status === 404) {
+      return {
+        exists: false,
+        details: null,
+        timedOut: false,
+        error: null,
+      };
+    }
+
+    return {
+      exists: false,
+      details: null,
+      timedOut: false,
+      error: `Gitea API returned HTTP ${response.status}`,
+    };
   } catch (error) {
-    console.error(`Error getting repo details for ${owner}/${repoName}:`, error);
-    return null;
+    return {
+      exists: false,
+      details: null,
+      timedOut: isTimeoutError(error),
+      error: error instanceof Error ? error.message : String(error),
+    };
   }
 }
 
@@ -99,6 +131,8 @@ async function repairMirroredRepositories() {
       .from(repositories)
       .where(whereConditions);
 
+    const totalRepos = repos.length;
+
     if (repos.length === 0) {
       if (!isStartupMode) {
         console.log("✅ No repositories found that need repair");
@@ -109,13 +143,25 @@ async function repairMirroredRepositories() {
     if (!isStartupMode) {
       console.log(`📋 Found ${repos.length} repositories to check:`);
       console.log("");
+    } else {
+      console.log(`Checking ${totalRepos} repositories for status inconsistencies...`);
+      console.log(`Request timeout: ${requestTimeoutMs}ms | Progress interval: every ${progressInterval} repositories`);
     }
 
+    const startedAt = Date.now();
+    const configCache = new Map<string, any>();
+    let checkedCount = 0;
     let repairedCount = 0;
     let skippedCount = 0;
     let errorCount = 0;
+    let timeoutCount = 0;
+    let giteaErrorCount = 0;
+    let giteaErrorSamples = 0;
+    let startupSkipWarningCount = 0;
 
     for (const repo of repos) {
+      checkedCount++;
+
       if (!isStartupMode) {
         console.log(`🔍 Checking repository: ${repo.name}`);
         console.log(`   Current status: ${repo.status}`);
@@ -124,13 +170,29 @@ async function repairMirroredRepositories() {
 
       try {
         // Get user configuration
-        const config = await db
-          .select()
-          .from(configs)
-          .where(eq(configs.id, repo.configId))
-          .limit(1);
+        const configKey = String(repo.configId);
+        let userConfig = configCache.get(configKey);
 
-        if (config.length === 0) {
+        if (!userConfig) {
+          const config = await db
+            .select()
+            .from(configs)
+            .where(eq(configs.id, repo.configId))
+            .limit(1);
+
+          if (config.length === 0) {
+            if (!isStartupMode) {
+              console.log(`   ❌ No configuration found for repository`);
+            }
+            errorCount++;
+            continue;
+          }
+
+          userConfig = config[0];
+          configCache.set(configKey, userConfig);
+        }
+
+        if (!userConfig) {
           if (!isStartupMode) {
             console.log(`   ❌ No configuration found for repository`);
           }
@@ -138,7 +200,6 @@ async function repairMirroredRepositories() {
           continue;
         }
 
-        const userConfig = config[0];
         const giteaUsername = userConfig.giteaConfig?.defaultOwner;
 
         if (!giteaUsername) {
@@ -153,25 +214,59 @@ async function repairMirroredRepositories() {
         let existsInGitea = false;
         let actualOwner = giteaUsername;
         let giteaRepoDetails = null;
+        let repoRequestTimedOut = false;
+        let repoRequestErrored = false;
 
         // First check user location
-        existsInGitea = await checkRepoInGitea(userConfig, giteaUsername, repo.name);
-        if (existsInGitea) {
-          giteaRepoDetails = await getRepoDetailsFromGitea(userConfig, giteaUsername, repo.name);
+        const userLookup = await getRepoDetailsFromGitea(userConfig, giteaUsername, repo.name);
+        existsInGitea = userLookup.exists;
+        giteaRepoDetails = userLookup.details;
+
+        if (userLookup.timedOut) {
+          timeoutCount++;
+          repoRequestTimedOut = true;
+        } else if (userLookup.error) {
+          giteaErrorCount++;
+          repoRequestErrored = true;
+          if (!isStartupMode || giteaErrorSamples < 3) {
+            console.log(`   ⚠️  Gitea lookup issue for ${giteaUsername}/${repo.name}: ${userLookup.error}`);
+            giteaErrorSamples++;
+          }
         }
 
         // If not found in user location and repo has organization, check organization
         if (!existsInGitea && repo.organization) {
-          existsInGitea = await checkRepoInGitea(userConfig, repo.organization, repo.name);
+          const orgLookup = await getRepoDetailsFromGitea(userConfig, repo.organization, repo.name);
+          existsInGitea = orgLookup.exists;
           if (existsInGitea) {
             actualOwner = repo.organization;
-            giteaRepoDetails = await getRepoDetailsFromGitea(userConfig, repo.organization, repo.name);
+            giteaRepoDetails = orgLookup.details;
+          }
+
+          if (orgLookup.timedOut) {
+            timeoutCount++;
+            repoRequestTimedOut = true;
+          } else if (orgLookup.error) {
+            giteaErrorCount++;
+            repoRequestErrored = true;
+            if (!isStartupMode || giteaErrorSamples < 3) {
+              console.log(`   ⚠️  Gitea lookup issue for ${repo.organization}/${repo.name}: ${orgLookup.error}`);
+              giteaErrorSamples++;
+            }
           }
         }
 
         if (!existsInGitea) {
           if (!isStartupMode) {
             console.log(`   ⏭️  Repository not found in Gitea - skipping`);
+          } else if (repoRequestTimedOut || repoRequestErrored) {
+            if (startupSkipWarningCount < 3) {
+              console.log(`   ⚠️  Skipping ${repo.name}; Gitea was slow/unreachable during lookup`);
+              startupSkipWarningCount++;
+              if (startupSkipWarningCount === 3) {
+                console.log(`   ℹ️  Additional slow/unreachable lookup warnings suppressed; progress logs will continue`);
+              }
+            }
           }
           skippedCount++;
           continue;
@@ -241,22 +336,43 @@ async function repairMirroredRepositories() {
 
       if (!isStartupMode) {
         console.log("");
+      } else if (checkedCount % progressInterval === 0 || checkedCount === totalRepos) {
+        const elapsedSeconds = Math.floor((Date.now() - startedAt) / 1000);
+        console.log(
+          `Repair progress: ${checkedCount}/${totalRepos} checked | repaired=${repairedCount}, skipped=${skippedCount}, errors=${errorCount}, timeouts=${timeoutCount} | elapsed=${elapsedSeconds}s`
+        );
       }
     }
 
     if (isStartupMode) {
-      // In startup mode, only log if there were repairs or errors
+      const elapsedSeconds = Math.floor((Date.now() - startedAt) / 1000);
+      console.log(
+        `Repository repair summary: checked=${checkedCount}, repaired=${repairedCount}, skipped=${skippedCount}, errors=${errorCount}, timeouts=${timeoutCount}, elapsed=${elapsedSeconds}s`
+      );
       if (repairedCount > 0) {
         console.log(`Repaired ${repairedCount} repository status inconsistencies`);
       }
       if (errorCount > 0) {
         console.log(`Warning: ${errorCount} repositories had errors during repair`);
       }
+      if (timeoutCount > 0) {
+        console.log(
+          `Warning: ${timeoutCount} Gitea API requests timed out. Increase GITEA_REPAIR_REQUEST_TIMEOUT_MS if your Gitea instance is under heavy load.`
+        );
+      }
+      if (giteaErrorCount > 0) {
+        console.log(`Warning: ${giteaErrorCount} Gitea API requests failed with non-timeout errors.`);
+      }
     } else {
       console.log("📊 Repair Summary:");
+      console.log(`   Checked: ${checkedCount}`);
       console.log(`   Repaired: ${repairedCount}`);
       console.log(`   Skipped: ${skippedCount}`);
       console.log(`   Errors: ${errorCount}`);
+      console.log(`   Timeouts: ${timeoutCount}`);
+      if (giteaErrorCount > 0) {
+        console.log(`   Gitea API Errors: ${giteaErrorCount}`);
+      }
 
       if (isDryRun && repairedCount > 0) {
         console.log("");

scripts/runtime-server.ts

@@ -0,0 +1,76 @@
+import { createServer } from "node:http";
+import type { IncomingMessage, ServerResponse } from "node:http";
+
+function normalizeBasePath(basePath: string | undefined): string {
+  if (!basePath || !basePath.trim()) {
+    return "/";
+  }
+
+  let normalized = basePath.trim();
+  if (!normalized.startsWith("/")) {
+    normalized = `/${normalized}`;
+  }
+
+  normalized = normalized.replace(/\/+$/, "");
+  return normalized || "/";
+}
+
+function rewriteRequestUrl(rawUrl: string, basePath: string): string | null {
+  if (basePath === "/") {
+    return rawUrl;
+  }
+
+  const url = new URL(rawUrl, "http://localhost");
+  const pathname = url.pathname;
+
+  if (pathname === basePath || pathname === `${basePath}/`) {
+    url.pathname = "/";
+    return `${url.pathname}${url.search}`;
+  }
+
+  if (pathname.startsWith(`${basePath}/`)) {
+    url.pathname = pathname.slice(basePath.length) || "/";
+    return `${url.pathname}${url.search}`;
+  }
+
+  return null;
+}
+
+const basePath = normalizeBasePath(process.env.BASE_URL);
+const host = process.env.HOST || "0.0.0.0";
+const port = Number.parseInt(process.env.PORT || "4321", 10);
+
+process.env.ASTRO_NODE_AUTOSTART = "disabled";
+const { handler } = await import("../dist/server/entry.mjs");
+
+const server = createServer((req: IncomingMessage, res: ServerResponse) => {
+  if (!req.url) {
+    res.statusCode = 400;
+    res.end("Bad Request");
+    return;
+  }
+
+  const rewrittenUrl = rewriteRequestUrl(req.url, basePath);
+  if (rewrittenUrl === null) {
+    res.statusCode = 404;
+    res.end("Not Found");
+    return;
+  }
+
+  req.url = rewrittenUrl;
+  req.headers["x-gitea-mirror-base-rewritten"] = "1";
+
+  Promise.resolve((handler as unknown as (request: IncomingMessage, response: ServerResponse) => unknown)(req, res)).catch((error) => {
+    console.error("Unhandled runtime server error:", error);
+    if (!res.headersSent) {
+      res.statusCode = 500;
+      res.end("Internal Server Error");
+    } else {
+      res.end();
+    }
+  });
+});
+
+server.listen(port, host, () => {
+  console.log(`Runtime server listening on http://${host}:${port} (BASE_URL=${basePath})`);
+});

scripts/validate-migrations.ts

@@ -0,0 +1,265 @@
+#!/usr/bin/env bun
+
+import { Database } from "bun:sqlite";
+import { readFileSync } from "fs";
+import path from "path";
+
+type JournalEntry = {
+  idx: number;
+  tag: string;
+  when: number;
+  breakpoints: boolean;
+};
+
+type Migration = {
+  entry: JournalEntry;
+  statements: string[];
+};
+
+type UpgradeFixture = {
+  seed: (db: Database) => void;
+  verify: (db: Database) => void;
+};
+
+type TableInfoRow = {
+  cid: number;
+  name: string;
+  type: string;
+  notnull: number;
+  dflt_value: string | null;
+  pk: number;
+};
+
+const migrationsFolder = path.join(process.cwd(), "drizzle");
+const migrations = loadMigrations();
+const latestMigration = migrations.at(-1);
+
+/**
+ * Known SQLite limitations that Drizzle-kit's auto-generated migrations
+ * can violate. Each rule is checked against every SQL statement.
+ */
+const SQLITE_LINT_RULES: { pattern: RegExp; message: string }[] = [
+  {
+    pattern: /ALTER\s+TABLE\s+\S+\s+ADD\s+(?:COLUMN\s+)?\S+[^;]*DEFAULT\s*\(/i,
+    message:
+      "ALTER TABLE ADD COLUMN with an expression default (e.g. DEFAULT (unixepoch())) " +
+      "is not allowed in SQLite. Use the table-recreation pattern instead " +
+      "(CREATE new table, INSERT SELECT, DROP old, RENAME).",
+  },
+  {
+    pattern: /ALTER\s+TABLE\s+\S+\s+ADD\s+(?:COLUMN\s+)?\S+[^;]*DEFAULT\s+CURRENT_(TIME|DATE|TIMESTAMP)\b/i,
+    message:
+      "ALTER TABLE ADD COLUMN with DEFAULT CURRENT_TIME/CURRENT_DATE/CURRENT_TIMESTAMP " +
+      "is not allowed in SQLite. Use the table-recreation pattern instead.",
+  },
+];
+
+function loadMigrations(): Migration[] {
+  const journalPath = path.join(migrationsFolder, "meta", "_journal.json");
+  const journal = JSON.parse(readFileSync(journalPath, "utf8")) as {
+    entries: JournalEntry[];
+  };
+
+  return journal.entries.map((entry) => {
+    const migrationPath = path.join(migrationsFolder, `${entry.tag}.sql`);
+    const statements = readFileSync(migrationPath, "utf8")
+      .split("--> statement-breakpoint")
+      .map((statement) => statement.trim())
+      .filter(Boolean);
+
+    return { entry, statements };
+  });
+}
+
+function assert(condition: unknown, message: string): asserts condition {
+  if (!condition) {
+    throw new Error(message);
+  }
+}
+
+function runMigration(db: Database, migration: Migration) {
+  db.run("BEGIN");
+
+  try {
+    for (const statement of migration.statements) {
+      db.run(statement);
+    }
+
+    db.run("COMMIT");
+  } catch (error) {
+    try {
+      db.run("ROLLBACK");
+    } catch {
+      // Ignore rollback errors so the original failure is preserved.
+    }
+
+    throw error;
+  }
+}
+
+function runMigrations(db: Database, selectedMigrations: Migration[]) {
+  for (const migration of selectedMigrations) {
+    runMigration(db, migration);
+  }
+}
+
+function seedPre0009Database(db: Database) {
+  // Seed every existing table so ALTER TABLE paths run against non-empty data.
+  db.run("INSERT INTO users (id, email, username, name) VALUES ('u1', 'u1@example.com', 'user1', 'User One')");
+  db.run("INSERT INTO configs (id, user_id, name, github_config, gitea_config, schedule_config, cleanup_config) VALUES ('c1', 'u1', 'Default', '{}', '{}', '{}', '{}')");
+  db.run("INSERT INTO accounts (id, account_id, user_id, provider_id, access_token, refresh_token, id_token, access_token_expires_at, refresh_token_expires_at, scope) VALUES ('acct1', 'acct-1', 'u1', 'github', 'access-token', 'refresh-token', 'id-token', 2000, 3000, 'repo')");
+  db.run("INSERT INTO events (id, user_id, channel, payload) VALUES ('evt1', 'u1', 'sync', '{\"status\":\"queued\"}')");
+  db.run("INSERT INTO mirror_jobs (id, user_id, repository_id, repository_name, status, message, timestamp) VALUES ('job1', 'u1', 'r1', 'owner/repo', 'imported', 'Imported repository', 900)");
+  db.run("INSERT INTO organizations (id, user_id, config_id, name, avatar_url, public_repository_count, private_repository_count, fork_repository_count) VALUES ('org1', 'u1', 'c1', 'Example Org', 'https://example.com/org.png', 1, 0, 0)");
+  db.run("INSERT INTO repositories (id, user_id, config_id, name, full_name, normalized_full_name, url, clone_url, owner, organization, default_branch, created_at, updated_at, metadata) VALUES ('r1', 'u1', 'c1', 'repo', 'owner/repo', 'owner/repo', 'https://example.com/repo', 'https://example.com/repo.git', 'owner', 'Example Org', 'main', 1000, 1100, '{\"issues\":true}')");
+  db.run("INSERT INTO sessions (id, token, user_id, expires_at) VALUES ('sess1', 'session-token', 'u1', 4000)");
+  db.run("INSERT INTO verification_tokens (id, token, identifier, type, expires_at) VALUES ('vt1', 'verify-token', 'u1@example.com', 'email', 5000)");
+  db.run("INSERT INTO verifications (id, identifier, value, expires_at) VALUES ('ver1', 'u1@example.com', '123456', 6000)");
+  db.run("INSERT INTO oauth_applications (id, client_id, client_secret, name, redirect_urls, type, user_id) VALUES ('app1', 'client-1', 'secret-1', 'Example App', '[\"https://example.com/callback\"]', 'confidential', 'u1')");
+  db.run("INSERT INTO oauth_access_tokens (id, access_token, refresh_token, access_token_expires_at, refresh_token_expires_at, client_id, user_id, scopes) VALUES ('oat1', 'oauth-access-token', 'oauth-refresh-token', 7000, 8000, 'client-1', 'u1', '[\"repo\"]')");
+  db.run("INSERT INTO oauth_consent (id, user_id, client_id, scopes, consent_given) VALUES ('consent1', 'u1', 'client-1', '[\"repo\"]', true)");
+  db.run("INSERT INTO sso_providers (id, issuer, domain, oidc_config, user_id, provider_id) VALUES ('sso1', 'https://issuer.example.com', 'example.com', '{}', 'u1', 'provider-1')");
+  db.run("INSERT INTO rate_limits (id, user_id, provider, `limit`, remaining, used, reset, retry_after, status, last_checked) VALUES ('rl1', 'u1', 'github', 5000, 4999, 1, 9000, NULL, 'ok', 8500)");
+}
+
+function verify0009Migration(db: Database) {
+  const repositoryColumns = db.query("PRAGMA table_info(repositories)").all() as TableInfoRow[];
+  const importedAtColumn = repositoryColumns.find((column) => column.name === "imported_at");
+
+  assert(importedAtColumn, "Expected repositories.imported_at column to exist after migration");
+  assert(importedAtColumn.notnull === 1, "Expected repositories.imported_at to be NOT NULL");
+  assert(importedAtColumn.dflt_value === "unixepoch()", `Expected repositories.imported_at default to be unixepoch(), got ${importedAtColumn.dflt_value ?? "null"}`);
+
+  const existingRepo = db.query("SELECT imported_at FROM repositories WHERE id = 'r1'").get() as { imported_at: number } | null;
+  assert(existingRepo?.imported_at === 900, `Expected existing repository imported_at to backfill from mirror_jobs timestamp 900, got ${existingRepo?.imported_at ?? "null"}`);
+
+  db.run("INSERT INTO repositories (id, user_id, config_id, name, full_name, normalized_full_name, url, clone_url, owner, default_branch) VALUES ('r2', 'u1', 'c1', 'repo-two', 'owner/repo-two', 'owner/repo-two', 'https://example.com/repo-two', 'https://example.com/repo-two.git', 'owner', 'main')");
+  const newRepo = db.query("SELECT imported_at FROM repositories WHERE id = 'r2'").get() as { imported_at: number } | null;
+  assert(typeof newRepo?.imported_at === "number" && newRepo.imported_at > 0, "Expected new repository insert to receive imported_at from the column default");
+
+  const importedAtIndex = db
+    .query("SELECT name FROM sqlite_master WHERE type = 'index' AND tbl_name = 'repositories' AND name = 'idx_repositories_user_imported_at'")
+    .get() as { name: string } | null;
+  assert(importedAtIndex?.name === "idx_repositories_user_imported_at", "Expected repositories imported_at index to exist after migration");
+}
+
+function seedPre0010Database(db: any) {
+  // Seed a repo row to verify index creation doesn't break existing data
+  seedPre0009Database(db);
+}
+
+function verify0010Migration(db: any) {
+  const indexes = db.prepare(
+    "SELECT name FROM sqlite_master WHERE type='index' AND name='uniq_repositories_user_mirrored_location'"
+  ).all();
+  if (indexes.length === 0) {
+    throw new Error("Missing unique partial index uniq_repositories_user_mirrored_location");
+  }
+
+  const lookupIdx = db.prepare(
+    "SELECT name FROM sqlite_master WHERE type='index' AND name='idx_repositories_mirrored_location'"
+  ).all();
+  if (lookupIdx.length === 0) {
+    throw new Error("Missing lookup index idx_repositories_mirrored_location");
+  }
+}
+
+function seedPre0011Database(db: any) {
+  seedPre0009Database(db);
+  runMigration(db, migrations.find((m) => m.entry.tag === "0009_nervous_tyger_tiger")!);
+  runMigration(db, migrations.find((m) => m.entry.tag === "0010_mirrored_location_index")!);
+}
+
+function verify0011Migration(db: any) {
+  const configColumns = db.query("PRAGMA table_info(configs)").all() as TableInfoRow[];
+  const notificationConfigColumn = configColumns.find((column: any) => column.name === "notification_config");
+
+  assert(notificationConfigColumn, "Expected configs.notification_config column to exist after migration");
+  assert(notificationConfigColumn.notnull === 1, "Expected configs.notification_config to be NOT NULL");
+  assert(
+    notificationConfigColumn.dflt_value !== null,
+    "Expected configs.notification_config to have a default value",
+  );
+
+  const existingConfig = db.query("SELECT notification_config FROM configs WHERE id = 'c1'").get() as { notification_config: string } | null;
+  assert(existingConfig, "Expected existing config row to still exist");
+  const parsed = JSON.parse(existingConfig.notification_config);
+  assert(parsed.enabled === false, "Expected default notification_config.enabled to be false");
+  assert(parsed.provider === "ntfy", "Expected default notification_config.provider to be 'ntfy'");
+}
+
+const latestUpgradeFixtures: Record<string, UpgradeFixture> = {
+  "0009_nervous_tyger_tiger": {
+    seed: seedPre0009Database,
+    verify: verify0009Migration,
+  },
+  "0010_mirrored_location_index": {
+    seed: seedPre0010Database,
+    verify: verify0010Migration,
+  },
+  "0011_notification_config": {
+    seed: seedPre0011Database,
+    verify: verify0011Migration,
+  },
+};
+
+function lintMigrations(selectedMigrations: Migration[]) {
+  const violations: string[] = [];
+
+  for (const migration of selectedMigrations) {
+    for (const statement of migration.statements) {
+      for (const rule of SQLITE_LINT_RULES) {
+        if (rule.pattern.test(statement)) {
+          violations.push(`[${migration.entry.tag}] ${rule.message}\n  Statement: ${statement.slice(0, 120)}...`);
+        }
+      }
+    }
+  }
+
+  assert(
+    violations.length === 0,
+    `SQLite lint found ${violations.length} violation(s):\n\n${violations.join("\n\n")}`,
+  );
+}
+
+function validateMigrations() {
+  assert(latestMigration, "No migrations found in drizzle/meta/_journal.json");
+
+  // Lint all migrations for known SQLite pitfalls before running anything.
+  lintMigrations(migrations);
+
+  const emptyDb = new Database(":memory:");
+  try {
+    runMigrations(emptyDb, migrations);
+  } finally {
+    emptyDb.close();
+  }
+
+  const upgradeFixture = latestUpgradeFixtures[latestMigration.entry.tag];
+  assert(
+    upgradeFixture,
+    `Missing upgrade fixture for latest migration ${latestMigration.entry.tag}. Add one in scripts/validate-migrations.ts.`,
+  );
+
+  const upgradeDb = new Database(":memory:");
+  try {
+    runMigrations(upgradeDb, migrations.slice(0, -1));
+    upgradeFixture.seed(upgradeDb);
+    runMigration(upgradeDb, latestMigration);
+    upgradeFixture.verify(upgradeDb);
+  } finally {
+    upgradeDb.close();
+  }
+
+  console.log(
+    `Validated ${migrations.length} migrations from scratch and upgrade path for ${latestMigration.entry.tag}.`,
+  );
+}
+
+try {
+  validateMigrations();
+} catch (error) {
+  console.error("Migration validation failed:");
+  console.error(error instanceof Error ? error.stack ?? error.message : String(error));
+  process.exit(1);
+}

src/components/NotFound.tsx

@@ -1,6 +1,7 @@
 import { Button } from "@/components/ui/button";
 import { Card, CardContent, CardHeader } from "@/components/ui/card";
 import { Home, ArrowLeft, GitBranch, BookOpen, Settings, FileQuestion } from "lucide-react";
+import { withBase } from "@/lib/base-path";
 
 export function NotFound() {
   return (
@@ -21,7 +22,7 @@ export function NotFound() {
           {/* Action Buttons */}
           <div className="flex flex-col gap-3">
             <Button asChild className="w-full">
-              <a href="/">
+              <a href={withBase("/")}>
                 <Home className="mr-2 h-4 w-4" />
                 Go to Dashboard
               </a>
@@ -45,21 +46,21 @@ export function NotFound() {
           {/* Quick Links */}
           <div className="grid grid-cols-3 gap-3">
             <a 
-              href="/repositories" 
+              href={withBase("/repositories")} 
               className="flex flex-col items-center gap-2 p-3 rounded-md hover:bg-muted transition-colors"
             >
               <GitBranch className="h-5 w-5 text-muted-foreground" />
               <span className="text-xs">Repositories</span>
             </a>
             <a 
-              href="/config" 
+              href={withBase("/config")} 
               className="flex flex-col items-center gap-2 p-3 rounded-md hover:bg-muted transition-colors"
             >
               <Settings className="h-5 w-5 text-muted-foreground" />
               <span className="text-xs">Config</span>
             </a>
             <a 
-              href="/docs" 
+              href={withBase("/docs")} 
               className="flex flex-col items-center gap-2 p-3 rounded-md hover:bg-muted transition-colors"
             >
               <BookOpen className="h-5 w-5 text-muted-foreground" />
@@ -77,4 +78,4 @@ export function NotFound() {
       </Card>
     </div>
   );
-}
+}

src/components/activity/ActivityLog.tsx

@@ -36,6 +36,7 @@ import { toast } from 'sonner';
 import { useLiveRefresh } from '@/hooks/useLiveRefresh';
 import { useConfigStatus } from '@/hooks/useConfigStatus';
 import { useNavigation } from '@/components/layout/MainLayout';
+import { withBase } from '@/lib/base-path';
 import {
   Drawer,
   DrawerClose,
@@ -321,7 +322,7 @@ export function ActivityLog() {
       setIsInitialLoading(true);
       setShowCleanupDialog(false);
 
-      const response = await fetch('/api/activities/cleanup', {
+      const response = await fetch(withBase('/api/activities/cleanup'), {
         method: 'POST',
         headers: { 'Content-Type': 'application/json' },
         body: JSON.stringify({ userId: user.id }),

src/components/auth/AccountMenu.tsx

@@ -0,0 +1,134 @@
+import { useEffect, useState } from "react";
+import { toast } from "sonner";
+import { KeyRound, LogOut, Mail } from "lucide-react";
+import { useAuth } from "@/hooks/useAuth";
+import { authClient } from "@/lib/auth-client";
+import { withBase } from "@/lib/base-path";
+import { Avatar, AvatarFallback, AvatarImage } from "@/components/ui/avatar";
+import { Button } from "@/components/ui/button";
+import {
+  DropdownMenu,
+  DropdownMenuContent,
+  DropdownMenuItem,
+  DropdownMenuLabel,
+  DropdownMenuSeparator,
+  DropdownMenuTrigger,
+} from "@/components/ui/dropdown-menu";
+import { ChangePasswordDialog } from "./ChangePasswordDialog";
+import { ChangeEmailDialog } from "./ChangeEmailDialog";
+
+export function AccountMenu() {
+  const { user, logout, refreshUser } = useAuth();
+  const [hasPassword, setHasPassword] = useState<boolean | null>(null);
+  const [passwordOpen, setPasswordOpen] = useState(false);
+  const [emailOpen, setEmailOpen] = useState(false);
+
+  useEffect(() => {
+    if (!user) {
+      setHasPassword(null);
+      return;
+    }
+    let cancelled = false;
+    (async () => {
+      try {
+        const accounts = await authClient.listAccounts();
+        if (cancelled) return;
+        const list = Array.isArray(accounts) ? accounts : accounts?.data;
+        setHasPassword(
+          Array.isArray(list) && list.some((a) => a.providerId === "credential")
+        );
+      } catch {
+        // Fail open: if we can't check, show the option rather than locking the
+        // user out of changing their password.
+        if (!cancelled) setHasPassword(true);
+      }
+    })();
+    return () => {
+      cancelled = true;
+    };
+  }, [user?.id]);
+
+  if (!user) {
+    return (
+      <Button variant="outline" size="sm" asChild>
+        <a href={withBase("/login")}>Login</a>
+      </Button>
+    );
+  }
+
+  const handleLogout = async () => {
+    toast.success("Logged out successfully");
+    await new Promise((resolve) => setTimeout(resolve, 500));
+    logout();
+  };
+
+  return (
+    <>
+      <DropdownMenu>
+        <DropdownMenuTrigger asChild>
+          <Button
+            variant="outline"
+            size="lg"
+            className="relative h-10 w-10 rounded-full p-0"
+          >
+            <Avatar className="h-full w-full">
+              <AvatarImage src={user.image || ""} alt={user.name || user.email} />
+              <AvatarFallback>
+                {(user.name || user.email || "U").charAt(0).toUpperCase()}
+              </AvatarFallback>
+            </Avatar>
+          </Button>
+        </DropdownMenuTrigger>
+        <DropdownMenuContent align="end" className="w-60">
+          <DropdownMenuLabel className="font-normal">
+            <div className="flex flex-col gap-0.5">
+              {user.name && (
+                <span className="text-sm font-medium leading-none">
+                  {user.name}
+                </span>
+              )}
+              <span className="text-xs leading-none text-muted-foreground truncate">
+                {user.email}
+              </span>
+            </div>
+          </DropdownMenuLabel>
+          <DropdownMenuSeparator />
+          {hasPassword && (
+            <DropdownMenuItem
+              onSelect={() => setPasswordOpen(true)}
+              className="cursor-pointer"
+            >
+              <KeyRound className="h-4 w-4 mr-2" />
+              Change password
+            </DropdownMenuItem>
+          )}
+          <DropdownMenuItem
+            onSelect={() => setEmailOpen(true)}
+            className="cursor-pointer"
+          >
+            <Mail className="h-4 w-4 mr-2" />
+            Change email
+          </DropdownMenuItem>
+          <DropdownMenuSeparator />
+          <DropdownMenuItem onSelect={handleLogout} className="cursor-pointer">
+            <LogOut className="h-4 w-4 mr-2" />
+            Logout
+          </DropdownMenuItem>
+        </DropdownMenuContent>
+      </DropdownMenu>
+
+      {hasPassword && (
+        <ChangePasswordDialog
+          open={passwordOpen}
+          onOpenChange={setPasswordOpen}
+        />
+      )}
+      <ChangeEmailDialog
+        open={emailOpen}
+        onOpenChange={setEmailOpen}
+        currentEmail={user.email}
+        onUpdated={refreshUser}
+      />
+    </>
+  );
+}

src/components/auth/ChangeEmailDialog.tsx

@@ -0,0 +1,110 @@
+import { useState } from "react";
+import { toast } from "sonner";
+import { authClient } from "@/lib/auth-client";
+import { Button } from "@/components/ui/button";
+import { Input } from "@/components/ui/input";
+import { Label } from "@/components/ui/label";
+import {
+  Dialog,
+  DialogContent,
+  DialogDescription,
+  DialogFooter,
+  DialogHeader,
+  DialogTitle,
+} from "@/components/ui/dialog";
+
+interface ChangeEmailDialogProps {
+  open: boolean;
+  onOpenChange: (open: boolean) => void;
+  currentEmail: string;
+  onUpdated?: () => void;
+}
+
+export function ChangeEmailDialog({
+  open,
+  onOpenChange,
+  currentEmail,
+  onUpdated,
+}: ChangeEmailDialogProps) {
+  const [newEmail, setNewEmail] = useState("");
+  const [isSubmitting, setIsSubmitting] = useState(false);
+
+  const reset = () => {
+    setNewEmail("");
+    setIsSubmitting(false);
+  };
+
+  const handleOpenChange = (next: boolean) => {
+    if (!next) reset();
+    onOpenChange(next);
+  };
+
+  const handleSubmit = async (e: React.FormEvent) => {
+    e.preventDefault();
+    const trimmed = newEmail.trim();
+    if (!trimmed) {
+      toast.error("Please enter a new email");
+      return;
+    }
+    if (trimmed.toLowerCase() === currentEmail.toLowerCase()) {
+      toast.error("New email must differ from current email");
+      return;
+    }
+
+    setIsSubmitting(true);
+    try {
+      const { error } = await authClient.changeEmail({ newEmail: trimmed });
+      if (error) {
+        toast.error(error.message || "Failed to change email");
+        return;
+      }
+      toast.success("Email updated.");
+      onUpdated?.();
+      handleOpenChange(false);
+    } catch (err) {
+      toast.error(err instanceof Error ? err.message : "Failed to change email");
+    } finally {
+      setIsSubmitting(false);
+    }
+  };
+
+  return (
+    <Dialog open={open} onOpenChange={handleOpenChange}>
+      <DialogContent className="sm:max-w-md">
+        <DialogHeader>
+          <DialogTitle>Change email</DialogTitle>
+          <DialogDescription>
+            Current: <span className="font-medium">{currentEmail}</span>
+          </DialogDescription>
+        </DialogHeader>
+        <form onSubmit={handleSubmit} className="space-y-4">
+          <div className="space-y-2">
+            <Label htmlFor="new-email">New email</Label>
+            <Input
+              id="new-email"
+              type="email"
+              autoComplete="email"
+              value={newEmail}
+              onChange={(e) => setNewEmail(e.target.value)}
+              disabled={isSubmitting}
+              required
+            />
+          </div>
+          <DialogFooter>
+            <Button
+              type="button"
+              variant="outline"
+              onClick={() => handleOpenChange(false)}
+              disabled={isSubmitting}
+            >
+              Cancel
+            </Button>
+            <Button type="submit" disabled={isSubmitting}>
+              {isSubmitting ? "Updating..." : "Update email"}
+            </Button>
+          </DialogFooter>
+        </form>
+      </DialogContent>
+    </Dialog>
+  );
+}

src/components/auth/ChangePasswordDialog.tsx

@@ -0,0 +1,158 @@
+import { useState } from "react";
+import { toast } from "sonner";
+import { authClient } from "@/lib/auth-client";
+import { Button } from "@/components/ui/button";
+import { Input } from "@/components/ui/input";
+import { Label } from "@/components/ui/label";
+import { Checkbox } from "@/components/ui/checkbox";
+import {
+  Dialog,
+  DialogContent,
+  DialogDescription,
+  DialogFooter,
+  DialogHeader,
+  DialogTitle,
+} from "@/components/ui/dialog";
+
+interface ChangePasswordDialogProps {
+  open: boolean;
+  onOpenChange: (open: boolean) => void;
+}
+
+export function ChangePasswordDialog({ open, onOpenChange }: ChangePasswordDialogProps) {
+  const [currentPassword, setCurrentPassword] = useState("");
+  const [newPassword, setNewPassword] = useState("");
+  const [confirmPassword, setConfirmPassword] = useState("");
+  const [revokeOtherSessions, setRevokeOtherSessions] = useState(true);
+  const [isSubmitting, setIsSubmitting] = useState(false);
+
+  const reset = () => {
+    setCurrentPassword("");
+    setNewPassword("");
+    setConfirmPassword("");
+    setRevokeOtherSessions(true);
+    setIsSubmitting(false);
+  };
+
+  const handleOpenChange = (next: boolean) => {
+    if (!next) reset();
+    onOpenChange(next);
+  };
+
+  const handleSubmit = async (e: React.FormEvent) => {
+    e.preventDefault();
+
+    if (!currentPassword || !newPassword) {
+      toast.error("Please fill in all fields");
+      return;
+    }
+    if (newPassword !== confirmPassword) {
+      toast.error("New passwords do not match");
+      return;
+    }
+    if (newPassword === currentPassword) {
+      toast.error("New password must differ from current password");
+      return;
+    }
+
+    setIsSubmitting(true);
+    try {
+      const { error } = await authClient.changePassword({
+        currentPassword,
+        newPassword,
+        revokeOtherSessions,
+      });
+      if (error) {
+        toast.error(error.message || "Failed to change password");
+        return;
+      }
+      toast.success(
+        revokeOtherSessions
+          ? "Password updated. Other sessions signed out."
+          : "Password updated."
+      );
+      handleOpenChange(false);
+    } catch (err) {
+      toast.error(err instanceof Error ? err.message : "Failed to change password");
+    } finally {
+      setIsSubmitting(false);
+    }
+  };
+
+  return (
+    <Dialog open={open} onOpenChange={handleOpenChange}>
+      <DialogContent className="sm:max-w-md">
+        <DialogHeader>
+          <DialogTitle>Change password</DialogTitle>
+          <DialogDescription>
+            Enter your current password and a new one. You'll stay signed in on this device.
+          </DialogDescription>
+        </DialogHeader>
+        <form onSubmit={handleSubmit} className="space-y-4">
+          <div className="space-y-2">
+            <Label htmlFor="current-password">Current password</Label>
+            <Input
+              id="current-password"
+              type="password"
+              autoComplete="current-password"
+              value={currentPassword}
+              onChange={(e) => setCurrentPassword(e.target.value)}
+              disabled={isSubmitting}
+              required
+            />
+          </div>
+          <div className="space-y-2">
+            <Label htmlFor="new-password">New password</Label>
+            <Input
+              id="new-password"
+              type="password"
+              autoComplete="new-password"
+              value={newPassword}
+              onChange={(e) => setNewPassword(e.target.value)}
+              disabled={isSubmitting}
+              required
+              minLength={8}
+            />
+          </div>
+          <div className="space-y-2">
+            <Label htmlFor="confirm-password">Confirm new password</Label>
+            <Input
+              id="confirm-password"
+              type="password"
+              autoComplete="new-password"
+              value={confirmPassword}
+              onChange={(e) => setConfirmPassword(e.target.value)}
+              disabled={isSubmitting}
+              required
+              minLength={8}
+            />
+          </div>
+          <div className="flex items-center gap-2">
+            <Checkbox
+              id="revoke-sessions"
+              checked={revokeOtherSessions}
+              onCheckedChange={(checked) => setRevokeOtherSessions(checked === true)}
+              disabled={isSubmitting}
+            />
+            <Label htmlFor="revoke-sessions" className="text-sm font-normal cursor-pointer">
+              Sign out other devices
+            </Label>
+          </div>
+          <DialogFooter>
+            <Button
+              type="button"
+              variant="outline"
+              onClick={() => handleOpenChange(false)}
+              disabled={isSubmitting}
+            >
+              Cancel
+            </Button>
+            <Button type="submit" disabled={isSubmitting}>
+              {isSubmitting ? "Updating..." : "Update password"}
+            </Button>
+          </DialogFooter>
+        </form>
+      </DialogContent>
+    </Dialog>
+  );
+}

src/components/auth/LoginForm.tsx

@@ -12,6 +12,7 @@ import { Separator } from '@/components/ui/separator';
 import { toast, Toaster } from 'sonner';
 import { showErrorToast } from '@/lib/utils';
 import { Loader2, Mail, Globe, Eye, EyeOff } from 'lucide-react';
+import { withBase } from '@/lib/base-path';
 
 
 export function LoginForm() {
@@ -47,7 +48,7 @@ export function LoginForm() {
       toast.success('Login successful!');
       // Small delay before redirecting to see the success message
       setTimeout(() => {
-        window.location.href = '/';
+        window.location.href = withBase('/');
       }, 1000);
     } catch (error) {
       showErrorToast(error, toast);
@@ -64,12 +65,15 @@ export function LoginForm() {
         return;
       }
 
-      const baseURL = typeof window !== 'undefined' ? window.location.origin : 'http://localhost:4321';
+      const callbackURL =
+        typeof window !== 'undefined'
+          ? new URL(withBase('/'), window.location.origin).toString()
+          : `http://localhost:4321${withBase('/')}`;
       await authClient.signIn.sso({
         email: ssoEmail || undefined,
         domain: domain,
         providerId: providerId,
-        callbackURL: `${baseURL}/`,
+        callbackURL,
         scopes: ['openid', 'email', 'profile'], // TODO: This is not being respected by the SSO plugin.
       });
     } catch (error) {
@@ -85,7 +89,7 @@ export function LoginForm() {
         <CardHeader className="text-center">
           <div className="flex justify-center mb-4">
             <img
-              src="/logo.png"
+              src={withBase('/logo.png')}
               alt="Gitea Mirror Logo"
               className="h-8 w-10"
             />

src/components/auth/SignupForm.tsx

@@ -7,6 +7,7 @@ import { toast, Toaster } from 'sonner';
 import { showErrorToast } from '@/lib/utils';
 import { useAuth } from '@/hooks/useAuth';
 import { Eye, EyeOff } from 'lucide-react';
+import { withBase } from '@/lib/base-path';
 
 export function SignupForm() {
   const [isLoading, setIsLoading] = useState(false);
@@ -42,7 +43,7 @@ export function SignupForm() {
       toast.success('Account created successfully! Redirecting to dashboard...');
       // Small delay before redirecting to see the success message
       setTimeout(() => {
-        window.location.href = '/';
+        window.location.href = withBase('/');
       }, 1500);
     } catch (error) {
       showErrorToast(error, toast);
@@ -57,7 +58,7 @@ export function SignupForm() {
         <CardHeader className="text-center">
           <div className="flex justify-center mb-4">
             <img
-              src="/logo.png"
+              src={withBase('/logo.png')}
               alt="Gitea Mirror Logo"
               className="h-8 w-10"
             />

src/components/config/AutomationSettings.tsx

@@ -1,7 +1,8 @@
-import { useEffect } from "react";
+import { useEffect, useMemo } from "react";
 import { Card, CardContent, CardHeader, CardTitle } from "@/components/ui/card";
 import { Checkbox } from "@/components/ui/checkbox";
 import { Label } from "@/components/ui/label";
+import { Input } from "@/components/ui/input";
 import {
   Select,
   SelectContent,
@@ -19,6 +20,7 @@ import {
   Zap,
   Info,
   Archive,
+  Globe,
 } from "lucide-react";
 import {
   Tooltip,
@@ -28,6 +30,10 @@ import {
 } from "@/components/ui/tooltip";
 import type { ScheduleConfig, DatabaseCleanupConfig } from "@/types/config";
 import { formatDate } from "@/lib/utils";
+import {
+  buildClockCronExpression,
+  getNextCronOccurrence,
+} from "@/lib/utils/schedule-utils";
 
 interface AutomationSettingsProps {
   scheduleConfig: ScheduleConfig;
@@ -38,15 +44,13 @@ interface AutomationSettingsProps {
   isAutoSavingCleanup?: boolean;
 }
 
-const scheduleIntervals = [
-  { label: "Every hour", value: 3600 },
-  { label: "Every 2 hours", value: 7200 },
-  { label: "Every 4 hours", value: 14400 },
-  { label: "Every 8 hours", value: 28800 },
-  { label: "Every 12 hours", value: 43200 },
-  { label: "Daily", value: 86400 },
-  { label: "Every 2 days", value: 172800 },
-  { label: "Weekly", value: 604800 },
+const clockFrequencies = [
+  { label: "Every hour", value: 1 },
+  { label: "Every 2 hours", value: 2 },
+  { label: "Every 4 hours", value: 4 },
+  { label: "Every 8 hours", value: 8 },
+  { label: "Every 12 hours", value: 12 },
+  { label: "Daily", value: 24 },
 ];
 
 const retentionPeriods = [
@@ -85,6 +89,27 @@ export function AutomationSettings({
   isAutoSavingSchedule,
   isAutoSavingCleanup,
 }: AutomationSettingsProps) {
+  const browserTimezone =
+    typeof Intl !== "undefined"
+      ? Intl.DateTimeFormat().resolvedOptions().timeZone || "UTC"
+      : "UTC";
+
+  // Use saved timezone, but treat "UTC" as unset for users who never chose it
+  const effectiveTimezone = scheduleConfig.timezone || browserTimezone;
+
+  const nextScheduledRun = useMemo(() => {
+    if (!scheduleConfig.enabled) return null;
+    const startTime = scheduleConfig.startTime || "22:00";
+    const frequencyHours = scheduleConfig.clockFrequencyHours || 24;
+    const cronExpression = buildClockCronExpression(startTime, frequencyHours);
+    if (!cronExpression) return null;
+    try {
+      return getNextCronOccurrence(cronExpression, new Date(), effectiveTimezone);
+    } catch {
+      return null;
+    }
+  }, [scheduleConfig.enabled, scheduleConfig.startTime, scheduleConfig.clockFrequencyHours, effectiveTimezone]);
+
   // Update nextRun for cleanup when settings change
   useEffect(() => {
     if (cleanupConfig.enabled && !cleanupConfig.nextRun) {
@@ -125,7 +150,7 @@ export function AutomationSettings({
   <CardContent className="space-y-6">
     <div className="grid grid-cols-1 md:grid-cols-2 gap-4">
       {/* Automatic Syncing Section */}
-      <div className="space-y-4 p-4 border border-border rounded-lg bg-card/50">
+      <div className="flex flex-col gap-4 p-4 border border-border rounded-lg bg-card/50">
         <div className="flex items-center justify-between">
           <h3 className="text-sm font-medium flex items-center gap-2">
             <RefreshCw className="h-4 w-4 text-primary" />
@@ -136,14 +161,21 @@ export function AutomationSettings({
               )}
             </div>
 
-            <div className="space-y-4">
+            <div className="flex-1 flex flex-col gap-4">
               <div className="flex items-start space-x-3">
                 <Checkbox
                   id="enable-auto-mirror"
                   checked={scheduleConfig.enabled}
                   className="mt-1.25"
                   onCheckedChange={(checked) =>
-                    onScheduleChange({ ...scheduleConfig, enabled: !!checked })
+                    onScheduleChange({
+                      ...scheduleConfig,
+                      enabled: !!checked,
+                      timezone: checked ? browserTimezone : scheduleConfig.timezone,
+                      startTime: scheduleConfig.startTime || "22:00",
+                      clockFrequencyHours: scheduleConfig.clockFrequencyHours || 24,
+                      scheduleMode: "clock",
+                    })
                   }
                 />
                 <div className="space-y-0.5 flex-1">
@@ -154,79 +186,148 @@ export function AutomationSettings({
                     Enable automatic repository syncing
                   </Label>
                   <p className="text-xs text-muted-foreground">
-                    Periodically check GitHub for changes and mirror them to Gitea
+                    Periodically sync GitHub changes to Gitea
                   </p>
                 </div>
               </div>
 
               {scheduleConfig.enabled && (
-                <div className="ml-6 space-y-3">
-                  <div>
-                    <Label htmlFor="mirror-interval" className="text-sm">
-                      Sync frequency
-                    </Label>
-                    <Select
-                      value={scheduleConfig.interval.toString()}
-                      onValueChange={(value) =>
+                <div className="space-y-3">
+                  <div className="flex flex-wrap items-center justify-between gap-2">
+                    <p className="text-[11px] font-medium uppercase tracking-wide text-muted-foreground">
+                      Schedule
+                    </p>
+                    <span className="inline-flex items-center gap-1.5 rounded-full border border-border/70 px-2.5 py-0.5 text-[11px] text-muted-foreground">
+                      <Globe className="h-3 w-3" />
+                      {effectiveTimezone}
+                    </span>
+                  </div>
+
+                  <div className="grid gap-3 sm:grid-cols-2">
+                    <div className="space-y-1.5">
+                      <Label
+                        htmlFor="clock-frequency"
+                        className="text-xs font-medium uppercase tracking-wide text-muted-foreground"
+                      >
+                        Frequency
+                      </Label>
+                      <Select
+                        value={String(scheduleConfig.clockFrequencyHours || 24)}
+                        onValueChange={(value) =>
+                          onScheduleChange({
+                            ...scheduleConfig,
+                            scheduleMode: "clock",
+                            clockFrequencyHours: parseInt(value, 10),
+                            startTime: scheduleConfig.startTime || "22:00",
+                            timezone: effectiveTimezone,
+                          })
+                        }
+                      >
+                        <SelectTrigger id="clock-frequency" className="w-full">
+                          <SelectValue />
+                        </SelectTrigger>
+                        <SelectContent>
+                          {clockFrequencies.map((option) => (
+                            <SelectItem
+                              key={option.value}
+                              value={option.value.toString()}
+                            >
+                              {option.label}
+                            </SelectItem>
+                          ))}
+                        </SelectContent>
+                      </Select>
+                    </div>
+
+                    <div className="space-y-1.5">
+                      <Label
+                        htmlFor="clock-start-time"
+                        className="text-xs font-medium uppercase tracking-wide text-muted-foreground"
+                      >
+                        Start time
+                      </Label>
+                      <div className="relative">
+                        <div className="text-muted-foreground pointer-events-none absolute inset-y-0 left-0 flex items-center justify-center pl-3">
+                          <Clock className="size-4" />
+                        </div>
+                        <Input
+                          id="clock-start-time"
+                          type="time"
+                          value={scheduleConfig.startTime || "22:00"}
+                          onChange={(event) =>
+                            onScheduleChange({
+                              ...scheduleConfig,
+                              scheduleMode: "clock",
+                              startTime: event.target.value,
+                              clockFrequencyHours:
+                                scheduleConfig.clockFrequencyHours || 24,
+                              timezone: effectiveTimezone,
+                            })
+                          }
+                          className="appearance-none pl-9 dark:bg-input/30 [&::-webkit-calendar-picker-indicator]:hidden [&::-webkit-calendar-picker-indicator]:appearance-none"
+                        />
+                      </div>
+                    </div>
+                  </div>
+
+                  <div className="flex items-start space-x-3 pt-1">
+                    <Checkbox
+                      id="enable-auto-mirror-new"
+                      checked={scheduleConfig.autoMirror ?? false}
+                      className="mt-1.25"
+                      onCheckedChange={(checked) =>
                         onScheduleChange({
                           ...scheduleConfig,
-                          interval: parseInt(value, 10),
+                          autoMirror: !!checked,
                         })
                       }
-                    >
-                      <SelectTrigger id="mirror-interval" className="mt-1.5">
-                        <SelectValue />
-                      </SelectTrigger>
-                      <SelectContent>
-                        {scheduleIntervals.map((option) => (
-                          <SelectItem
-                            key={option.value}
-                            value={option.value.toString()}
-                          >
-                            {option.label}
-                          </SelectItem>
-                        ))}
-                      </SelectContent>
-                    </Select>
+                    />
+                    <div className="space-y-0.5 flex-1">
+                      <Label
+                        htmlFor="enable-auto-mirror-new"
+                        className="text-sm font-normal cursor-pointer"
+                      >
+                        Auto-mirror new repositories
+                      </Label>
+                      <p className="text-xs text-muted-foreground">
+                        Automatically mirror newly imported repositories on each scheduled sync. When off, new repos are imported for browsing but require a manual mirror click. (Starred repos have their own toggle in GitHub settings.)
+                      </p>
+                    </div>
                   </div>
                 </div>
               )}
 
-              <div className="space-y-2 p-3 bg-muted/30 dark:bg-muted/10 rounded-md border border-border/50">
-                <div className="flex items-center justify-between text-xs">
-                  <span className="flex items-center gap-1.5">
-                    <Clock className="h-3.5 w-3.5" />
-                    Last sync
-                  </span>
-                  <span className="font-medium text-muted-foreground">
+              <div className="mt-auto flex items-center justify-between border-t border-border/50 pt-3 text-xs text-muted-foreground">
+                <span className="flex items-center gap-1.5">
+                  <Clock className="h-3.5 w-3.5" />
+                  Last sync{" "}
+                  <span className="font-medium">
                     {scheduleConfig.lastRun
                       ? formatDate(scheduleConfig.lastRun)
                       : "Never"}
                   </span>
-                </div>
+                </span>
                 {scheduleConfig.enabled ? (
-                  scheduleConfig.nextRun && (
-                    <div className="flex items-center justify-between text-xs">
-                      <span className="flex items-center gap-1.5">
-                        <Calendar className="h-3.5 w-3.5" />
-                        Next sync
-                      </span>
-                      <span className="font-medium">
-                        {formatDate(scheduleConfig.nextRun)}
-                      </span>
-                    </div>
-                  )
+                  <span className="flex items-center gap-1.5">
+                    <Calendar className="h-3.5 w-3.5" />
+                    Next sync{" "}
+                    <span className="font-medium text-primary">
+                      {scheduleConfig.nextRun
+                        ? formatDate(scheduleConfig.nextRun)
+                        : nextScheduledRun
+                          ? formatDate(nextScheduledRun)
+                          : "Calculating..."}
+                    </span>
+                  </span>
                 ) : (
-                  <div className="text-xs text-muted-foreground">
-                    Enable automatic syncing to schedule periodic repository updates
-                  </div>
+                  <span>Enable syncing to schedule updates</span>
                 )}
-          </div>
+              </div>
         </div>
       </div>
 
       {/* Database Cleanup Section */}
-      <div className="space-y-4 p-4 border border-border rounded-lg bg-card/50">
+      <div className="flex flex-col gap-4 p-4 border border-border rounded-lg bg-card/50">
         <div className="flex items-center justify-between">
           <h3 className="text-sm font-medium flex items-center gap-2">
             <Database className="h-4 w-4 text-primary" />
@@ -237,7 +338,7 @@ export function AutomationSettings({
               )}
             </div>
 
-            <div className="space-y-4">
+            <div className="flex-1 flex flex-col gap-4">
               <div className="flex items-start space-x-3">
                 <Checkbox
                   id="enable-auto-cleanup"
@@ -255,13 +356,13 @@ export function AutomationSettings({
                     Enable automatic database cleanup
                   </Label>
                   <p className="text-xs text-muted-foreground">
-                    Remove old activity logs and events to optimize storage
+                    Remove old activity logs to optimize storage
                   </p>
                 </div>
               </div>
 
               {cleanupConfig.enabled && (
-                <div className="ml-6 space-y-5">
+                <div className="space-y-5">
                   <div className="space-y-2">
                     <Label htmlFor="retention-period" className="text-sm flex items-center gap-2">
                       Data retention period
@@ -312,7 +413,7 @@ export function AutomationSettings({
                 </div>
               )}
 
-              <div className="space-y-2 p-3 bg-muted/30 dark:bg-muted/10 rounded-md border border-border/50">
+              <div className="mt-auto space-y-2 pt-3 border-t border-border/50">
                 <div className="flex items-center justify-between text-xs">
                   <span className="flex items-center gap-1.5">
                     <Clock className="h-3.5 w-3.5" />

src/components/config/ConfigTabs.tsx

@@ -3,6 +3,7 @@ import { GitHubConfigForm } from './GitHubConfigForm';
 import { GiteaConfigForm } from './GiteaConfigForm';
 import { AutomationSettings } from './AutomationSettings';
 import { SSOSettings } from './SSOSettings';
+import { NotificationSettings } from './NotificationSettings';
 import type {
   ConfigApiResponse,
   GiteaConfig,
@@ -13,6 +14,7 @@ import type {
   DatabaseCleanupConfig,
   MirrorOptions,
   AdvancedOptions,
+  NotificationConfig,
 } from '@/types/config';
 import { Button } from '../ui/button';
 import { useAuth } from '@/hooks/useAuth';
@@ -22,6 +24,7 @@ import { toast } from 'sonner';
 import { Skeleton } from '@/components/ui/skeleton';
 import { invalidateConfigCache } from '@/hooks/useConfigStatus';
 import { Tabs, TabsContent, TabsList, TabsTrigger } from '@/components/ui/tabs';
+import { withBase } from '@/lib/base-path';
 
 type ConfigState = {
   githubConfig: GitHubConfig;
@@ -30,8 +33,11 @@ type ConfigState = {
   cleanupConfig: DatabaseCleanupConfig;
   mirrorOptions: MirrorOptions;
   advancedOptions: AdvancedOptions;
+  notificationConfig: NotificationConfig;
 };
 
+const CONFIG_API_PATH = withBase('/api/config');
+
 export function ConfigTabs() {
   const [config, setConfig] = useState<ConfigState>({
     githubConfig: {
@@ -39,6 +45,7 @@ export function ConfigTabs() {
       token: '',
       privateRepositories: false,
       mirrorStarred: false,
+      starredLists: [],
     },
     giteaConfig: {
       url: '',
@@ -50,6 +57,11 @@ export function ConfigTabs() {
       starredReposOrg: 'starred',
       starredReposMode: 'dedicated-org',
       preserveOrgStructure: false,
+      backupStrategy: "on-force-push",
+      backupRetentionCount: 5,
+      backupRetentionDays: 30,
+      backupDirectory: 'data/repo-backups',
+      blockSyncOnBackupFailure: true,
     },
     scheduleConfig: {
       enabled: false, // Don't set defaults here - will be loaded from API
@@ -79,6 +91,14 @@ export function ConfigTabs() {
     advancedOptions: {
       skipForks: false,
       starredCodeOnly: false,
+      autoMirrorStarred: false,
+    },
+    notificationConfig: {
+      enabled: false,
+      provider: "ntfy",
+      notifyOnSyncError: true,
+      notifyOnSyncSuccess: false,
+      notifyOnNewRepo: false,
     },
   });
   const { user } = useAuth();
@@ -89,10 +109,12 @@ export function ConfigTabs() {
   const [isAutoSavingCleanup, setIsAutoSavingCleanup] = useState<boolean>(false);
   const [isAutoSavingGitHub, setIsAutoSavingGitHub] = useState<boolean>(false);
   const [isAutoSavingGitea, setIsAutoSavingGitea] = useState<boolean>(false);
+  const [isAutoSavingNotification, setIsAutoSavingNotification] = useState<boolean>(false);
   const autoSaveScheduleTimeoutRef = useRef<NodeJS.Timeout | null>(null);
   const autoSaveCleanupTimeoutRef = useRef<NodeJS.Timeout | null>(null);
   const autoSaveGitHubTimeoutRef = useRef<NodeJS.Timeout | null>(null);
   const autoSaveGiteaTimeoutRef = useRef<NodeJS.Timeout | null>(null);
+  const autoSaveNotificationTimeoutRef = useRef<NodeJS.Timeout | null>(null);
 
   const isConfigFormValid = (): boolean => {
     const { githubConfig, giteaConfig } = config;
@@ -119,19 +141,31 @@ export function ConfigTabs() {
     if (!user?.id) return;
     setIsSyncing(true);
     try {
-      const result = await apiRequest<{ success: boolean; message?: string }>(
+      const result = await apiRequest<{ success: boolean; message?: string; failedOrgs?: string[]; recoveredOrgs?: number }>(
         `/sync?userId=${user.id}`,
         { method: 'POST' },
       );
-      result.success
-        ? toast.success(
-            'GitHub data imported successfully! Head to the Repositories page to start mirroring.',
-          )
-        : toast.error(
-            `Failed to import GitHub data: ${
-              result.message || 'Unknown error'
-            }`,
+      if (result.success) {
+        toast.success(
+          'GitHub data imported successfully! Head to the Repositories page to start mirroring.',
+        );
+        if (result.failedOrgs && result.failedOrgs.length > 0) {
+          toast.warning(
+            `${result.failedOrgs.length} org${result.failedOrgs.length > 1 ? 's' : ''} failed to import (${result.failedOrgs.join(', ')}). Check the Organizations tab for details.`,
           );
+        }
+        if (result.recoveredOrgs && result.recoveredOrgs > 0) {
+          toast.success(
+            `${result.recoveredOrgs} previously failed org${result.recoveredOrgs > 1 ? 's' : ''} recovered successfully.`,
+          );
+        }
+      } else {
+        toast.error(
+          `Failed to import GitHub data: ${
+            result.message || 'Unknown error'
+          }`,
+        );
+      }
     } catch (error) {
       toast.error(
         `Error importing GitHub data: ${
@@ -167,7 +201,7 @@ export function ConfigTabs() {
       };
 
       try {
-        const response = await fetch('/api/config', {
+        const response = await fetch(CONFIG_API_PATH, {
           method: 'POST',
           headers: { 'Content-Type': 'application/json' },
           body: JSON.stringify(reqPayload),
@@ -233,7 +267,7 @@ export function ConfigTabs() {
       };
 
       try {
-        const response = await fetch('/api/config', {
+        const response = await fetch(CONFIG_API_PATH, {
           method: 'POST',
           headers: { 'Content-Type': 'application/json' },
           body: JSON.stringify(reqPayload),
@@ -298,7 +332,7 @@ export function ConfigTabs() {
       };
 
       try {
-        const response = await fetch('/api/config', {
+        const response = await fetch(CONFIG_API_PATH, {
           method: 'POST',
           headers: { 'Content-Type': 'application/json' },
           body: JSON.stringify(reqPayload),
@@ -347,7 +381,7 @@ export function ConfigTabs() {
       };
 
       try {
-        const response = await fetch('/api/config', {
+        const response = await fetch(CONFIG_API_PATH, {
           method: 'POST',
           headers: { 'Content-Type': 'application/json' },
           body: JSON.stringify(reqPayload),
@@ -387,7 +421,7 @@ export function ConfigTabs() {
     };
 
     try {
-      const response = await fetch('/api/config', {
+      const response = await fetch(CONFIG_API_PATH, {
         method: 'POST',
         headers: { 'Content-Type': 'application/json' },
         body: JSON.stringify(reqPayload),
@@ -422,7 +456,7 @@ export function ConfigTabs() {
     };
 
     try {
-      const response = await fetch('/api/config', {
+      const response = await fetch(CONFIG_API_PATH, {
         method: 'POST',
         headers: { 'Content-Type': 'application/json' },
         body: JSON.stringify(reqPayload),
@@ -442,6 +476,55 @@ export function ConfigTabs() {
     }
   }, [user?.id, config.githubConfig, config.giteaConfig, config.scheduleConfig, config.cleanupConfig, config.mirrorOptions]);
 
+  // Auto-save function for notification config changes
+  const autoSaveNotificationConfig = useCallback(async (notifConfig: NotificationConfig) => {
+    if (!user?.id) return;
+
+    // Clear any existing timeout
+    if (autoSaveNotificationTimeoutRef.current) {
+      clearTimeout(autoSaveNotificationTimeoutRef.current);
+    }
+
+    // Debounce the auto-save to prevent excessive API calls
+    autoSaveNotificationTimeoutRef.current = setTimeout(async () => {
+      setIsAutoSavingNotification(true);
+
+      const reqPayload = {
+        userId: user.id!,
+        githubConfig: config.githubConfig,
+        giteaConfig: config.giteaConfig,
+        scheduleConfig: config.scheduleConfig,
+        cleanupConfig: config.cleanupConfig,
+        mirrorOptions: config.mirrorOptions,
+        advancedOptions: config.advancedOptions,
+        notificationConfig: notifConfig,
+      };
+
+      try {
+        const response = await fetch(CONFIG_API_PATH, {
+          method: 'POST',
+          headers: { 'Content-Type': 'application/json' },
+          body: JSON.stringify(reqPayload),
+        });
+        const result: SaveConfigApiResponse = await response.json();
+
+        if (result.success) {
+          // Silent success - no toast for auto-save
+          invalidateConfigCache();
+        } else {
+          showErrorToast(
+            `Auto-save failed: ${result.message || 'Unknown error'}`,
+            toast
+          );
+        }
+      } catch (error) {
+        showErrorToast(error, toast);
+      } finally {
+        setIsAutoSavingNotification(false);
+      }
+    }, 500); // 500ms debounce
+  }, [user?.id, config.githubConfig, config.giteaConfig, config.scheduleConfig, config.cleanupConfig, config.mirrorOptions, config.advancedOptions]);
+
   // Cleanup timeouts on unmount
   useEffect(() => {
     return () => {
@@ -457,6 +540,9 @@ export function ConfigTabs() {
       if (autoSaveGiteaTimeoutRef.current) {
         clearTimeout(autoSaveGiteaTimeoutRef.current);
       }
+      if (autoSaveNotificationTimeoutRef.current) {
+        clearTimeout(autoSaveNotificationTimeoutRef.current);
+      }
     };
   }, []);
 
@@ -488,6 +574,8 @@ export function ConfigTabs() {
             },
             advancedOptions:
               response.advancedOptions || config.advancedOptions,
+            notificationConfig:
+              (response as any).notificationConfig || config.notificationConfig,
           });
 
         }
@@ -617,9 +705,10 @@ export function ConfigTabs() {
 
       {/* Content section - Tabs layout */}
       <Tabs defaultValue="connections" className="space-y-4">
-        <TabsList className="grid w-full grid-cols-3">
+        <TabsList className="grid w-full grid-cols-4">
           <TabsTrigger value="connections">Connections</TabsTrigger>
           <TabsTrigger value="automation">Automation</TabsTrigger>
+          <TabsTrigger value="notifications">Notifications</TabsTrigger>
           <TabsTrigger value="sso">Authentication</TabsTrigger>
         </TabsList>
 
@@ -656,9 +745,20 @@ export function ConfigTabs() {
                       : update,
                 }))
               }
+              giteaConfig={config.giteaConfig}
+              setGiteaConfig={update =>
+                setConfig(prev => ({
+                  ...prev,
+                  giteaConfig:
+                    typeof update === 'function'
+                      ? update(prev.giteaConfig)
+                      : update,
+                }))
+              }
               onAutoSave={autoSaveGitHubConfig}
               onMirrorOptionsAutoSave={autoSaveMirrorOptions}
               onAdvancedOptionsAutoSave={autoSaveAdvancedOptions}
+              onGiteaAutoSave={autoSaveGiteaConfig}
               isAutoSaving={isAutoSavingGitHub}
             />
             <GiteaConfigForm
@@ -696,6 +796,17 @@ export function ConfigTabs() {
           />
         </TabsContent>
 
+        <TabsContent value="notifications" className="space-y-4">
+          <NotificationSettings
+            notificationConfig={config.notificationConfig}
+            onNotificationChange={(newConfig) => {
+              setConfig(prev => ({ ...prev, notificationConfig: newConfig }));
+              autoSaveNotificationConfig(newConfig);
+            }}
+            isAutoSaving={isAutoSavingNotification}
+          />
+        </TabsContent>
+
         <TabsContent value="sso" className="space-y-4">
           <SSOSettings />
         </TabsContent>

src/components/config/GitHubConfigForm.tsx

@@ -7,10 +7,11 @@ import {
   CardTitle,
 } from "@/components/ui/card";
 import { githubApi } from "@/lib/api";
-import type { GitHubConfig, MirrorOptions, AdvancedOptions } from "@/types/config";
+import type { GitHubConfig, MirrorOptions, AdvancedOptions, GiteaConfig, BackupStrategy } from "@/types/config";
 import { Input } from "../ui/input";
 import { toast } from "sonner";
-import { Info } from "lucide-react";
+import { Info, ShieldAlert } from "lucide-react";
+import { Badge } from "@/components/ui/badge";
 import { GitHubMirrorSettings } from "./GitHubMirrorSettings";
 import { Separator } from "../ui/separator";
 import {
@@ -26,23 +27,29 @@ interface GitHubConfigFormProps {
   setMirrorOptions: React.Dispatch<React.SetStateAction<MirrorOptions>>;
   advancedOptions: AdvancedOptions;
   setAdvancedOptions: React.Dispatch<React.SetStateAction<AdvancedOptions>>;
+  giteaConfig?: GiteaConfig;
+  setGiteaConfig?: React.Dispatch<React.SetStateAction<GiteaConfig>>;
   onAutoSave?: (githubConfig: GitHubConfig) => Promise<void>;
   onMirrorOptionsAutoSave?: (mirrorOptions: MirrorOptions) => Promise<void>;
   onAdvancedOptionsAutoSave?: (advancedOptions: AdvancedOptions) => Promise<void>;
+  onGiteaAutoSave?: (giteaConfig: GiteaConfig) => Promise<void>;
   isAutoSaving?: boolean;
 }
 
 export function GitHubConfigForm({ 
-  config, 
-  setConfig, 
+  config,
+  setConfig,
   mirrorOptions,
   setMirrorOptions,
   advancedOptions,
   setAdvancedOptions,
-  onAutoSave, 
+  giteaConfig,
+  setGiteaConfig,
+  onAutoSave,
   onMirrorOptionsAutoSave,
   onAdvancedOptionsAutoSave,
-  isAutoSaving 
+  onGiteaAutoSave,
+  isAutoSaving
 }: GitHubConfigFormProps) {
   const [isLoading, setIsLoading] = useState(false);
 
@@ -202,7 +209,161 @@ export function GitHubConfigForm({
             if (onAdvancedOptionsAutoSave) onAdvancedOptionsAutoSave(newOptions);
           }}
         />
-        
+
+        {giteaConfig && setGiteaConfig && (
+          <>
+            <Separator />
+
+            <div className="space-y-4">
+              <h3 className="text-sm font-medium flex items-center gap-2">
+                <ShieldAlert className="h-4 w-4 text-primary" />
+                Destructive Update Protection
+                <Badge variant="secondary" className="ml-2 text-[10px] px-1.5 py-0">BETA</Badge>
+              </h3>
+              <p className="text-xs text-muted-foreground">
+                Choose how to handle force-pushes or rewritten upstream history on GitHub.
+              </p>
+
+              <div className="grid grid-cols-2 md:grid-cols-4 gap-2">
+                {([
+                  {
+                    value: "disabled",
+                    label: "Disabled",
+                    desc: "No detection or backups",
+                  },
+                  {
+                    value: "always",
+                    label: "Always Backup",
+                    desc: "Snapshot before every sync (high disk usage)",
+                  },
+                  {
+                    value: "on-force-push",
+                    label: "Smart",
+                    desc: "Backup only on force-push",
+                  },
+                  {
+                    value: "block-on-force-push",
+                    label: "Block & Approve",
+                    desc: "Require approval on force-push",
+                  },
+                ] as const).map((opt) => {
+                  const isSelected = (giteaConfig.backupStrategy ?? "on-force-push") === opt.value;
+                  return (
+                    <button
+                      key={opt.value}
+                      type="button"
+                      onClick={() => {
+                        const newConfig = { ...giteaConfig, backupStrategy: opt.value as BackupStrategy };
+                        setGiteaConfig(newConfig);
+                        if (onGiteaAutoSave) onGiteaAutoSave(newConfig);
+                      }}
+                      className={`flex flex-col items-start gap-1 rounded-lg border p-3 text-left text-sm transition-colors ${
+                        isSelected
+                          ? "border-primary bg-primary/5 ring-1 ring-primary"
+                          : "border-input hover:bg-accent hover:text-accent-foreground"
+                      }`}
+                    >
+                      <span className="font-medium">{opt.label}</span>
+                      <span className="text-xs text-muted-foreground">{opt.desc}</span>
+                    </button>
+                  );
+                })}
+              </div>
+
+              {(giteaConfig.backupStrategy ?? "on-force-push") !== "disabled" && (
+                <>
+                  <div className="grid grid-cols-1 md:grid-cols-3 gap-4">
+                    <div>
+                      <label htmlFor="backup-retention" className="block text-sm font-medium mb-1.5">
+                        Snapshot retention count
+                      </label>
+                      <input
+                        id="backup-retention"
+                        name="backupRetentionCount"
+                        type="number"
+                        min={1}
+                        value={giteaConfig.backupRetentionCount ?? 5}
+                        onChange={(e) => {
+                          const newConfig = {
+                            ...giteaConfig,
+                            backupRetentionCount: Math.max(1, Number.parseInt(e.target.value, 10) || 5),
+                          };
+                          setGiteaConfig(newConfig);
+                          if (onGiteaAutoSave) onGiteaAutoSave(newConfig);
+                        }}
+                        className="w-full rounded-md border border-input bg-background px-3 py-2 text-sm shadow-sm transition-colors placeholder:text-muted-foreground focus-visible:outline-none focus-visible:ring-1 focus-visible:ring-ring"
+                      />
+                    </div>
+                    <div>
+                      <label htmlFor="backup-retention-days" className="block text-sm font-medium mb-1.5">
+                        Snapshot retention days
+                      </label>
+                      <input
+                        id="backup-retention-days"
+                        name="backupRetentionDays"
+                        type="number"
+                        min={0}
+                        value={giteaConfig.backupRetentionDays ?? 30}
+                        onChange={(e) => {
+                          const newConfig = {
+                            ...giteaConfig,
+                            backupRetentionDays: Math.max(0, Number.parseInt(e.target.value, 10) || 0),
+                          };
+                          setGiteaConfig(newConfig);
+                          if (onGiteaAutoSave) onGiteaAutoSave(newConfig);
+                        }}
+                        className="w-full rounded-md border border-input bg-background px-3 py-2 text-sm shadow-sm transition-colors placeholder:text-muted-foreground focus-visible:outline-none focus-visible:ring-1 focus-visible:ring-ring"
+                      />
+                      <p className="text-xs text-muted-foreground mt-1">0 = no time-based limit</p>
+                    </div>
+                    <div>
+                      <label htmlFor="backup-directory" className="block text-sm font-medium mb-1.5">
+                        Snapshot directory
+                      </label>
+                      <input
+                        id="backup-directory"
+                        name="backupDirectory"
+                        type="text"
+                        value={giteaConfig.backupDirectory || "data/repo-backups"}
+                        onChange={(e) => {
+                          const newConfig = { ...giteaConfig, backupDirectory: e.target.value };
+                          setGiteaConfig(newConfig);
+                          if (onGiteaAutoSave) onGiteaAutoSave(newConfig);
+                        }}
+                        className="w-full rounded-md border border-input bg-background px-3 py-2 text-sm shadow-sm transition-colors placeholder:text-muted-foreground focus-visible:outline-none focus-visible:ring-1 focus-visible:ring-ring"
+                        placeholder="data/repo-backups"
+                      />
+                    </div>
+                  </div>
+
+                  {((giteaConfig.backupStrategy ?? "on-force-push") === "always" ||
+                    (giteaConfig.backupStrategy ?? "on-force-push") === "on-force-push") && (
+                    <label className="flex items-start gap-3 text-sm">
+                      <input
+                        name="blockSyncOnBackupFailure"
+                        type="checkbox"
+                        checked={Boolean(giteaConfig.blockSyncOnBackupFailure)}
+                        onChange={(e) => {
+                          const newConfig = { ...giteaConfig, blockSyncOnBackupFailure: e.target.checked };
+                          setGiteaConfig(newConfig);
+                          if (onGiteaAutoSave) onGiteaAutoSave(newConfig);
+                        }}
+                        className="mt-0.5 rounded border-input"
+                      />
+                      <span>
+                        Block sync when snapshot fails
+                        <p className="text-xs text-muted-foreground">
+                          Recommended for backup-first behavior. If disabled, sync continues even when snapshot creation fails.
+                        </p>
+                      </span>
+                    </label>
+                  )}
+                </>
+              )}
+            </div>
+          </>
+        )}
+
         {/* Mobile: Show button at bottom */}
         <Button
           type="button"

src/components/config/GitHubMirrorSettings.tsx

@@ -4,6 +4,7 @@ import { Label } from "@/components/ui/label";
 import { Separator } from "@/components/ui/separator";
 import { Badge } from "@/components/ui/badge";
 import { Button } from "@/components/ui/button";
+import { Input } from "@/components/ui/input";
 import {
   Tooltip,
   TooltipContent,
@@ -17,6 +18,7 @@ import {
 } from "@/components/ui/popover";
 import {
   Info,
+  Check,
   GitBranch,
   Star,
   Lock,
@@ -31,7 +33,10 @@ import {
   ChevronDown,
   Funnel,
   HardDrive,
-  FileCode2
+  FileCode2,
+  Plus,
+  Users,
+  X
 } from "lucide-react";
 import type { GitHubConfig, MirrorOptions, AdvancedOptions, DuplicateNameStrategy } from "@/types/config";
 import {
@@ -41,7 +46,16 @@ import {
   SelectTrigger,
   SelectValue,
 } from "@/components/ui/select";
+import {
+  Command,
+  CommandEmpty,
+  CommandGroup,
+  CommandInput,
+  CommandItem,
+  CommandList,
+} from "@/components/ui/command";
 import { cn } from "@/lib/utils";
+import { githubApi } from "@/lib/api";
 
 interface GitHubMirrorSettingsProps {
   githubConfig: GitHubConfig;
@@ -60,8 +74,42 @@ export function GitHubMirrorSettings({
   onMirrorOptionsChange,
   onAdvancedOptionsChange,
 }: GitHubMirrorSettingsProps) {
-  
-  const handleGitHubChange = (field: keyof GitHubConfig, value: boolean | string) => {
+  const [starListsOpen, setStarListsOpen] = React.useState(false);
+  const [starListSearch, setStarListSearch] = React.useState("");
+  const [customStarListName, setCustomStarListName] = React.useState("");
+  const [availableStarLists, setAvailableStarLists] = React.useState<string[]>([]);
+  const [loadingStarLists, setLoadingStarLists] = React.useState(false);
+  const [loadedStarLists, setLoadedStarLists] = React.useState(false);
+  const [attemptedStarListLoad, setAttemptedStarListLoad] = React.useState(false);
+
+  const normalizeStarListNames = React.useCallback((lists: string[] | undefined): string[] => {
+    if (!Array.isArray(lists)) return [];
+
+    const seen = new Set<string>();
+    const normalized: string[] = [];
+    for (const list of lists) {
+      const trimmed = list.trim();
+      if (!trimmed) continue;
+      const key = trimmed.toLowerCase();
+      if (seen.has(key)) continue;
+      seen.add(key);
+      normalized.push(trimmed);
+    }
+
+    return normalized;
+  }, []);
+
+  const selectedStarLists = React.useMemo(
+    () => normalizeStarListNames(githubConfig.starredLists),
+    [githubConfig.starredLists, normalizeStarListNames],
+  );
+
+  const allKnownStarLists = React.useMemo(
+    () => normalizeStarListNames([...availableStarLists, ...selectedStarLists]),
+    [availableStarLists, selectedStarLists, normalizeStarListNames],
+  );
+
+  const handleGitHubChange = (field: keyof GitHubConfig, value: boolean | string | string[]) => {
     onGitHubConfigChange({ ...githubConfig, [field]: value });
   };
 
@@ -83,6 +131,59 @@ export function GitHubMirrorSettings({
     onAdvancedOptionsChange({ ...advancedOptions, [field]: value });
   };
 
+  const setSelectedStarLists = React.useCallback((lists: string[]) => {
+    onGitHubConfigChange({
+      ...githubConfig,
+      starredLists: normalizeStarListNames(lists),
+    });
+  }, [githubConfig, normalizeStarListNames, onGitHubConfigChange]);
+
+  const loadStarLists = React.useCallback(async () => {
+    if (
+      loadingStarLists ||
+      loadedStarLists ||
+      attemptedStarListLoad ||
+      !githubConfig.mirrorStarred
+    ) return;
+
+    setAttemptedStarListLoad(true);
+    setLoadingStarLists(true);
+    try {
+      const response = await githubApi.getStarredLists();
+      setAvailableStarLists(normalizeStarListNames(response.lists));
+      setLoadedStarLists(true);
+    } catch {
+      // Keep UX usable with manual custom input even if list fetch fails.
+      // Allow retry on next popover open.
+      setLoadedStarLists(false);
+    } finally {
+      setLoadingStarLists(false);
+    }
+  }, [
+    attemptedStarListLoad,
+    githubConfig.mirrorStarred,
+    loadedStarLists,
+    loadingStarLists,
+    normalizeStarListNames,
+  ]);
+
+  React.useEffect(() => {
+    if (!starListsOpen || !githubConfig.mirrorStarred) return;
+    void loadStarLists();
+  }, [starListsOpen, githubConfig.mirrorStarred, loadStarLists]);
+
+  React.useEffect(() => {
+    if (!githubConfig.mirrorStarred) {
+      setStarListsOpen(false);
+    }
+  }, [githubConfig.mirrorStarred]);
+
+  React.useEffect(() => {
+    if (!starListsOpen) {
+      setAttemptedStarListLoad(false);
+    }
+  }, [starListsOpen]);
+
   // When metadata is disabled, all components should be disabled
   const isMetadataEnabled = mirrorOptions.mirrorMetadata;
   
@@ -98,6 +199,17 @@ export function GitHubMirrorSettings({
   const starredContentCount = Object.entries(starredRepoContent).filter(([key, value]) => key !== 'code' && value).length;
   const totalStarredOptions = 4; // releases, issues, PRs, wiki
 
+  const normalizedStarListSearch = starListSearch.trim();
+  const canAddSearchAsStarList = normalizedStarListSearch.length > 0
+    && !allKnownStarLists.some((list) => list.toLowerCase() === normalizedStarListSearch.toLowerCase());
+
+  const addCustomStarList = () => {
+    const trimmed = customStarListName.trim();
+    if (!trimmed) return;
+    setSelectedStarLists([...selectedStarLists, trimmed]);
+    setCustomStarListName("");
+  };
+
   return (
     <div className="space-y-6">
       {/* Repository Selection Section */}
@@ -133,6 +245,26 @@ export function GitHubMirrorSettings({
             </div>
           </div>
 
+          <div className="flex items-start space-x-3">
+            <Checkbox
+              id="collaborator-repos"
+              checked={githubConfig.includeCollaboratorRepos ?? true}
+              onCheckedChange={(checked) => handleGitHubChange('includeCollaboratorRepos', !!checked)}
+            />
+            <div className="space-y-0.5 flex-1">
+              <Label
+                htmlFor="collaborator-repos"
+                className="text-sm font-normal cursor-pointer flex items-center gap-2"
+              >
+                <Users className="h-3.5 w-3.5" />
+                Include collaborator repositories
+              </Label>
+              <p className="text-xs text-muted-foreground">
+                Also mirror repos where you're a collaborator but not the owner. Turn off to limit imports to repos you own.
+              </p>
+            </div>
+          </div>
+
           <div className="grid grid-cols-1 md:grid-cols-2 gap-4">
             <div className="flex items-start space-x-3">
               <Checkbox
@@ -287,6 +419,168 @@ export function GitHubMirrorSettings({
             </div>
           </div>
 
+          {/* Auto-mirror starred repos toggle */}
+          {githubConfig.mirrorStarred && (
+            <div className="mt-4">
+              <div className="flex items-start space-x-3">
+                <Checkbox
+                  id="auto-mirror-starred"
+                  checked={advancedOptions.autoMirrorStarred ?? false}
+                  onCheckedChange={(checked) => handleAdvancedChange('autoMirrorStarred', !!checked)}
+                />
+                <div className="space-y-0.5 flex-1">
+                  <Label
+                    htmlFor="auto-mirror-starred"
+                    className="text-sm font-normal cursor-pointer flex items-center gap-2"
+                  >
+                    <Star className="h-3.5 w-3.5" />
+                    Auto-mirror new starred repositories
+                  </Label>
+                  <p className="text-xs text-muted-foreground">
+                    When disabled, starred repos are imported for browsing but not automatically mirrored. You can still mirror individual repos manually.
+                  </p>
+                </div>
+              </div>
+            </div>
+          )}
+
+          {/* Star list selection */}
+          {githubConfig.mirrorStarred && (
+            <div className="mt-4 space-y-2">
+              <Label className="text-xs font-medium text-muted-foreground">
+                Star Lists (optional)
+              </Label>
+              <Popover open={starListsOpen} onOpenChange={setStarListsOpen}>
+                <PopoverTrigger asChild>
+                  <Button
+                    variant="outline"
+                    role="combobox"
+                    aria-expanded={starListsOpen}
+                    className="w-full justify-between h-9 text-xs font-normal"
+                  >
+                    <span className="truncate text-left">
+                      {selectedStarLists.length === 0
+                        ? "All starred repositories"
+                        : `${selectedStarLists.length} list${selectedStarLists.length === 1 ? "" : "s"} selected`}
+                    </span>
+                    <ChevronDown className="ml-2 h-3 w-3 opacity-50 shrink-0" />
+                  </Button>
+                </PopoverTrigger>
+                <PopoverContent className="w-[360px] p-0" align="start">
+                  <Command>
+                    <CommandInput
+                      value={starListSearch}
+                      onValueChange={setStarListSearch}
+                      placeholder="Search GitHub star lists..."
+                    />
+                    <CommandList>
+                      <CommandEmpty>
+                        {loadingStarLists ? "Loading star lists..." : "No matching lists"}
+                      </CommandEmpty>
+                      <CommandGroup>
+                        {allKnownStarLists.map((list) => {
+                          const isSelected = selectedStarLists.some(
+                            (selected) => selected.toLowerCase() === list.toLowerCase(),
+                          );
+
+                          return (
+                            <CommandItem
+                              key={list}
+                              value={list}
+                              onSelect={() => {
+                                if (isSelected) {
+                                  setSelectedStarLists(
+                                    selectedStarLists.filter(
+                                      (selected) => selected.toLowerCase() !== list.toLowerCase(),
+                                    ),
+                                  );
+                                } else {
+                                  setSelectedStarLists([...selectedStarLists, list]);
+                                }
+                              }}
+                            >
+                              <Check
+                                className={cn(
+                                  "mr-2 h-4 w-4",
+                                  isSelected ? "opacity-100" : "opacity-0",
+                                )}
+                              />
+                              <span className="truncate">{list}</span>
+                            </CommandItem>
+                          );
+                        })}
+                      </CommandGroup>
+                    </CommandList>
+                  </Command>
+
+                  {canAddSearchAsStarList && (
+                    <div className="border-t p-2">
+                      <Button
+                        variant="ghost"
+                        size="sm"
+                        className="w-full justify-start text-xs"
+                        onClick={() => {
+                          setSelectedStarLists([...selectedStarLists, normalizedStarListSearch]);
+                          setStarListSearch("");
+                        }}
+                      >
+                        <Plus className="mr-2 h-3.5 w-3.5" />
+                        Add "{normalizedStarListSearch}"
+                      </Button>
+                    </div>
+                  )}
+                </PopoverContent>
+              </Popover>
+
+              <p className="text-xs text-muted-foreground">
+                Leave empty to mirror all starred repositories. Select one or more lists to limit syncing.
+              </p>
+
+              {selectedStarLists.length > 0 && (
+                <div className="flex flex-wrap gap-1.5">
+                  {selectedStarLists.map((list) => (
+                    <Badge key={list} variant="secondary" className="gap-1">
+                      <span>{list}</span>
+                      <button
+                        type="button"
+                        onClick={() =>
+                          setSelectedStarLists(
+                            selectedStarLists.filter(
+                              (selected) => selected.toLowerCase() !== list.toLowerCase(),
+                            ),
+                          )
+                        }
+                        className="rounded-sm hover:text-foreground/80"
+                        aria-label={`Remove ${list} list`}
+                      >
+                        <X className="h-3 w-3" />
+                      </button>
+                    </Badge>
+                  ))}
+                </div>
+              )}
+
+              <div className="flex items-center gap-2">
+                <Input
+                  value={customStarListName}
+                  onChange={(event) => setCustomStarListName(event.target.value)}
+                  placeholder="Add custom list name"
+                  className="h-8 text-xs"
+                />
+                <Button
+                  type="button"
+                  variant="outline"
+                  size="sm"
+                  className="h-8"
+                  onClick={addCustomStarList}
+                  disabled={!customStarListName.trim()}
+                >
+                  Add
+                </Button>
+              </div>
+            </div>
+          )}
+
           {/* Duplicate name handling for starred repos */}
           {githubConfig.mirrorStarred && (
             <div className="mt-4 space-y-2">

src/components/config/GiteaConfigForm.tsx

@@ -6,7 +6,9 @@ import {
   CardHeader,
   CardTitle,
 } from "@/components/ui/card";
-import { giteaApi } from "@/lib/api";
+import { Alert, AlertDescription, AlertTitle } from "@/components/ui/alert";
+import { AlertTriangle } from "lucide-react";
+import { giteaApi, type GiteaServerInfo } from "@/lib/api";
 import type { GiteaConfig, MirrorStrategy } from "@/types/config";
 import { toast } from "sonner";
 import { OrganizationStrategy } from "./OrganizationStrategy";
@@ -23,6 +25,7 @@ interface GiteaConfigFormProps {
 
 export function GiteaConfigForm({ config, setConfig, onAutoSave, isAutoSaving, githubUsername }: GiteaConfigFormProps) {
   const [isLoading, setIsLoading] = useState(false);
+  const [serverInfo, setServerInfo] = useState<GiteaServerInfo | null>(null);
   
   // Derive the mirror strategy from existing config for backward compatibility
   const getMirrorStrategy = (): MirrorStrategy => {
@@ -100,9 +103,14 @@ export function GiteaConfigForm({ config, setConfig, onAutoSave, isAutoSaving, g
       );
     }
 
+    const normalizedValue =
+      type === "checkbox"
+        ? checked
+        : value;
+
     const newConfig = {
       ...config,
-      [name]: type === "checkbox" ? checked : value,
+      [name]: normalizedValue,
     };
     setConfig(newConfig);
 
@@ -123,13 +131,16 @@ export function GiteaConfigForm({ config, setConfig, onAutoSave, isAutoSaving, g
     try {
       const result = await giteaApi.testConnection(config.url, config.token);
       if (result.success) {
+        setServerInfo(result.serverInfo ?? null);
         toast.success("Successfully connected to Gitea!");
       } else {
+        setServerInfo(null);
         toast.error(
           "Failed to connect to Gitea. Please check your URL and token."
         );
       }
     } catch (error) {
+      setServerInfo(null);
       toast.error(
         error instanceof Error ? error.message : "An unknown error occurred"
       );
@@ -157,6 +168,31 @@ export function GiteaConfigForm({ config, setConfig, onAutoSave, isAutoSaving, g
       </CardHeader>
 
       <CardContent className="flex flex-col gap-y-6 flex-1">
+        {serverInfo?.type === "forgejo" && serverInfo.hasMirrorCredBug && (
+          <Alert variant="warning">
+            <AlertTriangle className="h-4 w-4" />
+            <AlertTitle>
+              Forgejo {serverInfo.version} has a known mirror-credential bug
+            </AlertTitle>
+            <AlertDescription>
+              <p>
+                Pull-mirror credentials sent via Forgejo's migrate API aren't persisted on this version, so subsequent syncs of private repos fail with <code className="text-xs font-mono bg-amber-100 dark:bg-amber-900/40 px-1 py-0.5 rounded">terminal prompts disabled</code>. Fixed in Forgejo 15.0.0 (
+                <a
+                  href="https://codeberg.org/forgejo/forgejo/pulls/11909"
+                  target="_blank"
+                  rel="noopener noreferrer"
+                  className="underline underline-offset-2"
+                >
+                  PR #11909
+                </a>
+                ).
+              </p>
+              <p>
+                Upgrade Forgejo to 15.0.0 or later, then delete and re-mirror affected repos — or open each repo's Settings → Mirror Settings in Forgejo and re-enter the GitHub token once.
+              </p>
+            </AlertDescription>
+          </Alert>
+        )}
         <div>
           <label
             htmlFor="gitea-username"
@@ -286,7 +322,7 @@ export function GiteaConfigForm({ config, setConfig, onAutoSave, isAutoSaving, g
             if (onAutoSave) onAutoSave(newConfig);
           }}
         />
-        
+
         {/* Mobile: Show button at bottom */}
         <Button
           type="button"

src/components/config/NotificationSettings.tsx

@@ -0,0 +1,395 @@
+import { useState } from "react";
+import { Card, CardContent, CardHeader, CardTitle } from "@/components/ui/card";
+import { Label } from "@/components/ui/label";
+import { Input } from "@/components/ui/input";
+import {
+  Select,
+  SelectContent,
+  SelectItem,
+  SelectTrigger,
+  SelectValue,
+} from "@/components/ui/select";
+import { Switch } from "@/components/ui/switch";
+import { Button } from "@/components/ui/button";
+import { Bell, Activity, Send } from "lucide-react";
+import { toast } from "sonner";
+import type { NotificationConfig } from "@/types/config";
+import { withBase } from "@/lib/base-path";
+
+interface NotificationSettingsProps {
+  notificationConfig: NotificationConfig;
+  onNotificationChange: (config: NotificationConfig) => void;
+  isAutoSaving?: boolean;
+}
+
+export function NotificationSettings({
+  notificationConfig,
+  onNotificationChange,
+  isAutoSaving,
+}: NotificationSettingsProps) {
+  const [isTesting, setIsTesting] = useState(false);
+
+  const handleTestNotification = async () => {
+    setIsTesting(true);
+    try {
+      const resp = await fetch(withBase("/api/notifications/test"), {
+        method: "POST",
+        headers: { "Content-Type": "application/json" },
+        body: JSON.stringify({ notificationConfig }),
+      });
+      const result = await resp.json();
+      if (result.success) {
+        toast.success("Test notification sent successfully!");
+      } else {
+        toast.error(`Test failed: ${result.error || "Unknown error"}`);
+      }
+    } catch (error) {
+      toast.error(
+        `Test failed: ${error instanceof Error ? error.message : String(error)}`
+      );
+    } finally {
+      setIsTesting(false);
+    }
+  };
+
+  return (
+    <Card className="w-full">
+      <CardHeader>
+        <CardTitle className="text-lg font-semibold flex items-center gap-2">
+          <Bell className="h-5 w-5" />
+          Notifications
+          {isAutoSaving && (
+            <Activity className="h-4 w-4 animate-spin text-muted-foreground ml-2" />
+          )}
+        </CardTitle>
+      </CardHeader>
+
+      <CardContent className="space-y-6">
+        {/* Enable/disable toggle */}
+        <div className="flex items-center justify-between">
+          <div className="space-y-0.5">
+            <Label htmlFor="notifications-enabled" className="text-sm font-medium cursor-pointer">
+              Enable notifications
+            </Label>
+            <p className="text-xs text-muted-foreground">
+              Receive alerts when mirror jobs complete or fail
+            </p>
+          </div>
+          <Switch
+            id="notifications-enabled"
+            checked={notificationConfig.enabled}
+            onCheckedChange={(checked) =>
+              onNotificationChange({ ...notificationConfig, enabled: checked })
+            }
+          />
+        </div>
+
+        {notificationConfig.enabled && (
+          <>
+            {/* Provider selector */}
+            <div className="space-y-2">
+              <Label htmlFor="notification-provider" className="text-sm font-medium">
+                Notification provider
+              </Label>
+              <Select
+                value={notificationConfig.provider}
+                onValueChange={(value: "ntfy" | "apprise") =>
+                  onNotificationChange({ ...notificationConfig, provider: value })
+                }
+              >
+                <SelectTrigger id="notification-provider">
+                  <SelectValue />
+                </SelectTrigger>
+                <SelectContent>
+                  <SelectItem value="ntfy">Ntfy.sh</SelectItem>
+                  <SelectItem value="apprise">Apprise API</SelectItem>
+                </SelectContent>
+              </Select>
+            </div>
+
+            {/* Ntfy configuration */}
+            {notificationConfig.provider === "ntfy" && (
+              <div className="space-y-4 p-4 border border-border rounded-lg bg-card/50">
+                <h3 className="text-sm font-medium">Ntfy.sh Settings</h3>
+
+                <div className="space-y-2">
+                  <Label htmlFor="ntfy-url" className="text-sm">
+                    Server URL
+                  </Label>
+                  <Input
+                    id="ntfy-url"
+                    type="url"
+                    placeholder="https://ntfy.sh"
+                    value={notificationConfig.ntfy?.url || "https://ntfy.sh"}
+                    onChange={(e) =>
+                      onNotificationChange({
+                        ...notificationConfig,
+                        ntfy: {
+                          ...notificationConfig.ntfy!,
+                          url: e.target.value,
+                          topic: notificationConfig.ntfy?.topic || "",
+                          priority: notificationConfig.ntfy?.priority || "default",
+                        },
+                      })
+                    }
+                  />
+                  <p className="text-xs text-muted-foreground">
+                    Use https://ntfy.sh for the public server or your self-hosted instance URL
+                  </p>
+                </div>
+
+                <div className="space-y-2">
+                  <Label htmlFor="ntfy-topic" className="text-sm">
+                    Topic <span className="text-destructive">*</span>
+                  </Label>
+                  <Input
+                    id="ntfy-topic"
+                    placeholder="gitea-mirror"
+                    value={notificationConfig.ntfy?.topic || ""}
+                    onChange={(e) =>
+                      onNotificationChange({
+                        ...notificationConfig,
+                        ntfy: {
+                          ...notificationConfig.ntfy!,
+                          url: notificationConfig.ntfy?.url || "https://ntfy.sh",
+                          topic: e.target.value,
+                          priority: notificationConfig.ntfy?.priority || "default",
+                        },
+                      })
+                    }
+                  />
+                  <p className="text-xs text-muted-foreground">
+                    Choose a unique topic name. Anyone with the topic name can subscribe.
+                  </p>
+                </div>
+
+                <div className="space-y-2">
+                  <Label htmlFor="ntfy-token" className="text-sm">
+                    Access token (optional)
+                  </Label>
+                  <Input
+                    id="ntfy-token"
+                    type="password"
+                    placeholder="tk_..."
+                    value={notificationConfig.ntfy?.token || ""}
+                    onChange={(e) =>
+                      onNotificationChange({
+                        ...notificationConfig,
+                        ntfy: {
+                          ...notificationConfig.ntfy!,
+                          url: notificationConfig.ntfy?.url || "https://ntfy.sh",
+                          topic: notificationConfig.ntfy?.topic || "",
+                          token: e.target.value,
+                          priority: notificationConfig.ntfy?.priority || "default",
+                        },
+                      })
+                    }
+                  />
+                  <p className="text-xs text-muted-foreground">
+                    Required if your ntfy server uses authentication
+                  </p>
+                </div>
+
+                <div className="space-y-2">
+                  <Label htmlFor="ntfy-priority" className="text-sm">
+                    Default priority
+                  </Label>
+                  <Select
+                    value={notificationConfig.ntfy?.priority || "default"}
+                    onValueChange={(value: "min" | "low" | "default" | "high" | "urgent") =>
+                      onNotificationChange({
+                        ...notificationConfig,
+                        ntfy: {
+                          ...notificationConfig.ntfy!,
+                          url: notificationConfig.ntfy?.url || "https://ntfy.sh",
+                          topic: notificationConfig.ntfy?.topic || "",
+                          priority: value,
+                        },
+                      })
+                    }
+                  >
+                    <SelectTrigger id="ntfy-priority">
+                      <SelectValue />
+                    </SelectTrigger>
+                    <SelectContent>
+                      <SelectItem value="min">Min</SelectItem>
+                      <SelectItem value="low">Low</SelectItem>
+                      <SelectItem value="default">Default</SelectItem>
+                      <SelectItem value="high">High</SelectItem>
+                      <SelectItem value="urgent">Urgent</SelectItem>
+                    </SelectContent>
+                  </Select>
+                  <p className="text-xs text-muted-foreground">
+                    Error notifications always use "high" priority regardless of this setting
+                  </p>
+                </div>
+              </div>
+            )}
+
+            {/* Apprise configuration */}
+            {notificationConfig.provider === "apprise" && (
+              <div className="space-y-4 p-4 border border-border rounded-lg bg-card/50">
+                <h3 className="text-sm font-medium">Apprise API Settings</h3>
+
+                <div className="space-y-2">
+                  <Label htmlFor="apprise-url" className="text-sm">
+                    Server URL <span className="text-destructive">*</span>
+                  </Label>
+                  <Input
+                    id="apprise-url"
+                    type="url"
+                    placeholder="http://apprise:8000"
+                    value={notificationConfig.apprise?.url || ""}
+                    onChange={(e) =>
+                      onNotificationChange({
+                        ...notificationConfig,
+                        apprise: {
+                          ...notificationConfig.apprise!,
+                          url: e.target.value,
+                          token: notificationConfig.apprise?.token || "",
+                        },
+                      })
+                    }
+                  />
+                  <p className="text-xs text-muted-foreground">
+                    URL of your Apprise API server (e.g., http://apprise:8000)
+                  </p>
+                </div>
+
+                <div className="space-y-2">
+                  <Label htmlFor="apprise-token" className="text-sm">
+                    Token / path <span className="text-destructive">*</span>
+                  </Label>
+                  <Input
+                    id="apprise-token"
+                    placeholder="gitea-mirror"
+                    value={notificationConfig.apprise?.token || ""}
+                    onChange={(e) =>
+                      onNotificationChange({
+                        ...notificationConfig,
+                        apprise: {
+                          ...notificationConfig.apprise!,
+                          url: notificationConfig.apprise?.url || "",
+                          token: e.target.value,
+                        },
+                      })
+                    }
+                  />
+                  <p className="text-xs text-muted-foreground">
+                    The Apprise API configuration token or key
+                  </p>
+                </div>
+
+                <div className="space-y-2">
+                  <Label htmlFor="apprise-tag" className="text-sm">
+                    Tag filter (optional)
+                  </Label>
+                  <Input
+                    id="apprise-tag"
+                    placeholder="all"
+                    value={notificationConfig.apprise?.tag || ""}
+                    onChange={(e) =>
+                      onNotificationChange({
+                        ...notificationConfig,
+                        apprise: {
+                          ...notificationConfig.apprise!,
+                          url: notificationConfig.apprise?.url || "",
+                          token: notificationConfig.apprise?.token || "",
+                          tag: e.target.value,
+                        },
+                      })
+                    }
+                  />
+                  <p className="text-xs text-muted-foreground">
+                    Optional tag to filter which Apprise services receive notifications
+                  </p>
+                </div>
+              </div>
+            )}
+
+            {/* Event toggles */}
+            <div className="space-y-4 p-4 border border-border rounded-lg bg-card/50">
+              <h3 className="text-sm font-medium">Notification Events</h3>
+
+              <div className="flex items-center justify-between">
+                <div className="space-y-0.5">
+                  <Label htmlFor="notify-sync-error" className="text-sm font-normal cursor-pointer">
+                    Sync errors
+                  </Label>
+                  <p className="text-xs text-muted-foreground">
+                    Notify when a mirror job fails
+                  </p>
+                </div>
+                <Switch
+                  id="notify-sync-error"
+                  checked={notificationConfig.notifyOnSyncError}
+                  onCheckedChange={(checked) =>
+                    onNotificationChange({ ...notificationConfig, notifyOnSyncError: checked })
+                  }
+                />
+              </div>
+
+              <div className="flex items-center justify-between">
+                <div className="space-y-0.5">
+                  <Label htmlFor="notify-sync-success" className="text-sm font-normal cursor-pointer">
+                    Sync success
+                  </Label>
+                  <p className="text-xs text-muted-foreground">
+                    Notify when a mirror job completes successfully
+                  </p>
+                </div>
+                <Switch
+                  id="notify-sync-success"
+                  checked={notificationConfig.notifyOnSyncSuccess}
+                  onCheckedChange={(checked) =>
+                    onNotificationChange({ ...notificationConfig, notifyOnSyncSuccess: checked })
+                  }
+                />
+              </div>
+
+              <div className="flex items-center justify-between">
+                <div className="space-y-0.5">
+                  <Label htmlFor="notify-new-repo" className="text-sm font-normal cursor-pointer text-muted-foreground">
+                    New repository discovered (coming soon)
+                  </Label>
+                  <p className="text-xs text-muted-foreground">
+                    Notify when a new GitHub repository is auto-imported
+                  </p>
+                </div>
+                <Switch
+                  id="notify-new-repo"
+                  checked={notificationConfig.notifyOnNewRepo}
+                  disabled
+                  onCheckedChange={(checked) =>
+                    onNotificationChange({ ...notificationConfig, notifyOnNewRepo: checked })
+                  }
+                />
+              </div>
+            </div>
+
+            {/* Test button */}
+            <div className="flex justify-end">
+              <Button
+                variant="outline"
+                onClick={handleTestNotification}
+                disabled={isTesting}
+              >
+                {isTesting ? (
+                  <>
+                    <Activity className="h-4 w-4 animate-spin mr-2" />
+                    Sending...
+                  </>
+                ) : (
+                  <>
+                    <Send className="h-4 w-4 mr-2" />
+                    Send Test Notification
+                  </>
+                )}
+              </Button>
+            </div>
+          </>
+        )}
+      </CardContent>
+    </Card>
+  );
+}

src/components/config/SSOSettings.tsx

@@ -14,6 +14,7 @@ import { Badge } from '../ui/badge';
 import { Tabs, TabsContent, TabsList, TabsTrigger } from '@/components/ui/tabs';
 import { Textarea } from '@/components/ui/textarea';
 import { MultiSelect } from '@/components/ui/multi-select';
+import { withBase } from '@/lib/base-path';
 
 function isTrustedIssuer(issuer: string, allowedHosts: string[]): boolean {
   try {
@@ -100,6 +101,9 @@ export function SSOSettings() {
     digestAlgorithm: 'sha256',
     identifierFormat: 'urn:oasis:names:tc:SAML:1.1:nameid-format:emailAddress',
   });
+  const appOrigin = typeof window !== 'undefined' ? window.location.origin : '';
+  const buildAbsoluteAppUrl = (path: string) =>
+    appOrigin ? new URL(withBase(path), appOrigin).toString() : withBase(path);
 
 
 
@@ -179,8 +183,8 @@ export function SSOSettings() {
       } else {
         requestData.entryPoint = providerForm.entryPoint;
         requestData.cert = providerForm.cert;
-        requestData.callbackUrl = providerForm.callbackUrl || `${window.location.origin}/api/auth/sso/saml2/callback/${providerForm.providerId}`;
-        requestData.audience = providerForm.audience || window.location.origin;
+        requestData.callbackUrl = providerForm.callbackUrl || buildAbsoluteAppUrl(`/api/auth/sso/saml2/callback/${providerForm.providerId}`);
+        requestData.audience = providerForm.audience || appOrigin;
         requestData.wantAssertionsSigned = providerForm.wantAssertionsSigned;
         requestData.signatureAlgorithm = providerForm.signatureAlgorithm;
         requestData.digestAlgorithm = providerForm.digestAlgorithm;
@@ -517,7 +521,7 @@ export function SSOSettings() {
                           <AlertCircle className="h-4 w-4" />
                           <AlertDescription>
                             <div className="space-y-2">
-                              <p>Redirect URL: {window.location.origin}/api/auth/sso/callback/{providerForm.providerId || '{provider-id}'}</p>
+                              <p>Redirect URL: {buildAbsoluteAppUrl(`/api/auth/sso/callback/${providerForm.providerId || '{provider-id}'}`)}</p>
                               {isTrustedIssuer(providerForm.issuer, ['google.com']) && (
                                 <p className="text-xs text-muted-foreground">
                                   Note: Google doesn't support the "offline_access" scope. Make sure to exclude it from the selected scopes.
@@ -563,8 +567,8 @@ export function SSOSettings() {
                           <AlertCircle className="h-4 w-4" />
                           <AlertDescription>
                             <div className="space-y-1">
-                              <p>Callback URL: {window.location.origin}/api/auth/sso/saml2/callback/{providerForm.providerId || '{provider-id}'}</p>
-                              <p>SP Metadata: {window.location.origin}/api/auth/sso/saml2/sp/metadata?providerId={providerForm.providerId || '{provider-id}'}</p>
+                              <p>Callback URL: {buildAbsoluteAppUrl(`/api/auth/sso/saml2/callback/${providerForm.providerId || '{provider-id}'}`)}</p>
+                              <p>SP Metadata: {buildAbsoluteAppUrl(`/api/auth/sso/saml2/sp/metadata?providerId=${providerForm.providerId || '{provider-id}'}`)}</p>
                             </div>
                           </AlertDescription>
                         </Alert>
@@ -724,4 +728,4 @@ export function SSOSettings() {
       </Card>
     </div>
   );
-}
+}

src/components/dashboard/Dashboard.tsx

@@ -16,6 +16,7 @@ import { useLiveRefresh } from "@/hooks/useLiveRefresh";
 import { usePageVisibility } from "@/hooks/usePageVisibility";
 import { useConfigStatus } from "@/hooks/useConfigStatus";
 import { useNavigation } from "@/components/layout/MainLayout";
+import { withBase } from "@/lib/base-path";
 
 // Helper function to format last sync time
 function formatLastSyncTime(date: Date | null): string {
@@ -110,7 +111,7 @@ export function Dashboard() {
   useEffectForToasts(() => {
     if (!user?.id) return;
 
-    const eventSource = new EventSource(`/api/events?userId=${user.id}`);
+    const eventSource = new EventSource(`${withBase("/api/events")}?userId=${user.id}`);
     
     eventSource.addEventListener("rate-limit", (event) => {
       try {

src/components/dashboard/RecentActivity.tsx

@@ -3,6 +3,7 @@ import type { MirrorJob } from "@/lib/db/schema";
 import { formatDate, getStatusColor } from "@/lib/utils";
 import { Button } from "../ui/button";
 import { Activity, Clock } from "lucide-react";
+import { withBase } from "@/lib/base-path";
 
 interface RecentActivityProps {
   activities: MirrorJob[];
@@ -14,7 +15,7 @@ export function RecentActivity({ activities }: RecentActivityProps) {
       <CardHeader className="flex flex-row items-center justify-between">
         <CardTitle>Recent Activity</CardTitle>
         <Button variant="outline" asChild>
-          <a href="/activity">View All</a>
+          <a href={withBase("/activity")}>View All</a>
         </Button>
       </CardHeader>
       <CardContent>
@@ -27,7 +28,7 @@ export function RecentActivity({ activities }: RecentActivityProps) {
             </p>
             <div className="flex gap-2">
               <Button variant="outline" size="sm" asChild>
-                <a href="/activity">
+                <a href={withBase("/activity")}>
                   <Activity className="h-3.5 w-3.5 mr-1.5" />
                   View History
                 </a>

src/components/dashboard/RepositoryList.tsx

@@ -4,7 +4,9 @@ import { GitFork } from "lucide-react";
 import { SiGithub, SiGitea } from "react-icons/si";
 import type { Repository } from "@/lib/db/schema";
 import { getStatusColor } from "@/lib/utils";
+import { buildGiteaWebUrl } from "@/lib/gitea-url";
 import { useGiteaConfig } from "@/hooks/useGiteaConfig";
+import { withBase } from "@/lib/base-path";
 
 interface RepositoryListProps {
   repositories: Repository[];
@@ -15,11 +17,6 @@ export function RepositoryList({ repositories }: RepositoryListProps) {
 
   // Helper function to construct Gitea repository URL
   const getGiteaRepoUrl = (repository: Repository): string | null => {
-    const rawBaseUrl = giteaConfig?.externalUrl || giteaConfig?.url;
-    if (!rawBaseUrl) {
-      return null;
-    }
-
     // Only provide Gitea links for repositories that have been or are being mirrored
     const validStatuses = ['mirroring', 'mirrored', 'syncing', 'synced'];
     if (!validStatuses.includes(repository.status)) {
@@ -38,12 +35,7 @@ export function RepositoryList({ repositories }: RepositoryListProps) {
       repoPath = `${owner}/${repository.name}`;
     }
 
-    // Ensure the base URL doesn't have a trailing slash
-    const baseUrl = rawBaseUrl.endsWith("/")
-      ? rawBaseUrl.slice(0, -1)
-      : rawBaseUrl;
-
-    return `${baseUrl}/${repoPath}`;
+    return buildGiteaWebUrl(giteaConfig, repoPath);
   };
 
   return (
@@ -51,7 +43,7 @@ export function RepositoryList({ repositories }: RepositoryListProps) {
       <CardHeader className="flex flex-row items-center justify-between">
         <CardTitle>Repositories</CardTitle>
         <Button variant="outline" asChild>
-          <a href="/repositories">View All</a>
+          <a href={withBase("/repositories")}>View All</a>
         </Button>
       </CardHeader>
       <CardContent>
@@ -63,7 +55,7 @@ export function RepositoryList({ repositories }: RepositoryListProps) {
               Configure your GitHub connection to start mirroring repositories.
             </p>
             <Button asChild>
-              <a href="/config">Configure GitHub</a>
+              <a href={withBase("/config")}>Configure GitHub</a>
             </Button>
           </div>
         ) : (

src/components/layout/Header.tsx

@@ -2,18 +2,12 @@ import { useAuth } from "@/hooks/useAuth";
 import { Button } from "@/components/ui/button";
 
 import { ModeToggle } from "@/components/theme/ModeToggle";
-import { Avatar, AvatarFallback, AvatarImage } from "../ui/avatar";
-import { toast } from "sonner";
 import { Skeleton } from "@/components/ui/skeleton";
 import { useLiveRefresh } from "@/hooks/useLiveRefresh";
 import { useConfigStatus } from "@/hooks/useConfigStatus";
-import { Menu, LogOut, PanelRightOpen, PanelRightClose } from "lucide-react";
-import {
-  DropdownMenu,
-  DropdownMenuContent,
-  DropdownMenuItem,
-  DropdownMenuTrigger,
-} from "@/components/ui/dropdown-menu";
+import { PanelRightOpen, PanelRightClose } from "lucide-react";
+import { AccountMenu } from "@/components/auth/AccountMenu";
+import { withBase } from "@/lib/base-path";
 
 interface HeaderProps {
   currentPage?: "dashboard" | "repositories" | "organizations" | "configuration" | "activity-log";
@@ -25,7 +19,7 @@ interface HeaderProps {
 }
 
 export function Header({ currentPage, onNavigate, onMenuClick, onToggleCollapse, isSidebarCollapsed, isSidebarOpen }: HeaderProps) {
-  const { user, logout, isLoading } = useAuth();
+  const { isLoading } = useAuth();
   const { isLiveEnabled, toggleLive } = useLiveRefresh();
   const { isFullyConfigured, isLoading: configLoading } = useConfigStatus();
 
@@ -46,13 +40,6 @@ export function Header({ currentPage, onNavigate, onMenuClick, onToggleCollapse,
     return isLiveEnabled ? 'Disable live refresh' : 'Enable live refresh';
   };
 
-  const handleLogout = async () => {
-    toast.success("Logged out successfully");
-    // Small delay to show the toast before redirecting
-    await new Promise((resolve) => setTimeout(resolve, 500));
-    logout();
-  };
-
   // Auth buttons skeleton loader
   function AuthButtonsSkeleton() {
     return (
@@ -101,14 +88,14 @@ export function Header({ currentPage, onNavigate, onMenuClick, onToggleCollapse,
           <button
             onClick={() => {
               if (currentPage !== 'dashboard') {
-                window.history.pushState({}, '', '/');
+                window.history.pushState({}, '', withBase('/'));
                 onNavigate?.('dashboard');
               }
             }}
             className="flex items-center gap-2 py-1 hover:opacity-80 transition-opacity"
           >
             <img
-              src="/logo.png"
+              src={withBase('/logo.png')}
               alt="Gitea Mirror Logo"
               className="h-5 w-6"
             />
@@ -140,32 +127,7 @@ export function Header({ currentPage, onNavigate, onMenuClick, onToggleCollapse,
 
           <ModeToggle />
 
-          {isLoading ? (
-            <AuthButtonsSkeleton />
-          ) : user ? (
-            <DropdownMenu>
-              <DropdownMenuTrigger asChild>
-                <Button variant="outline" size="lg" className="relative h-10 w-10 rounded-full p-0">
-                  <Avatar className="h-full w-full">
-                    <AvatarImage src={user.image || ""} alt={user.name || user.email} />
-                    <AvatarFallback>
-                      {(user.name || user.email || "U").charAt(0).toUpperCase()}
-                    </AvatarFallback>
-                  </Avatar>
-                </Button>
-              </DropdownMenuTrigger>
-              <DropdownMenuContent align="end" className="w-48">
-                <DropdownMenuItem onClick={handleLogout} className="cursor-pointer">
-                  <LogOut className="h-4 w-4 mr-2" />
-                  Logout
-                </DropdownMenuItem>
-              </DropdownMenuContent>
-            </DropdownMenu>
-          ) : (
-            <Button variant="outline" size="sm" asChild>
-              <a href="/login">Login</a>
-            </Button>
-          )}
+          {isLoading ? <AuthButtonsSkeleton /> : <AccountMenu />}
         </div>
       </div>
     </header>

src/components/layout/MainLayout.tsx

@@ -11,6 +11,7 @@ import { Toaster } from "@/components/ui/sonner";
 import { useAuth } from "@/hooks/useAuth";
 import { useRepoSync } from "@/hooks/useSyncRepo";
 import { useConfigStatus } from "@/hooks/useConfigStatus";
+import { stripBasePath, withBase } from "@/lib/base-path";
 
 // Navigation context to signal when navigation happens
 const NavigationContext = createContext<{ navigationKey: number }>({ navigationKey: 0 });
@@ -71,7 +72,7 @@ function AppWithProviders({ page: initialPage }: AppProps) {
   // Handle browser back/forward navigation
   useEffect(() => {
     const handlePopState = () => {
-      const path = window.location.pathname;
+      const path = stripBasePath(window.location.pathname);
       const pageMap: Record<string, AppProps['page']> = {
         '/': 'dashboard',
         '/repositories': 'repositories',
@@ -125,7 +126,7 @@ function AppWithProviders({ page: initialPage }: AppProps) {
   if (!authLoading && !user) {
     // Use window.location for client-side redirect
     if (typeof window !== 'undefined') {
-      window.location.href = '/login';
+      window.location.href = withBase('/login');
     }
     return null;
   }

src/components/layout/Sidebar.tsx

@@ -9,6 +9,7 @@ import {
   TooltipProvider,
   TooltipTrigger,
 } from "@/components/ui/tooltip";
+import { stripBasePath, withBase } from "@/lib/base-path";
 
 interface SidebarProps {
   className?: string;
@@ -24,14 +25,14 @@ export function Sidebar({ className, onNavigate, isOpen, isCollapsed = false, on
 
   useEffect(() => {
     // Hydration happens here
-    const path = window.location.pathname;
+    const path = stripBasePath(window.location.pathname);
     setCurrentPath(path);
   }, []);
 
   // Listen for URL changes (browser back/forward)
   useEffect(() => {
     const handlePopState = () => {
-      setCurrentPath(window.location.pathname);
+      setCurrentPath(stripBasePath(window.location.pathname));
     };
 
     window.addEventListener('popstate', handlePopState);
@@ -45,7 +46,7 @@ export function Sidebar({ className, onNavigate, isOpen, isCollapsed = false, on
     if (currentPath === href) return;
 
     // Update URL without page reload
-    window.history.pushState({}, '', href);
+    window.history.pushState({}, '', withBase(href));
     setCurrentPath(href);
 
     // Map href to page name for the parent component
@@ -163,7 +164,7 @@ export function Sidebar({ className, onNavigate, isOpen, isCollapsed = false, on
                   Check out the documentation for help with setup and configuration.
                 </p>
                 <a
-                  href="/docs"
+                  href={withBase("/docs")}
                   target="_blank"
                   rel="noopener noreferrer"
                   className="inline-flex items-center gap-1.5 text-xs md:text-xs text-primary hover:underline py-2 md:py-0"
@@ -177,7 +178,7 @@ export function Sidebar({ className, onNavigate, isOpen, isCollapsed = false, on
                 <Tooltip delayDuration={0}>
                   <TooltipTrigger asChild>
                     <a
-                      href="/docs"
+                      href={withBase("/docs")}
                       target="_blank"
                       rel="noopener noreferrer"
                       className={cn(

src/components/organizations/OrganizationsList.tsx

@@ -9,8 +9,10 @@ import type { FilterParams } from "@/types/filter";
 import Fuse from "fuse.js";
 import { Skeleton } from "@/components/ui/skeleton";
 import { cn } from "@/lib/utils";
+import { buildGiteaWebUrl } from "@/lib/gitea-url";
 import { MirrorDestinationEditor } from "./MirrorDestinationEditor";
 import { useGiteaConfig } from "@/hooks/useGiteaConfig";
+import { withBase } from "@/lib/base-path";
 import {
   DropdownMenu,
   DropdownMenuContent,
@@ -67,11 +69,6 @@ export function OrganizationList({
 
   // Helper function to construct Gitea organization URL
   const getGiteaOrgUrl = (organization: Organization): string | null => {
-    const rawBaseUrl = giteaConfig?.externalUrl || giteaConfig?.url;
-    if (!rawBaseUrl) {
-      return null;
-    }
-
     // Only provide Gitea links for organizations that have been mirrored
     const validStatuses = ['mirroring', 'mirrored'];
     if (!validStatuses.includes(organization.status || '')) {
@@ -84,17 +81,12 @@ export function OrganizationList({
       return null;
     }
 
-    // Ensure the base URL doesn't have a trailing slash
-    const baseUrl = rawBaseUrl.endsWith("/")
-      ? rawBaseUrl.slice(0, -1)
-      : rawBaseUrl;
-
-    return `${baseUrl}/${orgName}`;
+    return buildGiteaWebUrl(giteaConfig, orgName);
   };
 
   const handleUpdateDestination = async (orgId: string, newDestination: string | null) => {
     // Call API to update organization destination
-    const response = await fetch(`/api/organizations/${orgId}`, {
+    const response = await fetch(`${withBase("/api/organizations")}/${orgId}`, {
       method: "PATCH",
       headers: {
         "Content-Type": "application/json",
@@ -198,7 +190,7 @@ export function OrganizationList({
                   <div className="flex items-center gap-2 min-w-0">
                     <Building2 className="h-5 w-5 text-muted-foreground flex-shrink-0" />
                     <a 
-                      href={`/repositories?organization=${encodeURIComponent(org.name || '')}`}
+                      href={`${withBase('/repositories')}?organization=${encodeURIComponent(org.name || '')}`}
                       className="font-medium hover:underline cursor-pointer truncate"
                     >
                       {org.name}
@@ -248,6 +240,11 @@ export function OrganizationList({
                 </div>
               </div>
 
+              {/* Error message for failed orgs */}
+              {org.status === "failed" && org.errorMessage && (
+                <p className="text-xs text-destructive line-clamp-2">{org.errorMessage}</p>
+              )}
+
               {/* Destination override section */}
               <div>
                 <MirrorDestinationEditor
@@ -268,7 +265,7 @@ export function OrganizationList({
                   <div className="flex-1">
                     <div className="flex items-center gap-3 mb-1">
                       <a 
-                        href={`/repositories?organization=${encodeURIComponent(org.name || '')}`}
+                        href={`${withBase('/repositories')}?organization=${encodeURIComponent(org.name || '')}`}
                         className="text-xl font-semibold hover:underline cursor-pointer"
                       >
                         {org.name}
@@ -304,6 +301,13 @@ export function OrganizationList({
                 />
               </div>
 
+              {/* Error message for failed orgs */}
+              {org.status === "failed" && org.errorMessage && (
+                <div className="mb-4 p-3 rounded-md bg-destructive/10 border border-destructive/20">
+                  <p className="text-sm text-destructive">{org.errorMessage}</p>
+                </div>
+              )}
+
               {/* Repository statistics */}
               <div className="mb-4">
                 <div className="flex items-center gap-4 text-sm">
@@ -313,7 +317,7 @@ export function OrganizationList({
                       {org.repositoryCount === 1 ? "repository" : "repositories"}
                     </span>
                   </div>
-                  
+
                   {/* Repository breakdown - only show non-zero counts */}
                   {(() => {
                     const counts = [];
@@ -326,7 +330,7 @@ export function OrganizationList({
                     if (org.forkRepositoryCount && org.forkRepositoryCount > 0) {
                       counts.push(`${org.forkRepositoryCount} ${org.forkRepositoryCount === 1 ? 'fork' : 'forks'}`);
                     }
-                    
+
                     return counts.length > 0 ? (
                       <div className="flex items-center gap-3 text-xs text-muted-foreground">
                         {counts.map((count, index) => (
@@ -415,7 +419,7 @@ export function OrganizationList({
                     )}
                   </>
                 )}
-                
+
                 {/* Dropdown menu for additional actions */}
                 {org.status !== "mirroring" && (
                   <DropdownMenu>
@@ -426,7 +430,7 @@ export function OrganizationList({
                     </DropdownMenuTrigger>
                     <DropdownMenuContent align="end">
                       {org.status !== "ignored" && (
-                        <DropdownMenuItem 
+                        <DropdownMenuItem
                           onClick={() => org.id && onIgnore && onIgnore({ orgId: org.id, ignore: true })}
                         >
                           <Ban className="h-4 w-4 mr-2" />
@@ -449,7 +453,7 @@ export function OrganizationList({
                   </DropdownMenu>
                 )}
               </div>
-              
+
               <div className="flex items-center gap-2 justify-center">
                 {(() => {
                   const giteaUrl = getGiteaOrgUrl(org);

src/components/repositories/AddRepositoryDialog.tsx

@@ -18,10 +18,12 @@ interface AddRepositoryDialogProps {
     repo,
     owner,
     force,
+    destinationOrg,
   }: {
     repo: string;
     owner: string;
     force?: boolean;
+    destinationOrg?: string;
   }) => Promise<void>;
 }
 
@@ -32,6 +34,7 @@ export default function AddRepositoryDialog({
 }: AddRepositoryDialogProps) {
   const [repo, setRepo] = useState<string>("");
   const [owner, setOwner] = useState<string>("");
+  const [destinationOrg, setDestinationOrg] = useState<string>("");
   const [isLoading, setIsLoading] = useState<boolean>(false);
   const [error, setError] = useState<string>("");
 
@@ -40,6 +43,7 @@ export default function AddRepositoryDialog({
       setError("");
       setRepo("");
       setOwner("");
+      setDestinationOrg("");
     }
   }, [isDialogOpen]);
 
@@ -54,11 +58,16 @@ export default function AddRepositoryDialog({
     try {
       setIsLoading(true);
 
-      await onAddRepository({ repo, owner });
+      await onAddRepository({
+        repo,
+        owner,
+        destinationOrg: destinationOrg.trim() || undefined,
+      });
 
       setError("");
       setRepo("");
       setOwner("");
+      setDestinationOrg("");
       setIsDialogOpen(false);
     } catch (err: any) {
       setError(err?.message || "Failed to add repository.");
@@ -124,6 +133,27 @@ export default function AddRepositoryDialog({
               />
             </div>
 
+            <div>
+              <label
+                htmlFor="destinationOrg"
+                className="block text-sm font-medium mb-1.5"
+              >
+                Target Organization{" "}
+                <span className="text-muted-foreground font-normal">
+                  (optional)
+                </span>
+              </label>
+              <input
+                id="destinationOrg"
+                type="text"
+                value={destinationOrg}
+                onChange={(e) => setDestinationOrg(e.target.value)}
+                className="w-full rounded-md border border-input bg-background px-3 py-2 text-sm shadow-sm transition-colors placeholder:text-muted-foreground focus-visible:outline-none focus-visible:ring-1 focus-visible:ring-ring"
+                placeholder="Gitea org or user (uses default strategy if empty)"
+                autoComplete="off"
+              />
+            </div>
+
             {error && <p className="text-sm text-red-500 mt-1">{error}</p>}
           </div>
 

src/components/repositories/Repository.tsx

@@ -50,19 +50,30 @@ import AddRepositoryDialog from "./AddRepositoryDialog";
 import { useLiveRefresh } from "@/hooks/useLiveRefresh";
 import { useConfigStatus } from "@/hooks/useConfigStatus";
 import { useNavigation } from "@/components/layout/MainLayout";
+import { withBase } from "@/lib/base-path";
+
+const REPOSITORY_SORT_OPTIONS = [
+  { value: "imported-desc", label: "Recently Imported" },
+  { value: "imported-asc", label: "Oldest Imported" },
+  { value: "updated-desc", label: "Recently Updated" },
+  { value: "updated-asc", label: "Oldest Updated" },
+  { value: "name-asc", label: "Name (A-Z)" },
+  { value: "name-desc", label: "Name (Z-A)" },
+] as const;
 
 export default function Repository() {
   const [repositories, setRepositories] = useState<Repository[]>([]);
   const [isInitialLoading, setIsInitialLoading] = useState(true);
   const { user } = useAuth();
   const { registerRefreshCallback, isLiveEnabled } = useLiveRefresh();
-  const { isGitHubConfigured, isFullyConfigured } = useConfigStatus();
+  const { isGitHubConfigured, isFullyConfigured, autoMirrorStarred, githubOwner } = useConfigStatus();
   const { navigationKey } = useNavigation();
   const { filter, setFilter } = useFilterParams({
     searchTerm: "",
     status: "",
     organization: "",
     owner: "",
+    sort: "imported-desc",
   });
   const [isDialogOpen, setIsDialogOpen] = useState<boolean>(false);
   const [selectedRepoIds, setSelectedRepoIds] = useState<Set<string>>(new Set());
@@ -233,10 +244,12 @@ export default function Repository() {
       // Filter out repositories that are already mirroring, mirrored, or ignored
       const eligibleRepos = repositories.filter(
         (repo) =>
-          repo.status !== "mirroring" && 
-          repo.status !== "mirrored" && 
+          repo.status !== "mirroring" &&
+          repo.status !== "mirrored" &&
           repo.status !== "ignored" && // Skip ignored repositories
-          repo.id
+          repo.id &&
+          // Skip starred repos from other owners when autoMirrorStarred is disabled
+          !(repo.isStarred && !autoMirrorStarred && repo.owner !== githubOwner)
       );
 
       if (eligibleRepos.length === 0) {
@@ -292,7 +305,7 @@ export default function Repository() {
     
     const selectedRepos = repositories.filter(repo => repo.id && selectedRepoIds.has(repo.id));
     const eligibleRepos = selectedRepos.filter(
-      repo => repo.status === "imported" || repo.status === "failed"
+      repo => repo.status === "imported" || repo.status === "failed" || repo.status === "pending-approval"
     );
 
     if (eligibleRepos.length === 0) {
@@ -301,7 +314,7 @@ export default function Repository() {
     }
 
     const repoIds = eligibleRepos.map(repo => repo.id as string);
-    
+
     setLoadingRepoIds(prev => {
       const newSet = new Set(prev);
       repoIds.forEach(id => newSet.add(id));
@@ -694,14 +707,90 @@ export default function Repository() {
     }
   };
 
+  const handleApproveSyncAction = async ({ repoId }: { repoId: string }) => {
+    try {
+      if (!user || !user.id) return;
+      setLoadingRepoIds((prev) => new Set(prev).add(repoId));
+
+      const response = await apiRequest<{
+        success: boolean;
+        message?: string;
+        error?: string;
+        repositories: Repository[];
+      }>("/job/approve-sync", {
+        method: "POST",
+        data: { repositoryIds: [repoId], action: "approve" },
+      });
+
+      if (response.success) {
+        toast.success("Sync approved — backup + sync started");
+        setRepositories((prevRepos) =>
+          prevRepos.map((repo) => {
+            const updated = response.repositories.find((r) => r.id === repo.id);
+            return updated ? updated : repo;
+          }),
+        );
+      } else {
+        showErrorToast(response.error || "Error approving sync", toast);
+      }
+    } catch (error) {
+      showErrorToast(error, toast);
+    } finally {
+      setLoadingRepoIds((prev) => {
+        const newSet = new Set(prev);
+        newSet.delete(repoId);
+        return newSet;
+      });
+    }
+  };
+
+  const handleDismissSyncAction = async ({ repoId }: { repoId: string }) => {
+    try {
+      if (!user || !user.id) return;
+      setLoadingRepoIds((prev) => new Set(prev).add(repoId));
+
+      const response = await apiRequest<{
+        success: boolean;
+        message?: string;
+        error?: string;
+        repositories: Repository[];
+      }>("/job/approve-sync", {
+        method: "POST",
+        data: { repositoryIds: [repoId], action: "dismiss" },
+      });
+
+      if (response.success) {
+        toast.success("Force-push alert dismissed");
+        setRepositories((prevRepos) =>
+          prevRepos.map((repo) => {
+            const updated = response.repositories.find((r) => r.id === repo.id);
+            return updated ? updated : repo;
+          }),
+        );
+      } else {
+        showErrorToast(response.error || "Error dismissing alert", toast);
+      }
+    } catch (error) {
+      showErrorToast(error, toast);
+    } finally {
+      setLoadingRepoIds((prev) => {
+        const newSet = new Set(prev);
+        newSet.delete(repoId);
+        return newSet;
+      });
+    }
+  };
+
   const handleAddRepository = async ({
     repo,
     owner,
     force = false,
+    destinationOrg,
   }: {
     repo: string;
     owner: string;
     force?: boolean;
+    destinationOrg?: string;
   }) => {
     if (!user || !user.id) {
       return;
@@ -736,6 +825,7 @@ export default function Repository() {
         repo: trimmedRepo,
         owner: trimmedOwner,
         force,
+        ...(destinationOrg ? { destinationOrg } : {}),
       };
 
       const response = await apiRequest<AddRepositoriesApiResponse>(
@@ -860,7 +950,7 @@ export default function Repository() {
     const actions = [];
     
     // Check if any selected repos can be mirrored
-    if (selectedRepos.some(repo => repo.status === "imported" || repo.status === "failed")) {
+    if (selectedRepos.some(repo => repo.status === "imported" || repo.status === "failed" || repo.status === "pending-approval")) {
       actions.push('mirror');
     }
     
@@ -898,7 +988,7 @@ export default function Repository() {
     const selectedRepos = repositories.filter(repo => repo.id && selectedRepoIds.has(repo.id));
     
     return {
-      mirror: selectedRepos.filter(repo => repo.status === "imported" || repo.status === "failed").length,
+      mirror: selectedRepos.filter(repo => repo.status === "imported" || repo.status === "failed" || repo.status === "pending-approval").length,
       sync: selectedRepos.filter(repo => repo.status === "mirrored" || repo.status === "synced").length,
       rerunMetadata: selectedRepos.filter(repo => ["mirrored", "synced", "archived"].includes(repo.status)).length,
       retry: selectedRepos.filter(repo => repo.status === "failed").length,
@@ -920,6 +1010,7 @@ export default function Repository() {
       status: "",
       organization: "",
       owner: "",
+      sort: filter.sort || "imported-desc",
     });
   };
 
@@ -1060,6 +1151,33 @@ export default function Repository() {
                     </SelectContent>
                   </Select>
                 </div>
+
+                {/* Sort Filter */}
+                <div className="space-y-2">
+                  <label className="text-sm font-medium flex items-center gap-2">
+                    <span className="text-muted-foreground">Sort</span>
+                  </label>
+                  <Select
+                    value={filter.sort || "imported-desc"}
+                    onValueChange={(value) =>
+                      setFilter((prev) => ({
+                        ...prev,
+                        sort: value,
+                      }))
+                    }
+                  >
+                    <SelectTrigger className="w-full h-10">
+                      <SelectValue placeholder="Sort repositories" />
+                    </SelectTrigger>
+                    <SelectContent>
+                      {REPOSITORY_SORT_OPTIONS.map((option) => (
+                        <SelectItem key={option.value} value={option.value}>
+                          {option.label}
+                        </SelectItem>
+                      ))}
+                    </SelectContent>
+                  </Select>
+                </div>
               </div>
               
               <DrawerFooter className="gap-2 px-4 pt-2 pb-4 border-t">
@@ -1162,6 +1280,27 @@ export default function Repository() {
               </SelectContent>
             </Select>
 
+            <Select
+              value={filter.sort || "imported-desc"}
+              onValueChange={(value) =>
+                setFilter((prev) => ({
+                  ...prev,
+                  sort: value,
+                }))
+              }
+            >
+              <SelectTrigger className="w-[190px] h-10">
+                <SelectValue placeholder="Sort repositories" />
+              </SelectTrigger>
+              <SelectContent>
+                {REPOSITORY_SORT_OPTIONS.map((option) => (
+                  <SelectItem key={option.value} value={option.value}>
+                    {option.label}
+                  </SelectItem>
+                ))}
+              </SelectContent>
+            </Select>
+
             <Button
               variant="outline"
               size="icon"
@@ -1380,7 +1519,7 @@ export default function Repository() {
           <Button
             variant="default"
             onClick={() => {
-              window.history.pushState({}, '', '/config');
+              window.history.pushState({}, '', withBase('/config'));
               // We need to trigger a page change event for the navigation system
               window.dispatchEvent(new PopStateEvent('popstate'));
             }}
@@ -1406,6 +1545,8 @@ export default function Repository() {
             await fetchRepositories(false);
           }}
           onDelete={handleRequestDeleteRepository}
+          onApproveSync={handleApproveSyncAction}
+          onDismissSync={handleDismissSyncAction}
         />
       )}
 

src/components/repositories/RepositoryTable.tsx

@@ -1,11 +1,20 @@
 import { useMemo, useRef } from "react";
-import Fuse from "fuse.js";
+import {
+  getCoreRowModel,
+  getFilteredRowModel,
+  getSortedRowModel,
+  useReactTable,
+  type ColumnDef,
+  type ColumnFiltersState,
+  type SortingState,
+} from "@tanstack/react-table";
 import { useVirtualizer } from "@tanstack/react-virtual";
-import { FlipHorizontal, GitFork, RefreshCw, RotateCcw, Star, Lock, Ban, Check, ChevronDown, Trash2 } from "lucide-react";
+import { FlipHorizontal, GitFork, RefreshCw, RotateCcw, Star, Lock, Ban, Check, ChevronDown, Trash2, X } from "lucide-react";
 import { SiGithub, SiGitea } from "react-icons/si";
 import type { Repository } from "@/lib/db/schema";
 import { Button } from "@/components/ui/button";
-import { formatDate, formatLastSyncTime, getStatusColor } from "@/lib/utils";
+import { formatLastSyncTime } from "@/lib/utils";
+import { buildGiteaWebUrl } from "@/lib/gitea-url";
 import type { FilterParams } from "@/types/filter";
 import { Skeleton } from "@/components/ui/skeleton";
 import { useGiteaConfig } from "@/hooks/useGiteaConfig";
@@ -19,6 +28,7 @@ import {
 import { InlineDestinationEditor } from "./InlineDestinationEditor";
 import { Card, CardContent } from "@/components/ui/card";
 import { Badge } from "@/components/ui/badge";
+import { withBase } from "@/lib/base-path";
 import {
   DropdownMenu,
   DropdownMenuContent,
@@ -42,6 +52,32 @@ interface RepositoryTableProps {
   onSelectionChange: (selectedIds: Set<string>) => void;
   onRefresh?: () => Promise<void>;
   onDelete?: (repoId: string) => void;
+  onApproveSync?: ({ repoId }: { repoId: string }) => Promise<void>;
+  onDismissSync?: ({ repoId }: { repoId: string }) => Promise<void>;
+}
+
+function getTimestamp(value: Date | string | null | undefined): number {
+  if (!value) return 0;
+  const timestamp = new Date(value).getTime();
+  return Number.isNaN(timestamp) ? 0 : timestamp;
+}
+
+function getTableSorting(sortOrder: string | undefined): SortingState {
+  switch (sortOrder ?? "imported-desc") {
+    case "imported-asc":
+      return [{ id: "importedAt", desc: false }];
+    case "updated-desc":
+      return [{ id: "updatedAt", desc: true }];
+    case "updated-asc":
+      return [{ id: "updatedAt", desc: false }];
+    case "name-asc":
+      return [{ id: "fullName", desc: false }];
+    case "name-desc":
+      return [{ id: "fullName", desc: true }];
+    case "imported-desc":
+    default:
+      return [{ id: "importedAt", desc: true }];
+  }
 }
 
 export default function RepositoryTable({
@@ -59,13 +95,15 @@ export default function RepositoryTable({
   onSelectionChange,
   onRefresh,
   onDelete,
+  onApproveSync,
+  onDismissSync,
 }: RepositoryTableProps) {
   const tableParentRef = useRef<HTMLDivElement>(null);
   const { giteaConfig } = useGiteaConfig();
 
   const handleUpdateDestination = async (repoId: string, newDestination: string | null) => {
     // Call API to update repository destination
-    const response = await fetch(`/api/repositories/${repoId}`, {
+    const response = await fetch(`${withBase("/api/repositories")}/${repoId}`, {
       method: "PATCH",
       headers: {
         "Content-Type": "application/json",
@@ -88,10 +126,6 @@ export default function RepositoryTable({
 
   // Helper function to construct Gitea repository URL
   const getGiteaRepoUrl = (repository: Repository): string | null => {
-    if (!giteaConfig?.url) {
-      return null;
-    }
-
     // Only provide Gitea links for repositories that have been or are being mirrored
     const validStatuses = ['mirroring', 'mirrored', 'syncing', 'synced', 'archived'];
     if (!validStatuses.includes(repository.status)) {
@@ -108,48 +142,92 @@ export default function RepositoryTable({
       repoPath = `${owner}/${repository.name}`;
     }
 
-    // Ensure the base URL doesn't have a trailing slash
-    const baseUrl = giteaConfig.url.endsWith('/')
-      ? giteaConfig.url.slice(0, -1)
-      : giteaConfig.url;
-
-    return `${baseUrl}/${repoPath}`;
+    return buildGiteaWebUrl(giteaConfig, repoPath);
   };
 
-  const hasAnyFilter = Object.values(filter).some(
-    (val) => val?.toString().trim() !== ""
-  );
+  const hasAnyFilter = [
+    filter.searchTerm,
+    filter.status,
+    filter.owner,
+    filter.organization,
+  ].some((val) => val?.toString().trim() !== "");
 
-  const filteredRepositories = useMemo(() => {
-    let result = repositories;
+  const columnFilters = useMemo<ColumnFiltersState>(() => {
+    const next: ColumnFiltersState = [];
 
     if (filter.status) {
-      result = result.filter((repo) => repo.status === filter.status);
+      next.push({ id: "status", value: filter.status });
     }
 
     if (filter.owner) {
-      result = result.filter((repo) => repo.owner === filter.owner);
+      next.push({ id: "owner", value: filter.owner });
     }
 
     if (filter.organization) {
-      result = result.filter(
-        (repo) => repo.organization === filter.organization
-      );
+      next.push({ id: "organization", value: filter.organization });
     }
 
-    if (filter.searchTerm) {
-      const fuse = new Fuse(result, {
-        keys: ["name", "fullName", "owner", "organization"],
-        threshold: 0.3,
-      });
-      result = fuse.search(filter.searchTerm).map((res) => res.item);
-    }
+    return next;
+  }, [filter.status, filter.owner, filter.organization]);
 
-    return result;
-  }, [repositories, filter]);
+  const sorting = useMemo(() => getTableSorting(filter.sort), [filter.sort]);
+
+  const columns = useMemo<ColumnDef<Repository>[]>(
+    () => [
+      {
+        id: "fullName",
+        accessorFn: (row) => row.fullName,
+      },
+      {
+        id: "owner",
+        accessorFn: (row) => row.owner,
+        filterFn: "equalsString",
+      },
+      {
+        id: "organization",
+        accessorFn: (row) => row.organization ?? "",
+        filterFn: "equalsString",
+      },
+      {
+        id: "status",
+        accessorFn: (row) => row.status,
+        filterFn: "equalsString",
+      },
+      {
+        id: "importedAt",
+        accessorFn: (row) => getTimestamp(row.importedAt),
+        enableGlobalFilter: false,
+        enableColumnFilter: false,
+      },
+      {
+        id: "updatedAt",
+        accessorFn: (row) => getTimestamp(row.updatedAt),
+        enableGlobalFilter: false,
+        enableColumnFilter: false,
+      },
+    ],
+    []
+  );
+
+  const table = useReactTable({
+    data: repositories,
+    columns,
+    state: {
+      globalFilter: filter.searchTerm ?? "",
+      columnFilters,
+      sorting,
+    },
+    getCoreRowModel: getCoreRowModel(),
+    getFilteredRowModel: getFilteredRowModel(),
+    getSortedRowModel: getSortedRowModel(),
+  });
+
+  const visibleRepositories = table
+    .getRowModel()
+    .rows.map((row) => row.original);
 
   const rowVirtualizer = useVirtualizer({
-    count: filteredRepositories.length,
+    count: visibleRepositories.length,
     getScrollElement: () => tableParentRef.current,
     estimateSize: () => 65,
     overscan: 5,
@@ -158,7 +236,11 @@ export default function RepositoryTable({
   // Selection handlers
   const handleSelectAll = (checked: boolean) => {
     if (checked) {
-      const allIds = new Set(filteredRepositories.map(repo => repo.id).filter((id): id is string => !!id));
+      const allIds = new Set(
+        visibleRepositories
+          .map((repo) => repo.id)
+          .filter((id): id is string => !!id)
+      );
       onSelectionChange(allIds);
     } else {
       onSelectionChange(new Set());
@@ -175,8 +257,9 @@ export default function RepositoryTable({
     onSelectionChange(newSelection);
   };
 
-  const isAllSelected = filteredRepositories.length > 0 && 
-    filteredRepositories.every(repo => repo.id && selectedRepoIds.has(repo.id));
+  const isAllSelected =
+    visibleRepositories.length > 0 &&
+    visibleRepositories.every((repo) => repo.id && selectedRepoIds.has(repo.id));
   const isPartiallySelected = selectedRepoIds.size > 0 && !isAllSelected;
 
   // Mobile card layout for repository
@@ -231,7 +314,7 @@ export default function RepositoryTable({
 
               {/* Status & Last Mirrored */}
               <div className="flex items-center justify-between">
-                <Badge 
+                <Badge
                   className={`capitalize
                     ${repo.status === 'imported' ? 'bg-yellow-500/10 text-yellow-600 hover:bg-yellow-500/20 dark:text-yellow-400' :
                       repo.status === 'mirrored' || repo.status === 'synced' ? 'bg-green-500/10 text-green-600 hover:bg-green-500/20 dark:text-green-400' :
@@ -239,13 +322,14 @@ export default function RepositoryTable({
                       repo.status === 'failed' ? 'bg-red-500/10 text-red-600 hover:bg-red-500/20 dark:text-red-400' :
                       repo.status === 'ignored' ? 'bg-gray-500/10 text-gray-600 hover:bg-gray-500/20 dark:text-gray-400' :
                       repo.status === 'skipped' ? 'bg-orange-500/10 text-orange-600 hover:bg-orange-500/20 dark:text-orange-400' :
+                      repo.status === 'pending-approval' ? 'bg-amber-500/10 text-amber-600 hover:bg-amber-500/20 dark:text-amber-400' :
                       'bg-muted hover:bg-muted/80'}`}
                   variant="secondary"
                 >
                   {repo.status}
                 </Badge>
                 <span className="text-xs text-muted-foreground">
-                  {formatLastSyncTime(repo.lastMirrored)}
+                  {formatLastSyncTime(repo.lastMirrored ?? null)}
                 </span>
               </div>
             </div>
@@ -316,7 +400,40 @@ export default function RepositoryTable({
                   )}
                 </Button>
               )}
-              
+              {repo.status === "pending-approval" && (
+                <div className="flex gap-2 w-full">
+                  <Button
+                    size="default"
+                    variant="default"
+                    onClick={() => repo.id && onApproveSync?.({ repoId: repo.id })}
+                    disabled={isLoading}
+                    className="flex-1 h-10"
+                  >
+                    {isLoading ? (
+                      <>
+                        <Check className="h-4 w-4 mr-2 animate-spin" />
+                        Approving...
+                      </>
+                    ) : (
+                      <>
+                        <Check className="h-4 w-4 mr-2" />
+                        Approve Sync
+                      </>
+                    )}
+                  </Button>
+                  <Button
+                    size="default"
+                    variant="outline"
+                    onClick={() => repo.id && onDismissSync?.({ repoId: repo.id })}
+                    disabled={isLoading}
+                    className="flex-1 h-10"
+                  >
+                    <X className="h-4 w-4 mr-2" />
+                    Dismiss
+                  </Button>
+                </div>
+              )}
+
               {/* Ignore/Include button */}
               {repo.status === "ignored" ? (
                 <Button
@@ -341,7 +458,7 @@ export default function RepositoryTable({
                   Ignore Repository
                 </Button>
               )}
-              
+
               {/* External links */}
               <div className="flex gap-2">
                 <Button variant="outline" size="default" className="flex-1 h-10 min-w-0" asChild>
@@ -472,7 +589,7 @@ export default function RepositoryTable({
       {hasAnyFilter && (
         <div className="mb-4 flex items-center gap-2">
           <span className="text-sm text-muted-foreground">
-            Showing {filteredRepositories.length} of {repositories.length} repositories
+            Showing {visibleRepositories.length} of {repositories.length} repositories
           </span>
           <Button
             variant="ghost"
@@ -483,6 +600,7 @@ export default function RepositoryTable({
                 status: "",
                 organization: "",
                 owner: "",
+                sort: filter.sort || "imported-desc",
               })
             }
           >
@@ -491,7 +609,7 @@ export default function RepositoryTable({
         </div>
       )}
 
-      {filteredRepositories.length === 0 ? (
+      {visibleRepositories.length === 0 ? (
         <div className="text-center py-8">
           <p className="text-muted-foreground">
             {hasAnyFilter
@@ -512,12 +630,12 @@ export default function RepositoryTable({
                 className="h-5 w-5"
               />
               <span className="text-sm font-medium">
-                Select All ({filteredRepositories.length})
+                Select All ({visibleRepositories.length})
               </span>
             </div>
 
             {/* Repository cards */}
-            {filteredRepositories.map((repo) => (
+            {visibleRepositories.map((repo) => (
               <RepositoryCard key={repo.id} repo={repo} />
             ))}
           </div>
@@ -563,13 +681,14 @@ export default function RepositoryTable({
                   position: "relative",
                 }}
               >
-                {rowVirtualizer.getVirtualItems().map((virtualRow, index) => {
-                  const repo = filteredRepositories[virtualRow.index];
+                {rowVirtualizer.getVirtualItems().map((virtualRow) => {
+                  const repo = visibleRepositories[virtualRow.index];
+                  if (!repo) return null;
                   const isLoading = loadingRepoIds.has(repo.id ?? "");
 
                   return (
                     <div
-                      key={index}
+                      key={virtualRow.key}
                       ref={rowVirtualizer.measureElement}
                       style={{
                         position: "absolute",
@@ -632,7 +751,7 @@ export default function RepositoryTable({
                       {/* Last Mirrored */}
                       <div className="h-full p-3 flex items-center flex-[1]">
                         <p className="text-sm">
-                          {formatLastSyncTime(repo.lastMirrored)}
+                          {formatLastSyncTime(repo.lastMirrored ?? null)}
                         </p>
                       </div>
 
@@ -642,7 +761,7 @@ export default function RepositoryTable({
                           <TooltipProvider>
                             <Tooltip>
                               <TooltipTrigger asChild>
-                                <Badge 
+                                <Badge
                                   variant="destructive"
                                   className="cursor-help capitalize"
                                 >
@@ -655,7 +774,7 @@ export default function RepositoryTable({
                             </Tooltip>
                           </TooltipProvider>
                         ) : (
-                          <Badge 
+                          <Badge
                             className={`capitalize
                               ${repo.status === 'imported' ? 'bg-yellow-500/10 text-yellow-600 hover:bg-yellow-500/20 dark:text-yellow-400' :
                                 repo.status === 'mirrored' || repo.status === 'synced' ? 'bg-green-500/10 text-green-600 hover:bg-green-500/20 dark:text-green-400' :
@@ -663,6 +782,7 @@ export default function RepositoryTable({
                                 repo.status === 'failed' ? 'bg-red-500/10 text-red-600 hover:bg-red-500/20 dark:text-red-400' :
                                 repo.status === 'ignored' ? 'bg-gray-500/10 text-gray-600 hover:bg-gray-500/20 dark:text-gray-400' :
                                 repo.status === 'skipped' ? 'bg-orange-500/10 text-orange-600 hover:bg-orange-500/20 dark:text-orange-400' :
+                                repo.status === 'pending-approval' ? 'bg-amber-500/10 text-amber-600 hover:bg-amber-500/20 dark:text-amber-400' :
                                 'bg-muted hover:bg-muted/80'}`}
                             variant="secondary"
                           >
@@ -680,6 +800,8 @@ export default function RepositoryTable({
                           onRetry={() => onRetry({ repoId: repo.id ?? "" })}
                           onSkip={(skip) => onSkip({ repoId: repo.id ?? "", skip })}
                           onDelete={onDelete && repo.id ? () => onDelete(repo.id as string) : undefined}
+                          onApproveSync={onApproveSync ? () => onApproveSync({ repoId: repo.id ?? "" }) : undefined}
+                          onDismissSync={onDismissSync ? () => onDismissSync({ repoId: repo.id ?? "" }) : undefined}
                         />
                       </div>
                       {/* Links */}
@@ -743,7 +865,7 @@ export default function RepositoryTable({
                 <div className={`h-1.5 w-1.5 rounded-full ${isLiveActive ? 'bg-emerald-500' : 'bg-primary'}`} />
                 <span className="text-sm font-medium text-foreground">
                   {hasAnyFilter
-                    ? `Showing ${filteredRepositories.length} of ${repositories.length} repositories`
+                    ? `Showing ${visibleRepositories.length} of ${repositories.length} repositories`
                     : `${repositories.length} ${repositories.length === 1 ? 'repository' : 'repositories'} total`}
                 </span>
               </div>
@@ -791,6 +913,8 @@ function RepoActionButton({
   onRetry,
   onSkip,
   onDelete,
+  onApproveSync,
+  onDismissSync,
 }: {
   repo: { id: string; status: string };
   isLoading: boolean;
@@ -799,7 +923,36 @@ function RepoActionButton({
   onRetry: () => void;
   onSkip: (skip: boolean) => void;
   onDelete?: () => void;
+  onApproveSync?: () => void;
+  onDismissSync?: () => void;
 }) {
+  // For pending-approval repos, show approve/dismiss actions
+  if (repo.status === "pending-approval") {
+    return (
+      <div className="flex gap-1">
+        <Button
+          variant="default"
+          size="sm"
+          disabled={isLoading}
+          onClick={onApproveSync}
+          className="min-w-[70px]"
+        >
+          <Check className="h-4 w-4 mr-1" />
+          Approve
+        </Button>
+        <Button
+          variant="outline"
+          size="sm"
+          disabled={isLoading}
+          onClick={onDismissSync}
+        >
+          <X className="h-4 w-4 mr-1" />
+          Dismiss
+        </Button>
+      </div>
+    );
+  }
+
   // For ignored repos, show an "Include" action
   if (repo.status === "ignored") {
     return (

src/components/theme/ThemeScript.astro

@@ -1,7 +1,26 @@
 ---
+import { BASE_PATH_WINDOW_KEY } from '@/lib/base-path';
+
+const normalizeBasePath = (value) => {
+  if (!value || !value.trim()) {
+    return '/';
+  }
+
+  let normalized = value.trim();
+  if (!normalized.startsWith('/')) {
+    normalized = `/${normalized}`;
+  }
+
+  normalized = normalized.replace(/\/+$/, '');
+  return normalized || '/';
+};
+
+const runtimeBasePath = normalizeBasePath(process.env.BASE_URL);
 ---
 
-<script is:inline>
+<script is:inline define:vars={{ BASE_PATH_WINDOW_KEY, runtimeBasePath }}>
+  window[BASE_PATH_WINDOW_KEY] = runtimeBasePath;
+
   const getThemePreference = () => {
     if (typeof localStorage !== 'undefined' && localStorage.getItem('theme')) {
       return localStorage.getItem('theme');

src/content/config.ts

@@ -1,4 +0,0 @@
-import { defineCollection, z } from 'astro:content';
-
-// Export empty collections since docs have been moved
-export const collections = {};

src/hooks/useAuth-legacy.ts

@@ -8,6 +8,7 @@ import {
 } from "react";
 import { authApi } from "@/lib/api";
 import type { ExtendedUser } from "@/types/user";
+import { withBase } from "@/lib/base-path";
 
 interface AuthContextType {
   user: ExtendedUser | null;
@@ -61,9 +62,9 @@ export function AuthProvider({ children }: { children: React.ReactNode }) {
 
         // Redirect user based on error
         if (err?.message === "No users found") {
-          window.location.href = "/signup";
+          window.location.href = withBase("/signup");
         } else {
-          window.location.href = "/login";
+          window.location.href = withBase("/login");
         }
         console.error("Auth check failed", err);
       } finally {
@@ -111,7 +112,7 @@ export function AuthProvider({ children }: { children: React.ReactNode }) {
     try {
       await authApi.logout();
       setUser(null);
-      window.location.href = "/login";
+      window.location.href = withBase("/login");
     } catch (err) {
       console.error("Logout error:", err);
     } finally {

src/hooks/useAuth.ts

@@ -8,6 +8,7 @@ import {
 } from "react";
 import { authClient, useSession as useBetterAuthSession } from "@/lib/auth-client";
 import type { Session, AuthUser } from "@/lib/auth-client";
+import { withBase } from "@/lib/base-path";
 
 interface AuthContextType {
   user: AuthUser | null;
@@ -46,7 +47,7 @@ export function AuthProvider({ children }: { children: React.ReactNode }) {
       const result = await authClient.signIn.email({
         email,
         password,
-        callbackURL: "/",
+        callbackURL: withBase("/"),
       });
       
       if (result.error) {
@@ -73,7 +74,7 @@ export function AuthProvider({ children }: { children: React.ReactNode }) {
         email,
         password,
         name: username, // Better Auth uses 'name' field for display name
-        callbackURL: "/",
+        callbackURL: withBase("/"),
       });
 
       if (result.error) {
@@ -94,7 +95,7 @@ export function AuthProvider({ children }: { children: React.ReactNode }) {
       await authClient.signOut({
         fetchOptions: {
           onSuccess: () => {
-            window.location.href = "/login";
+            window.location.href = withBase("/login");
           },
         },
       });
@@ -140,4 +141,4 @@ export function useAuth() {
 }
 
 // Export the Better Auth session hook for direct use when needed
-export { useBetterAuthSession };
+export { useBetterAuthSession };

src/hooks/useConfigStatus.ts

@@ -9,6 +9,8 @@ interface ConfigStatus {
   isFullyConfigured: boolean;
   isLoading: boolean;
   error: string | null;
+  autoMirrorStarred: boolean;
+  githubOwner: string;
 }
 
 // Cache to prevent duplicate API calls across components
@@ -33,6 +35,8 @@ export function useConfigStatus(): ConfigStatus {
     isFullyConfigured: false,
     isLoading: true,
     error: null,
+    autoMirrorStarred: false,
+    githubOwner: '',
   });
 
   // Track if this hook has already checked config to prevent multiple calls
@@ -46,6 +50,8 @@ export function useConfigStatus(): ConfigStatus {
         isFullyConfigured: false,
         isLoading: false,
         error: 'No user found',
+        autoMirrorStarred: false,
+        githubOwner: '',
       });
       return;
     }
@@ -59,14 +65,16 @@ export function useConfigStatus(): ConfigStatus {
     if (isCacheValid && hasCheckedRef.current) {
       const configResponse = configCache.data!;
 
-      const isGitHubConfigured = !!(
-        configResponse?.githubConfig?.username &&
-        configResponse?.githubConfig?.token
-      );
+      // Only token/url are actually required at runtime: the GitHub token is
+      // self-authenticating for listForAuthenticatedUser, and a Gitea username
+      // isn't needed under single-org / flat mirror strategies. Users who
+      // configure via env vars without GITHUB_USERNAME / GITEA_USERNAME set
+      // (or who otherwise left those blank) were being locked out of the
+      // dashboard even though mirroring worked fine (see issue #271).
+      const isGitHubConfigured = !!configResponse?.githubConfig?.token;
 
       const isGiteaConfigured = !!(
         configResponse?.giteaConfig?.url &&
-        configResponse?.giteaConfig?.username &&
         configResponse?.giteaConfig?.token
       );
 
@@ -78,6 +86,8 @@ export function useConfigStatus(): ConfigStatus {
         isFullyConfigured,
         isLoading: false,
         error: null,
+        autoMirrorStarred: configResponse?.advancedOptions?.autoMirrorStarred ?? false,
+        githubOwner: configResponse?.githubConfig?.username ?? '',
       });
       return;
     }
@@ -100,14 +110,16 @@ export function useConfigStatus(): ConfigStatus {
         userId: user.id
       };
 
-      const isGitHubConfigured = !!(
-        configResponse?.githubConfig?.username &&
-        configResponse?.githubConfig?.token
-      );
+      // Only token/url are actually required at runtime: the GitHub token is
+      // self-authenticating for listForAuthenticatedUser, and a Gitea username
+      // isn't needed under single-org / flat mirror strategies. Users who
+      // configure via env vars without GITHUB_USERNAME / GITEA_USERNAME set
+      // (or who otherwise left those blank) were being locked out of the
+      // dashboard even though mirroring worked fine (see issue #271).
+      const isGitHubConfigured = !!configResponse?.githubConfig?.token;
 
       const isGiteaConfigured = !!(
         configResponse?.giteaConfig?.url &&
-        configResponse?.giteaConfig?.username &&
         configResponse?.giteaConfig?.token
       );
 
@@ -119,6 +131,8 @@ export function useConfigStatus(): ConfigStatus {
         isFullyConfigured,
         isLoading: false,
         error: null,
+        autoMirrorStarred: configResponse?.advancedOptions?.autoMirrorStarred ?? false,
+        githubOwner: configResponse?.githubConfig?.username ?? '',
       });
 
       hasCheckedRef.current = true;
@@ -129,6 +143,8 @@ export function useConfigStatus(): ConfigStatus {
         isFullyConfigured: false,
         isLoading: false,
         error: error instanceof Error ? error.message : 'Failed to check configuration',
+        autoMirrorStarred: false,
+        githubOwner: '',
       });
       hasCheckedRef.current = true;
     }

src/hooks/useFilterParams.ts

@@ -7,6 +7,7 @@ const FILTER_KEYS: (keyof FilterParams)[] = [
   "membershipRole",
   "owner",
   "organization",
+  "sort",
   "type",
   "name",
 ];

src/hooks/useSEE.ts

@@ -1,5 +1,6 @@
 import { useEffect, useState, useRef, useCallback } from "react";
 import type { MirrorJob } from "@/lib/db/schema";
+import { withBase } from "@/lib/base-path";
 
 interface UseSSEOptions {
   userId?: string;
@@ -41,7 +42,7 @@ export const useSSE = ({
     }
 
     // Create new EventSource connection
-    const eventSource = new EventSource(`/api/sse?userId=${userId}`);
+    const eventSource = new EventSource(`${withBase("/api/sse")}?userId=${userId}`);
     eventSourceRef.current = eventSource;
 
     const handleMessage = (event: MessageEvent) => {

src/hooks/useSyncRepo.ts

@@ -1,5 +1,6 @@
 import { useEffect, useRef } from "react";
 import { useAuth } from "./useAuth";
+import { withBase } from "@/lib/base-path";
 
 interface UseRepoSyncOptions {
   userId?: string;
@@ -51,7 +52,7 @@ export function useRepoSync({
 
     const sync = async () => {
       try {
-        const response = await fetch("/api/job/schedule-sync-repo", {
+        const response = await fetch(withBase("/api/job/schedule-sync-repo"), {
           method: "POST",
           headers: {
             "Content-Type": "application/json",

src/layouts/main.astro

@@ -2,6 +2,7 @@
 import '../styles/global.css';
 import '../styles/docs.css';
 import ThemeScript from '@/components/theme/ThemeScript.astro';
+import { withBase } from '@/lib/base-path';
 
 // Accept title as a prop with a default value
 const { title = 'Gitea Mirror' } = Astro.props;
@@ -11,7 +12,7 @@ const { title = 'Gitea Mirror' } = Astro.props;
 	<head>
 		<meta charset="utf-8" />
 		<meta name="viewport" content="width=device-width" />
-		<link rel="icon" type="image/svg+xml" href="/favicon.svg" />
+		<link rel="icon" type="image/svg+xml" href={withBase('/favicon.svg')} />
 		<title>{title}</title>
 		<ThemeScript />
 	</head>

src/lib/api.ts

@@ -1,5 +1,7 @@
+import { withBase } from "@/lib/base-path";
+
 // Base API URL
-const API_BASE = "/api";
+const API_BASE = withBase("/api");
 
 // Helper function for API requests
 async function apiRequest<T>(
@@ -78,48 +80,44 @@ export const githubApi = {
       method: "POST",
       body: JSON.stringify({ token }),
     }),
+  getStarredLists: () =>
+    apiRequest<{ success: boolean; lists: string[] }>("/github/starred-lists", {
+      method: "GET",
+    }),
 };
 
 // Gitea API
+export interface GiteaServerInfo {
+  type: "forgejo" | "gitea";
+  version: string;
+  raw: string;
+  hasMirrorCredBug: boolean;
+}
+
 export const giteaApi = {
   testConnection: (url: string, token: string) =>
-    apiRequest<{ success: boolean }>("/gitea/test-connection", {
-      method: "POST",
-      body: JSON.stringify({ url, token }),
-    }),
+    apiRequest<{ success: boolean; serverInfo?: GiteaServerInfo; message?: string }>(
+      "/gitea/test-connection",
+      {
+        method: "POST",
+        body: JSON.stringify({ url, token }),
+      }
+    ),
 };
 
 // Health API
 export interface HealthResponse {
-  status: "ok" | "error";
+  status: "ok" | "error" | "degraded";
   timestamp: string;
   version: string;
   latestVersion: string;
   updateAvailable: boolean;
   database: {
     connected: boolean;
-    message: string;
   };
-  system: {
-    uptime: {
-      startTime: string;
-      uptimeMs: number;
-      formatted: string;
-    };
-    memory: {
-      rss: string;
-      heapTotal: string;
-      heapUsed: string;
-      external: string;
-      systemTotal: string;
-      systemFree: string;
-    };
-    os: {
-      platform: string;
-      version: string;
-      arch: string;
-    };
-    env: string;
+  recovery?: {
+    status: string;
+    jobsNeedingRecovery: number;
   };
   error?: string;
 }

src/lib/auth-client.ts

@@ -3,6 +3,12 @@ import { createAuthClient } from "better-auth/react";
 import { oidcClient } from "better-auth/client/plugins";
 import { ssoClient } from "@better-auth/sso/client";
 import type { Session as BetterAuthSession, User as BetterAuthUser } from "better-auth";
+import { withBase } from "@/lib/base-path";
+
+function normalizeAuthBaseUrl(url: string): string {
+  const validatedUrl = new URL(url.trim());
+  return validatedUrl.origin;
+}
 
 export const authClient = createAuthClient({
   // Use PUBLIC_BETTER_AUTH_URL if set (for multi-origin access), otherwise use current origin
@@ -18,9 +24,8 @@ export const authClient = createAuthClient({
     // Validate and clean the URL if provided
     if (url && typeof url === 'string' && url.trim() !== '') {
       try {
-        // Validate URL format and remove trailing slash
-        const validatedUrl = new URL(url.trim());
-        return validatedUrl.origin; // Use origin to ensure clean URL without path
+        // Validate URL format and preserve optional base path
+        return normalizeAuthBaseUrl(url);
       } catch (e) {
         console.warn(`Invalid PUBLIC_BETTER_AUTH_URL: ${url}, falling back to default`);
       }
@@ -34,7 +39,7 @@ export const authClient = createAuthClient({
     // Default for SSR - always return a valid URL
     return 'http://localhost:4321';
   })(),
-  basePath: '/api/auth', // Explicitly set the base path
+  basePath: withBase('/api/auth'), // Explicitly set the base path
   plugins: [
     oidcClient(),
     ssoClient(),

src/lib/auth-origins.test.ts

@@ -0,0 +1,119 @@
+import { describe, test, expect, beforeEach, afterEach } from "bun:test";
+import { resolveTrustedOrigins } from "./auth";
+
+// Helper to create a mock Request with specific headers
+function mockRequest(headers: Record<string, string>): Request {
+  return new Request("http://localhost:4321/api/auth/sign-in", {
+    headers: new Headers(headers),
+  });
+}
+
+describe("resolveTrustedOrigins", () => {
+  const savedEnv: Record<string, string | undefined> = {};
+
+  beforeEach(() => {
+    // Save and clear relevant env vars
+    for (const key of ["BETTER_AUTH_URL", "BETTER_AUTH_TRUSTED_ORIGINS"]) {
+      savedEnv[key] = process.env[key];
+      delete process.env[key];
+    }
+  });
+
+  afterEach(() => {
+    // Restore env vars
+    for (const [key, val] of Object.entries(savedEnv)) {
+      if (val === undefined) delete process.env[key];
+      else process.env[key] = val;
+    }
+  });
+
+  test("includes localhost defaults when called without request", async () => {
+    const origins = await resolveTrustedOrigins();
+    expect(origins).toContain("http://localhost:4321");
+    expect(origins).toContain("http://localhost:8080");
+  });
+
+  test("includes BETTER_AUTH_URL from env", async () => {
+    process.env.BETTER_AUTH_URL = "https://gitea-mirror.example.com";
+    const origins = await resolveTrustedOrigins();
+    expect(origins).toContain("https://gitea-mirror.example.com");
+  });
+
+  test("includes BETTER_AUTH_TRUSTED_ORIGINS (comma-separated)", async () => {
+    process.env.BETTER_AUTH_TRUSTED_ORIGINS = "https://a.example.com, https://b.example.com";
+    const origins = await resolveTrustedOrigins();
+    expect(origins).toContain("https://a.example.com");
+    expect(origins).toContain("https://b.example.com");
+  });
+
+  test("skips invalid URLs in env vars", async () => {
+    process.env.BETTER_AUTH_URL = "not-a-url";
+    process.env.BETTER_AUTH_TRUSTED_ORIGINS = "also-invalid, https://valid.example.com";
+    const origins = await resolveTrustedOrigins();
+    expect(origins).not.toContain("not-a-url");
+    expect(origins).not.toContain("also-invalid");
+    expect(origins).toContain("https://valid.example.com");
+  });
+
+  test("auto-detects origin from x-forwarded-host + x-forwarded-proto", async () => {
+    const req = mockRequest({
+      "x-forwarded-host": "gitea-mirror.mydomain.tld",
+      "x-forwarded-proto": "https",
+    });
+    const origins = await resolveTrustedOrigins(req);
+    expect(origins).toContain("https://gitea-mirror.mydomain.tld");
+  });
+
+  test("falls back to host header when x-forwarded-host is absent", async () => {
+    const req = mockRequest({
+      host: "myserver.local:4321",
+    });
+    const origins = await resolveTrustedOrigins(req);
+    expect(origins).toContain("http://myserver.local:4321");
+  });
+
+  test("handles multi-value x-forwarded-host (chained proxies)", async () => {
+    const req = mockRequest({
+      "x-forwarded-host": "external.example.com, internal.proxy.local",
+      "x-forwarded-proto": "https",
+    });
+    const origins = await resolveTrustedOrigins(req);
+    expect(origins).toContain("https://external.example.com");
+    expect(origins).not.toContain("https://internal.proxy.local");
+  });
+
+  test("handles multi-value x-forwarded-proto (chained proxies)", async () => {
+    const req = mockRequest({
+      "x-forwarded-host": "gitea.example.com",
+      "x-forwarded-proto": "https, http",
+    });
+    const origins = await resolveTrustedOrigins(req);
+    expect(origins).toContain("https://gitea.example.com");
+    // Should NOT create an origin with "https, http" as proto
+    expect(origins).not.toContain("https, http://gitea.example.com");
+  });
+
+  test("rejects invalid x-forwarded-proto values", async () => {
+    const req = mockRequest({
+      "x-forwarded-host": "gitea.example.com",
+      "x-forwarded-proto": "ftp",
+    });
+    const origins = await resolveTrustedOrigins(req);
+    expect(origins).not.toContain("ftp://gitea.example.com");
+  });
+
+  test("deduplicates origins", async () => {
+    process.env.BETTER_AUTH_URL = "http://localhost:4321";
+    const origins = await resolveTrustedOrigins();
+    const count = origins.filter(o => o === "http://localhost:4321").length;
+    expect(count).toBe(1);
+  });
+
+  test("defaults proto to http when x-forwarded-proto is absent", async () => {
+    const req = mockRequest({
+      "x-forwarded-host": "gitea.internal",
+    });
+    const origins = await resolveTrustedOrigins(req);
+    expect(origins).toContain("http://gitea.internal");
+  });
+});

src/lib/auth.ts

@@ -5,6 +5,73 @@ import { sso } from "@better-auth/sso";
 import { db, users } from "./db";
 import * as schema from "./db/schema";
 import { eq } from "drizzle-orm";
+import { withBase } from "./base-path";
+
+/**
+ * Resolves the list of trusted origins for Better Auth CSRF validation.
+ * Exported for testing. Called per-request with the incoming Request,
+ * or at startup with no request (static origins only).
+ */
+export async function resolveTrustedOrigins(request?: Request): Promise<string[]> {
+  const origins: string[] = [
+    "http://localhost:4321",
+    "http://localhost:8080", // Keycloak
+  ];
+
+  // Add the primary URL from BETTER_AUTH_URL
+  const primaryUrl = process.env.BETTER_AUTH_URL;
+  if (primaryUrl && typeof primaryUrl === 'string' && primaryUrl.trim() !== '') {
+    try {
+      const validatedUrl = new URL(primaryUrl.trim());
+      origins.push(validatedUrl.origin);
+    } catch {
+      // Skip if invalid
+    }
+  }
+
+  // Add additional trusted origins from environment
+  if (process.env.BETTER_AUTH_TRUSTED_ORIGINS) {
+    const additionalOrigins = process.env.BETTER_AUTH_TRUSTED_ORIGINS
+      .split(',')
+      .map(o => o.trim())
+      .filter(o => o !== '');
+
+    for (const origin of additionalOrigins) {
+      try {
+        const validatedUrl = new URL(origin);
+        origins.push(validatedUrl.origin);
+      } catch {
+        console.warn(`Invalid trusted origin: ${origin}, skipping`);
+      }
+    }
+  }
+
+  // Auto-detect origin from the incoming request's Host header when running
+  // behind a reverse proxy. Helps with Better Auth's per-request CSRF check.
+  if (request?.headers) {
+    // Take first value only — headers can be comma-separated in chained proxy setups
+    const rawHost = request.headers.get("x-forwarded-host") || request.headers.get("host");
+    const host = rawHost?.split(",")[0].trim();
+    if (host) {
+      const rawProto = request.headers.get("x-forwarded-proto") || "http";
+      const proto = rawProto.split(",")[0].trim().toLowerCase();
+      if (proto === "http" || proto === "https") {
+        try {
+          const detected = new URL(`${proto}://${host}`);
+          origins.push(detected.origin);
+        } catch {
+          // Malformed header, ignore
+        }
+      }
+    }
+  }
+
+  const uniqueOrigins = [...new Set(origins.filter(Boolean))];
+  if (!request) {
+    console.info("Trusted origins (static):", uniqueOrigins);
+  }
+  return uniqueOrigins;
+}
 
 export const auth = betterAuth({
   // Database configuration
@@ -31,7 +98,7 @@ export const auth = betterAuth({
     try {
       // Validate URL format and ensure it's a proper origin
       const validatedUrl = new URL(url.trim());
-      const cleanUrl = validatedUrl.origin; // Use origin to ensure no trailing paths
+      const cleanUrl = validatedUrl.origin;
       console.info('Using BETTER_AUTH_URL:', cleanUrl);
       return cleanUrl;
     } catch (e) {
@@ -41,50 +108,13 @@ export const auth = betterAuth({
       return defaultUrl;
     }
   })(),
-  basePath: "/api/auth", // Specify the base path for auth endpoints
+  basePath: withBase("/api/auth"), // Specify the base path for auth endpoints
   
-  // Trusted origins - this is how we support multiple access URLs
-  trustedOrigins: (() => {
-    const origins: string[] = [
-      "http://localhost:4321",
-      "http://localhost:8080", // Keycloak
-    ];
-    
-    // Add the primary URL from BETTER_AUTH_URL
-    const primaryUrl = process.env.BETTER_AUTH_URL;
-    if (primaryUrl && typeof primaryUrl === 'string' && primaryUrl.trim() !== '') {
-      try {
-        const validatedUrl = new URL(primaryUrl.trim());
-        origins.push(validatedUrl.origin);
-      } catch {
-        // Skip if invalid
-      }
-    }
-    
-    // Add additional trusted origins from environment
-    // This is where users can specify multiple access URLs
-    if (process.env.BETTER_AUTH_TRUSTED_ORIGINS) {
-      const additionalOrigins = process.env.BETTER_AUTH_TRUSTED_ORIGINS
-        .split(',')
-        .map(o => o.trim())
-        .filter(o => o !== '');
-      
-      // Validate each additional origin
-      for (const origin of additionalOrigins) {
-        try {
-          const validatedUrl = new URL(origin);
-          origins.push(validatedUrl.origin);
-        } catch {
-          console.warn(`Invalid trusted origin: ${origin}, skipping`);
-        }
-      }
-    }
-    
-    // Remove duplicates and empty strings, then return
-    const uniqueOrigins = [...new Set(origins.filter(Boolean))];
-    console.info('Trusted origins:', uniqueOrigins);
-    return uniqueOrigins;
-  })(),
+  // Trusted origins - this is how we support multiple access URLs.
+  // Uses the function form so that the origin can be auto-detected from
+  // the incoming request's Host / X-Forwarded-* headers, which makes the
+  // app work behind a reverse proxy without manual env var configuration.
+  trustedOrigins: (request?: Request) => resolveTrustedOrigins(request),
 
   // Authentication methods
   emailAndPassword: {
@@ -115,14 +145,20 @@ export const auth = betterAuth({
         input: false, // Don't show in signup form - we'll derive from email
       }
     },
+    changeEmail: {
+      enabled: true,
+      // Email verification isn't wired up (sendResetPassword is a TODO),
+      // so allow direct updates. Safe here because emails stay unverified.
+      updateEmailWithoutVerification: true,
+    },
   },
 
   // Plugins configuration
   plugins: [
     // OIDC Provider plugin - allows this app to act as an OIDC provider
     oidcProvider({
-      loginPage: "/login",
-      consentPage: "/oauth/consent",
+      loginPage: withBase("/login"),
+      consentPage: withBase("/oauth/consent"),
       // Allow dynamic client registration for flexibility
       allowDynamicClientRegistration: true,
       // Note: trustedClients would be configured here if Better Auth supports it

src/lib/base-path.test.ts

@@ -0,0 +1,86 @@
+import { afterEach, describe, expect, test } from "bun:test";
+
+const originalBaseUrl = process.env.BASE_URL;
+const originalWindow = (globalThis as { window?: unknown }).window;
+
+async function loadModule(baseUrl?: string, runtimeWindowBasePath?: string) {
+  if (baseUrl === undefined) {
+    delete process.env.BASE_URL;
+  } else {
+    process.env.BASE_URL = baseUrl;
+  }
+
+  if (runtimeWindowBasePath === undefined) {
+    if (originalWindow === undefined) {
+      delete (globalThis as { window?: unknown }).window;
+    } else {
+      (globalThis as { window?: unknown }).window = originalWindow;
+      const restoredWindow = (globalThis as { window?: { __GITEA_MIRROR_BASE_PATH__?: string } }).window;
+      if (typeof restoredWindow === "object" && restoredWindow !== null) {
+        delete restoredWindow.__GITEA_MIRROR_BASE_PATH__;
+      }
+    }
+  } else {
+    (globalThis as { window?: { __GITEA_MIRROR_BASE_PATH__?: string } }).window = {
+      __GITEA_MIRROR_BASE_PATH__: runtimeWindowBasePath,
+    };
+  }
+
+  return import(`./base-path.ts?case=${encodeURIComponent(baseUrl ?? "default")}-${Date.now()}-${Math.random()}`);
+}
+
+afterEach(() => {
+  if (originalBaseUrl === undefined) {
+    delete process.env.BASE_URL;
+  } else {
+    process.env.BASE_URL = originalBaseUrl;
+  }
+
+  if (originalWindow === undefined) {
+    delete (globalThis as { window?: unknown }).window;
+  } else {
+    (globalThis as { window?: unknown }).window = originalWindow;
+  }
+});
+
+describe("base-path helpers", () => {
+  test("defaults to root paths", async () => {
+    const mod = await loadModule(undefined);
+
+    expect(mod.BASE_PATH).toBe("/");
+    expect(mod.withBase("/api/health")).toBe("/api/health");
+    expect(mod.withBase("repositories")).toBe("/repositories");
+    expect(mod.stripBasePath("/config")).toBe("/config");
+  });
+
+  test("normalizes prefixed base paths", async () => {
+    const mod = await loadModule("mirror/");
+
+    expect(mod.BASE_PATH).toBe("/mirror");
+    expect(mod.withBase("/api/health")).toBe("/mirror/api/health");
+    expect(mod.withBase("repositories")).toBe("/mirror/repositories");
+    expect(mod.stripBasePath("/mirror/config")).toBe("/config");
+    expect(mod.stripBasePath("/mirror")).toBe("/");
+  });
+
+  test("keeps absolute URLs unchanged", async () => {
+    const mod = await loadModule("/mirror");
+
+    expect(mod.withBase("https://example.com/path")).toBe("https://example.com/path");
+  });
+
+  test("uses browser runtime base path when process env is unset", async () => {
+    const mod = await loadModule(undefined, "/runtime");
+
+    expect(mod.BASE_PATH).toBe("/runtime");
+    expect(mod.withBase("/api/health")).toBe("/runtime/api/health");
+    expect(mod.stripBasePath("/runtime/config")).toBe("/config");
+  });
+
+  test("prefers process env base path over browser runtime value", async () => {
+    const mod = await loadModule("/env", "/runtime");
+
+    expect(mod.BASE_PATH).toBe("/env");
+    expect(mod.withBase("/api/health")).toBe("/env/api/health");
+  });
+});

src/lib/base-path.ts

@@ -0,0 +1,83 @@
+const URL_SCHEME_REGEX = /^[a-zA-Z][a-zA-Z\d+\-.]*:/;
+const BASE_PATH_WINDOW_KEY = "__GITEA_MIRROR_BASE_PATH__";
+
+function normalizeBasePath(basePath: string | null | undefined): string {
+  if (!basePath) {
+    return "/";
+  }
+
+  let normalized = basePath.trim();
+  if (!normalized) {
+    return "/";
+  }
+
+  if (!normalized.startsWith("/")) {
+    normalized = `/${normalized}`;
+  }
+
+  normalized = normalized.replace(/\/+$/, "");
+  return normalized || "/";
+}
+
+function resolveRuntimeBasePath(): string {
+  if (typeof process !== "undefined" && typeof process.env?.BASE_URL === "string") {
+    return normalizeBasePath(process.env.BASE_URL);
+  }
+
+  if (typeof window !== "undefined") {
+    const runtimeBasePath = (window as Window & { [BASE_PATH_WINDOW_KEY]?: string })[BASE_PATH_WINDOW_KEY];
+    if (typeof runtimeBasePath === "string") {
+      return normalizeBasePath(runtimeBasePath);
+    }
+  }
+
+  return "/";
+}
+
+export function getBasePath(): string {
+  return resolveRuntimeBasePath();
+}
+
+export const BASE_PATH = getBasePath();
+export { BASE_PATH_WINDOW_KEY };
+
+export function withBase(path: string): string {
+  const basePath = getBasePath();
+
+  if (!path) {
+    return basePath === "/" ? "/" : `${basePath}/`;
+  }
+
+  if (URL_SCHEME_REGEX.test(path) || path.startsWith("//")) {
+    return path;
+  }
+
+  const normalizedPath = path.startsWith("/") ? path : `/${path}`;
+  if (basePath === "/") {
+    return normalizedPath;
+  }
+
+  return `${basePath}${normalizedPath}`;
+}
+
+export function stripBasePath(pathname: string): string {
+  const basePath = getBasePath();
+
+  if (!pathname) {
+    return "/";
+  }
+
+  if (basePath === "/") {
+    return pathname;
+  }
+
+  if (pathname === basePath || pathname === `${basePath}/`) {
+    return "/";
+  }
+
+  if (pathname.startsWith(`${basePath}/`)) {
+    return pathname.slice(basePath.length) || "/";
+  }
+
+  return pathname;
+}

src/lib/config.ts

@@ -19,8 +19,23 @@ export const ENV = {
   },
 
   // Better Auth secret for authentication
-  BETTER_AUTH_SECRET:
-    process.env.BETTER_AUTH_SECRET || "your-secret-key-change-this-in-production",
+  get BETTER_AUTH_SECRET(): string {
+    const secret = process.env.BETTER_AUTH_SECRET;
+    const knownInsecureDefaults = [
+      "your-secret-key-change-this-in-production",
+      "dev-only-insecure-secret-do-not-use-in-production",
+    ];
+    if (!secret || knownInsecureDefaults.includes(secret)) {
+      if (process.env.NODE_ENV === "production") {
+        console.error(
+          "\x1b[31m[SECURITY WARNING]\x1b[0m BETTER_AUTH_SECRET is missing or using an insecure default. " +
+          "Set a strong secret: openssl rand -base64 32"
+        );
+      }
+      return secret || "dev-only-insecure-secret-do-not-use-in-production";
+    }
+    return secret;
+  },
 
   // Server host and port
   HOST: process.env.HOST || "localhost",

src/lib/db/index.ts

@@ -35,13 +35,54 @@ if (process.env.NODE_ENV !== "test") {
   // Create drizzle instance with the SQLite client
   db = drizzle({ client: sqlite });
 
+  /**
+   * Fix migration records that were marked as applied but whose DDL actually
+   * failed (e.g. the v3.13.0 release where ALTER TABLE with expression default
+   * was rejected by SQLite). Without this, Drizzle skips the migration on
+   * retry because it thinks it already ran.
+   *
+   * Drizzle tracks migrations by `created_at` (= journal timestamp) and only
+   * looks at the most recent record. If the last recorded timestamp is >= the
+   * failed migration's timestamp but the expected column is missing, we delete
+   * stale records so the migration re-runs.
+   */
+  function repairFailedMigrations() {
+    try {
+      const migrationsTableExists = sqlite
+        .query("SELECT name FROM sqlite_master WHERE type='table' AND name='__drizzle_migrations'")
+        .get();
+
+      if (!migrationsTableExists) return;
+
+      // Migration 0009 journal timestamp (from drizzle/meta/_journal.json)
+      const MIGRATION_0009_TIMESTAMP = 1773542995732;
+
+      const lastMigration = sqlite
+        .query("SELECT id, created_at FROM __drizzle_migrations ORDER BY created_at DESC LIMIT 1")
+        .get() as { id: number; created_at: number } | null;
+
+      if (!lastMigration || Number(lastMigration.created_at) < MIGRATION_0009_TIMESTAMP) return;
+
+      // Migration 0009 is recorded as applied — verify the column actually exists
+      const columns = sqlite.query("PRAGMA table_info(repositories)").all() as { name: string }[];
+      const hasImportedAt = columns.some((c) => c.name === "imported_at");
+
+      if (!hasImportedAt) {
+        console.log("🔧 Detected failed migration 0009 (imported_at column missing). Removing stale record so it can re-run...");
+        sqlite.prepare("DELETE FROM __drizzle_migrations WHERE created_at >= ?").run(MIGRATION_0009_TIMESTAMP);
+      }
+    } catch (error) {
+      console.warn("⚠️ Migration repair check failed (non-fatal):", error);
+    }
+  }
+
   /**
    * Run Drizzle migrations
    */
   function runDrizzleMigrations() {
     try {
       console.log("🔄 Checking for pending migrations...");
-      
+
       // Check if migrations table exists
       const migrationsTableExists = sqlite
         .query("SELECT name FROM sqlite_master WHERE type='table' AND name='__drizzle_migrations'")
@@ -51,9 +92,12 @@ if (process.env.NODE_ENV !== "test") {
         console.log("📦 First time setup - running initial migrations...");
       }
 
+      // Fix any migrations that were recorded but actually failed (e.g. v3.13.0 bug)
+      repairFailedMigrations();
+
       // Run migrations using Drizzle migrate function
       migrate(db, { migrationsFolder: "./drizzle" });
-      
+
       console.log("✅ Database migrations completed successfully");
     } catch (error) {
       console.error("❌ Error running migrations:", error);

src/lib/db/migrations.test.ts

@@ -0,0 +1,26 @@
+import { expect, test } from "bun:test";
+
+function decodeOutput(output: ArrayBufferLike | Uint8Array | null | undefined) {
+  if (!output) {
+    return "";
+  }
+
+  return Buffer.from(output as ArrayBufferLike).toString("utf8");
+}
+
+test("migration validation script passes", () => {
+  const result = Bun.spawnSync({
+    cmd: ["bun", "scripts/validate-migrations.ts"],
+    cwd: process.cwd(),
+    stdout: "pipe",
+    stderr: "pipe",
+  });
+
+  const stdout = decodeOutput(result.stdout);
+  const stderr = decodeOutput(result.stderr);
+
+  expect(
+    result.exitCode,
+    `Migration validation script failed.\nstdout:\n${stdout}\nstderr:\n${stderr}`,
+  ).toBe(0);
+});

src/lib/db/schema.ts

@@ -23,16 +23,26 @@ export const githubConfigSchema = z.object({
   includeArchived: z.boolean().default(false),
   includePrivate: z.boolean().default(true),
   includePublic: z.boolean().default(true),
+  includeCollaboratorRepos: z.boolean().default(true),
   includeOrganizations: z.array(z.string()).default([]),
   starredReposOrg: z.string().optional(),
   starredReposMode: z.enum(["dedicated-org", "preserve-owner"]).default("dedicated-org"),
+  starredLists: z.array(z.string()).default([]),
   mirrorStrategy: z.enum(["preserve", "single-org", "flat-user", "mixed"]).default("preserve"),
   defaultOrg: z.string().optional(),
   starredCodeOnly: z.boolean().default(false),
+  autoMirrorStarred: z.boolean().default(false),
   skipStarredIssues: z.boolean().optional(), // Deprecated: kept for backward compatibility, use starredCodeOnly instead
   starredDuplicateStrategy: z.enum(["suffix", "prefix", "owner-org"]).default("suffix").optional(),
 });
 
+export const backupStrategyEnum = z.enum([
+  "disabled",
+  "always",
+  "on-force-push",
+  "block-on-force-push",
+]);
+
 export const giteaConfigSchema = z.object({
   url: z.url(),
   externalUrl: z.url().optional(),
@@ -65,6 +75,12 @@ export const giteaConfigSchema = z.object({
   mirrorPullRequests: z.boolean().default(false),
   mirrorLabels: z.boolean().default(false),
   mirrorMilestones: z.boolean().default(false),
+  backupStrategy: backupStrategyEnum.default("on-force-push"),
+  backupBeforeSync: z.boolean().default(true), // Deprecated: kept for backward compat, use backupStrategy
+  backupRetentionCount: z.number().int().min(1).default(5),
+  backupRetentionDays: z.number().int().min(0).default(30),
+  backupDirectory: z.string().optional(),
+  blockSyncOnBackupFailure: z.boolean().default(true),
 });
 
 export const scheduleConfigSchema = z.object({
@@ -108,6 +124,31 @@ export const cleanupConfigSchema = z.object({
   nextRun: z.coerce.date().optional(),
 });
 
+export const ntfyConfigSchema = z.object({
+  url: z.string().default("https://ntfy.sh"),
+  topic: z.string().default(""),
+  token: z.string().optional(),
+  priority: z.enum(["min", "low", "default", "high", "urgent"]).default("default"),
+});
+
+export const appriseConfigSchema = z.object({
+  url: z.string().default(""),
+  token: z.string().default(""),
+  tag: z.string().optional(),
+});
+
+export const notificationConfigSchema = z.object({
+  enabled: z.boolean().default(false),
+  provider: z.enum(["ntfy", "apprise"]).default("ntfy"),
+  notifyOnSyncError: z.boolean().default(true),
+  notifyOnSyncSuccess: z.boolean().default(false),
+  notifyOnNewRepo: z.boolean().default(false),
+  ntfy: ntfyConfigSchema.optional(),
+  apprise: appriseConfigSchema.optional(),
+});
+
+export type NotificationConfig = z.infer<typeof notificationConfigSchema>;
+
 export const configSchema = z.object({
   id: z.string(),
   userId: z.string(),
@@ -161,12 +202,14 @@ export const repositorySchema = z.object({
       "syncing",
       "synced",
       "archived",
+      "pending-approval", // Blocked by force-push detection, needs manual approval
     ])
     .default("imported"),
   lastMirrored: z.coerce.date().optional().nullable(),
   errorMessage: z.string().optional().nullable(),
   destinationOrg: z.string().optional().nullable(),
   metadata: z.string().optional().nullable(), // JSON string for metadata sync state
+  importedAt: z.coerce.date(),
   createdAt: z.coerce.date(),
   updatedAt: z.coerce.date(),
 });
@@ -192,6 +235,7 @@ export const mirrorJobSchema = z.object({
       "syncing",
       "synced",
       "archived",
+      "pending-approval",
     ])
     .default("imported"),
   message: z.string(),
@@ -320,6 +364,11 @@ export const configs = sqliteTable("configs", {
     .$type<z.infer<typeof cleanupConfigSchema>>()
     .notNull(),
 
+  notificationConfig: text("notification_config", { mode: "json" })
+    .$type<z.infer<typeof notificationConfigSchema>>()
+    .notNull()
+    .default(sql`'{"enabled":false,"provider":"ntfy","notifyOnSyncError":true,"notifyOnSyncSuccess":false,"notifyOnNewRepo":false}'`),
+
   createdAt: integer("created_at", { mode: "timestamp" })
     .notNull()
     .default(sql`(unixepoch())`),
@@ -380,6 +429,9 @@ export const repositories = sqliteTable("repositories", {
   destinationOrg: text("destination_org"),
 
   metadata: text("metadata"), // JSON string storing metadata sync state (issues, PRs, releases, etc.)
+  importedAt: integer("imported_at", { mode: "timestamp" })
+    .notNull()
+    .default(sql`(unixepoch())`),
 
   createdAt: integer("created_at", { mode: "timestamp" })
     .notNull()
@@ -395,8 +447,10 @@ export const repositories = sqliteTable("repositories", {
   index("idx_repositories_organization").on(table.organization),
   index("idx_repositories_is_fork").on(table.isForked),
   index("idx_repositories_is_starred").on(table.isStarred),
+  index("idx_repositories_user_imported_at").on(table.userId, table.importedAt),
   uniqueIndex("uniq_repositories_user_full_name").on(table.userId, table.fullName),
   uniqueIndex("uniq_repositories_user_normalized_full_name").on(table.userId, table.normalizedFullName),
+  index("idx_repositories_mirrored_location").on(table.userId, table.mirroredLocation),
 ]);
 
 export const mirrorJobs = sqliteTable("mirror_jobs", {

src/lib/env-config-loader.ts

@@ -4,7 +4,7 @@
  */
 
 import { db, configs, users } from '@/lib/db';
-import { eq, and } from 'drizzle-orm';
+import { eq, and, sql } from 'drizzle-orm';
 import { v4 as uuidv4 } from 'uuid';
 import { encrypt } from '@/lib/utils/encryption';
 
@@ -15,6 +15,7 @@ interface EnvConfig {
     type?: 'personal' | 'organization';
     privateRepositories?: boolean;
     publicRepositories?: boolean;
+    includeCollaboratorRepos?: boolean;
     mirrorStarred?: boolean;
     skipForks?: boolean;
     includeArchived?: boolean;
@@ -22,8 +23,10 @@ interface EnvConfig {
     preserveOrgStructure?: boolean;
     onlyMirrorOrgs?: boolean;
     starredCodeOnly?: boolean;
+    autoMirrorStarred?: boolean;
     starredReposOrg?: string;
     starredReposMode?: 'dedicated-org' | 'preserve-owner';
+    starredLists?: string[];
     mirrorStrategy?: 'preserve' | 'single-org' | 'flat-user' | 'mixed';
   };
   gitea: {
@@ -98,6 +101,9 @@ function parseEnvConfig(): EnvConfig {
   const protectedRepos = process.env.CLEANUP_PROTECTED_REPOS 
     ? process.env.CLEANUP_PROTECTED_REPOS.split(',').map(r => r.trim()).filter(Boolean)
     : undefined;
+  const starredLists = process.env.MIRROR_STARRED_LISTS
+    ? process.env.MIRROR_STARRED_LISTS.split(',').map((list) => list.trim()).filter(Boolean)
+    : undefined;
 
   return {
     github: {
@@ -106,6 +112,11 @@ function parseEnvConfig(): EnvConfig {
       type: process.env.GITHUB_TYPE as 'personal' | 'organization',
       privateRepositories: process.env.PRIVATE_REPOSITORIES === 'true',
       publicRepositories: process.env.PUBLIC_REPOSITORIES === 'true',
+      // Tri-state parse so unset falls through to existingConfig / schema default (true).
+      includeCollaboratorRepos:
+        process.env.INCLUDE_COLLABORATOR_REPOS === 'true' ? true
+        : process.env.INCLUDE_COLLABORATOR_REPOS === 'false' ? false
+        : undefined,
       mirrorStarred: process.env.MIRROR_STARRED === 'true',
       skipForks: process.env.SKIP_FORKS === 'true',
       includeArchived: process.env.INCLUDE_ARCHIVED === 'true',
@@ -113,8 +124,10 @@ function parseEnvConfig(): EnvConfig {
       preserveOrgStructure: process.env.PRESERVE_ORG_STRUCTURE === 'true',
       onlyMirrorOrgs: process.env.ONLY_MIRROR_ORGS === 'true',
       starredCodeOnly: process.env.SKIP_STARRED_ISSUES === 'true',
+      autoMirrorStarred: process.env.AUTO_MIRROR_STARRED === 'true',
       starredReposOrg: process.env.STARRED_REPOS_ORG,
       starredReposMode: process.env.STARRED_REPOS_MODE as 'dedicated-org' | 'preserve-owner',
+      starredLists,
       mirrorStrategy: process.env.MIRROR_STRATEGY as 'preserve' | 'single-org' | 'flat-user' | 'mixed',
     },
     gitea: {
@@ -217,10 +230,12 @@ export async function initializeConfigFromEnv(): Promise<void> {
 
     console.log('[ENV Config Loader] Found environment configuration, initializing...');
 
-    // Get the first user (admin user)
+    // Get the first user (admin user) — deterministic order so we always pick the
+    // same row across restarts even if multiple users exist.
     const firstUser = await db
       .select()
       .from(users)
+      .orderBy(sql`${users.createdAt} ASC`)
       .limit(1);
 
     if (firstUser.length === 0) {
@@ -230,11 +245,14 @@ export async function initializeConfigFromEnv(): Promise<void> {
 
     const userId = firstUser[0].id;
 
-    // Check if config already exists for this user
+    // Check if config already exists for this user — prefer the active config and
+    // fall back to most-recently-updated so we never write env values into a stale
+    // inactive stub while the populated active row sits untouched (see issue #271).
     const existingConfig = await db
       .select()
       .from(configs)
       .where(eq(configs.userId, userId))
+      .orderBy(sql`${configs.isActive} DESC`, sql`${configs.updatedAt} DESC`)
       .limit(1);
 
     // Determine mirror strategy based on environment variables or use explicit value
@@ -258,12 +276,15 @@ export async function initializeConfigFromEnv(): Promise<void> {
       includeArchived: envConfig.github.includeArchived ?? existingConfig?.[0]?.githubConfig?.includeArchived ?? false,
       includePrivate: envConfig.github.privateRepositories ?? existingConfig?.[0]?.githubConfig?.includePrivate ?? false,
       includePublic: envConfig.github.publicRepositories ?? existingConfig?.[0]?.githubConfig?.includePublic ?? true,
+      includeCollaboratorRepos: envConfig.github.includeCollaboratorRepos ?? existingConfig?.[0]?.githubConfig?.includeCollaboratorRepos ?? true,
       includeOrganizations: envConfig.github.mirrorOrganizations ? [] : (existingConfig?.[0]?.githubConfig?.includeOrganizations ?? []),
       starredReposOrg: envConfig.github.starredReposOrg || existingConfig?.[0]?.githubConfig?.starredReposOrg || 'starred',
       starredReposMode: envConfig.github.starredReposMode || existingConfig?.[0]?.githubConfig?.starredReposMode || 'dedicated-org',
       mirrorStrategy,
       defaultOrg: envConfig.gitea.organization || existingConfig?.[0]?.githubConfig?.defaultOrg || 'github-mirrors',
       starredCodeOnly: envConfig.github.starredCodeOnly ?? existingConfig?.[0]?.githubConfig?.starredCodeOnly ?? false,
+      autoMirrorStarred: envConfig.github.autoMirrorStarred ?? existingConfig?.[0]?.githubConfig?.autoMirrorStarred ?? false,
+      starredLists: envConfig.github.starredLists ?? existingConfig?.[0]?.githubConfig?.starredLists ?? [],
     };
 
     // Build Gitea config
@@ -299,6 +320,13 @@ export async function initializeConfigFromEnv(): Promise<void> {
       mirrorPullRequests: envConfig.mirror.mirrorPullRequests ?? existingConfig?.[0]?.giteaConfig?.mirrorPullRequests ?? false,
       mirrorLabels: envConfig.mirror.mirrorLabels ?? existingConfig?.[0]?.giteaConfig?.mirrorLabels ?? false,
       mirrorMilestones: envConfig.mirror.mirrorMilestones ?? existingConfig?.[0]?.giteaConfig?.mirrorMilestones ?? false,
+      // Backup options — preserve existing values so UI-configured settings survive restart
+      backupStrategy: existingConfig?.[0]?.giteaConfig?.backupStrategy ?? 'on-force-push',
+      backupBeforeSync: existingConfig?.[0]?.giteaConfig?.backupBeforeSync ?? true,
+      backupRetentionCount: existingConfig?.[0]?.giteaConfig?.backupRetentionCount ?? 5,
+      backupRetentionDays: existingConfig?.[0]?.giteaConfig?.backupRetentionDays ?? 30,
+      backupDirectory: existingConfig?.[0]?.giteaConfig?.backupDirectory || undefined,
+      blockSyncOnBackupFailure: existingConfig?.[0]?.giteaConfig?.blockSyncOnBackupFailure ?? true,
     };
 
     // Build schedule config with support for interval as string or number

src/lib/gitea-enhanced.test.ts

@@ -13,6 +13,11 @@ const mockMirrorGitRepoPullRequestsToGitea = mock(() => Promise.resolve());
 const mockMirrorGitRepoLabelsToGitea = mock(() => Promise.resolve());
 const mockMirrorGitRepoMilestonesToGitea = mock(() => Promise.resolve());
 const mockGetGiteaRepoOwnerAsync = mock(() => Promise.resolve("starred"));
+const mockCreatePreSyncBundleBackup = mock(() =>
+  Promise.resolve({ bundlePath: "/tmp/mock.bundle" })
+);
+let mockShouldCreatePreSyncBackup = false;
+let mockShouldBlockSyncOnBackupFailure = true;
 
 // Mock the database module
 const mockDb = {
@@ -28,8 +33,14 @@ const mockDb = {
 
 mock.module("@/lib/db", () => ({
   db: mockDb,
+  users: {},
+  configs: {},
+  organizations: {},
   mirrorJobs: {},
-  repositories: {}
+  repositories: {},
+  events: {},
+  accounts: {},
+  sessions: {},
 }));
 
 // Mock config encryption
@@ -235,6 +246,12 @@ mock.module("@/lib/http-client", () => ({
   HttpError: MockHttpError
 }));
 
+mock.module("@/lib/repo-backup", () => ({
+  createPreSyncBundleBackup: mockCreatePreSyncBundleBackup,
+  shouldCreatePreSyncBackup: () => mockShouldCreatePreSyncBackup,
+  shouldBlockSyncOnBackupFailure: () => mockShouldBlockSyncOnBackupFailure,
+}));
+
 // Now import the modules we're testing
 import { 
   getGiteaRepoInfo, 
@@ -264,6 +281,15 @@ describe("Enhanced Gitea Operations", () => {
     mockMirrorGitRepoMilestonesToGitea.mockClear();
     mockGetGiteaRepoOwnerAsync.mockClear();
     mockGetGiteaRepoOwnerAsync.mockImplementation(() => Promise.resolve("starred"));
+    mockHttpGet.mockClear();
+    mockHttpPost.mockClear();
+    mockHttpDelete.mockClear();
+    mockCreatePreSyncBundleBackup.mockClear();
+    mockCreatePreSyncBundleBackup.mockImplementation(() =>
+      Promise.resolve({ bundlePath: "/tmp/mock.bundle" })
+    );
+    mockShouldCreatePreSyncBackup = false;
+    mockShouldBlockSyncOnBackupFailure = true;
     // Reset tracking variables
     orgCheckCount = 0;
     orgTestContext = "";
@@ -529,6 +555,182 @@ describe("Enhanced Gitea Operations", () => {
       expect(releaseCall.octokit).toBeDefined();
     });
 
+    test("prefers recorded mirroredLocation when owner resolution changes", async () => {
+      mockGetGiteaRepoOwnerAsync.mockImplementation(() => Promise.resolve("ceph"));
+
+      const config: Partial<Config> = {
+        userId: "user123",
+        githubConfig: {
+          username: "testuser",
+          token: "github-token",
+          privateRepositories: false,
+          mirrorStarred: true,
+        },
+        giteaConfig: {
+          url: "https://gitea.example.com",
+          token: "encrypted-token",
+          defaultOwner: "testuser",
+          mirrorReleases: true,
+        },
+      };
+
+      const repository: Repository = {
+        id: "repo789",
+        name: "test-repo",
+        fullName: "ceph/test-repo",
+        owner: "ceph",
+        cloneUrl: "https://github.com/ceph/test-repo.git",
+        isPrivate: false,
+        isStarred: true,
+        status: repoStatusEnum.parse("mirrored"),
+        visibility: "public",
+        userId: "user123",
+        mirroredLocation: "starred/test-repo",
+        createdAt: new Date(),
+        updatedAt: new Date(),
+      };
+
+      const result = await syncGiteaRepoEnhanced(
+        { config, repository },
+        {
+          getGiteaRepoOwnerAsync: mockGetGiteaRepoOwnerAsync,
+          mirrorGitHubReleasesToGitea: mockMirrorGitHubReleasesToGitea,
+          mirrorGitRepoIssuesToGitea: mockMirrorGitRepoIssuesToGitea,
+          mirrorGitRepoPullRequestsToGitea: mockMirrorGitRepoPullRequestsToGitea,
+          mirrorGitRepoLabelsToGitea: mockMirrorGitRepoLabelsToGitea,
+          mirrorGitRepoMilestonesToGitea: mockMirrorGitRepoMilestonesToGitea,
+        }
+      );
+
+      expect(result).toEqual({ success: true });
+
+      const mirrorSyncCalls = mockHttpPost.mock.calls.filter((call) =>
+        String(call[0]).includes("/mirror-sync")
+      );
+      expect(mirrorSyncCalls).toHaveLength(1);
+      expect(String(mirrorSyncCalls[0][0])).toContain("/api/v1/repos/starred/test-repo/mirror-sync");
+      expect(String(mirrorSyncCalls[0][0])).not.toContain("/api/v1/repos/ceph/test-repo/mirror-sync");
+    });
+
+    test("blocks sync when pre-sync snapshot fails and blocking is enabled", async () => {
+      mockShouldCreatePreSyncBackup = true;
+      mockShouldBlockSyncOnBackupFailure = true;
+      mockCreatePreSyncBundleBackup.mockImplementation(() =>
+        Promise.reject(new Error("simulated backup failure"))
+      );
+
+      const config: Partial<Config> = {
+        userId: "user123",
+        githubConfig: {
+          username: "testuser",
+          token: "github-token",
+          privateRepositories: false,
+          mirrorStarred: true,
+        },
+        giteaConfig: {
+          url: "https://gitea.example.com",
+          token: "encrypted-token",
+          defaultOwner: "testuser",
+          mirrorReleases: false,
+          backupStrategy: "always",
+          blockSyncOnBackupFailure: true,
+        },
+      };
+
+      const repository: Repository = {
+        id: "repo456",
+        name: "mirror-repo",
+        fullName: "user/mirror-repo",
+        owner: "user",
+        cloneUrl: "https://github.com/user/mirror-repo.git",
+        isPrivate: false,
+        isStarred: true,
+        status: repoStatusEnum.parse("mirrored"),
+        visibility: "public",
+        userId: "user123",
+        createdAt: new Date(),
+        updatedAt: new Date(),
+      };
+
+      await expect(
+        syncGiteaRepoEnhanced(
+          { config, repository },
+          {
+            getGiteaRepoOwnerAsync: mockGetGiteaRepoOwnerAsync,
+            mirrorGitHubReleasesToGitea: mockMirrorGitHubReleasesToGitea,
+            mirrorGitRepoIssuesToGitea: mockMirrorGitRepoIssuesToGitea,
+            mirrorGitRepoPullRequestsToGitea: mockMirrorGitRepoPullRequestsToGitea,
+            mirrorGitRepoLabelsToGitea: mockMirrorGitRepoLabelsToGitea,
+            mirrorGitRepoMilestonesToGitea: mockMirrorGitRepoMilestonesToGitea,
+          }
+        )
+      ).rejects.toThrow("Snapshot failed; sync blocked to protect history.");
+
+      const mirrorSyncCalls = mockHttpPost.mock.calls.filter((call) =>
+        String(call[0]).includes("/mirror-sync")
+      );
+      expect(mirrorSyncCalls.length).toBe(0);
+    });
+
+    test("continues sync when pre-sync snapshot fails and blocking is disabled", async () => {
+      mockShouldCreatePreSyncBackup = true;
+      mockShouldBlockSyncOnBackupFailure = false;
+      mockCreatePreSyncBundleBackup.mockImplementation(() =>
+        Promise.reject(new Error("simulated backup failure"))
+      );
+
+      const config: Partial<Config> = {
+        userId: "user123",
+        githubConfig: {
+          username: "testuser",
+          token: "github-token",
+          privateRepositories: false,
+          mirrorStarred: true,
+        },
+        giteaConfig: {
+          url: "https://gitea.example.com",
+          token: "encrypted-token",
+          defaultOwner: "testuser",
+          mirrorReleases: false,
+          backupBeforeSync: true,
+          blockSyncOnBackupFailure: false,
+        },
+      };
+
+      const repository: Repository = {
+        id: "repo457",
+        name: "mirror-repo",
+        fullName: "user/mirror-repo",
+        owner: "user",
+        cloneUrl: "https://github.com/user/mirror-repo.git",
+        isPrivate: false,
+        isStarred: true,
+        status: repoStatusEnum.parse("mirrored"),
+        visibility: "public",
+        userId: "user123",
+        createdAt: new Date(),
+        updatedAt: new Date(),
+      };
+
+      const result = await syncGiteaRepoEnhanced(
+        { config, repository },
+        {
+          getGiteaRepoOwnerAsync: mockGetGiteaRepoOwnerAsync,
+          mirrorGitHubReleasesToGitea: mockMirrorGitHubReleasesToGitea,
+          mirrorGitRepoIssuesToGitea: mockMirrorGitRepoIssuesToGitea,
+          mirrorGitRepoPullRequestsToGitea: mockMirrorGitRepoPullRequestsToGitea,
+          mirrorGitRepoLabelsToGitea: mockMirrorGitRepoLabelsToGitea,
+          mirrorGitRepoMilestonesToGitea: mockMirrorGitRepoMilestonesToGitea,
+        }
+      );
+
+      expect(result).toEqual({ success: true });
+      const mirrorSyncCalls = mockHttpPost.mock.calls.filter((call) =>
+        String(call[0]).includes("/mirror-sync")
+      );
+      expect(mirrorSyncCalls.length).toBe(1);
+    });
+
     test("mirrors metadata components when enabled and not previously synced", async () => {
       const config: Partial<Config> = {
         userId: "user123",
@@ -587,7 +789,7 @@ describe("Enhanced Gitea Operations", () => {
       expect(mockMirrorGitRepoLabelsToGitea).not.toHaveBeenCalled();
     });
 
-    test("continues incremental issue and PR syncing when metadata was previously synced", async () => {
+    test("skips issues and PRs when metadata shows they were already synced", async () => {
       const config: Partial<Config> = {
         userId: "user123",
         githubConfig: {
@@ -646,11 +848,15 @@ describe("Enhanced Gitea Operations", () => {
         }
       );
 
+      // Metadata reconciliation now runs on every sync (mirror* functions
+      // are idempotent and PATCH existing entries by marker/name/title).
+      // Releases are still skipped here because the flag is off in this config.
+      // Labels are still skipped because the issues path also handles labels.
       expect(mockMirrorGitHubReleasesToGitea).not.toHaveBeenCalled();
       expect(mockMirrorGitRepoIssuesToGitea).toHaveBeenCalledTimes(1);
       expect(mockMirrorGitRepoPullRequestsToGitea).toHaveBeenCalledTimes(1);
       expect(mockMirrorGitRepoLabelsToGitea).not.toHaveBeenCalled();
-      expect(mockMirrorGitRepoMilestonesToGitea).not.toHaveBeenCalled();
+      expect(mockMirrorGitRepoMilestonesToGitea).toHaveBeenCalledTimes(1);
     });
   });
 

src/lib/gitea-enhanced.ts

@@ -8,13 +8,24 @@
 
 import type { Config } from "@/types/config";
 import type { Repository } from "./db/schema";
-import { Octokit } from "@octokit/rest";
+import type { Octokit } from "@octokit/rest";
+import { createGitHubClient } from "./github";
 import { createMirrorJob } from "./helpers";
 import { decryptConfigTokens } from "./utils/config-encryption";
 import { httpPost, httpGet, httpPatch, HttpError } from "./http-client";
 import { db, repositories } from "./db";
 import { eq } from "drizzle-orm";
 import { repoStatusEnum } from "@/types/Repository";
+import {
+  createPreSyncBundleBackup,
+  shouldCreatePreSyncBackup,
+  shouldBlockSyncOnBackupFailure,
+  resolveBackupStrategy,
+  shouldBackupForStrategy,
+  shouldBlockSyncForStrategy,
+  strategyNeedsDetection,
+} from "./repo-backup";
+import { detectForcePush } from "./utils/force-push-detection";
 import {
   parseRepositoryMetadataState,
   serializeRepositoryMetadataState,
@@ -42,6 +53,41 @@ interface GiteaRepoInfo {
   private: boolean;
 }
 
+interface SyncTargetCandidate {
+  owner: string;
+  repoName: string;
+}
+
+function parseMirroredLocation(location?: string | null): SyncTargetCandidate | null {
+  if (!location) return null;
+
+  const trimmed = location.trim();
+  if (!trimmed) return null;
+
+  const slashIndex = trimmed.indexOf("/");
+  if (slashIndex <= 0 || slashIndex === trimmed.length - 1) return null;
+
+  const owner = trimmed.slice(0, slashIndex).trim();
+  const repoName = trimmed.slice(slashIndex + 1).trim();
+  if (!owner || !repoName) return null;
+
+  return { owner, repoName };
+}
+
+function dedupeSyncTargets(targets: SyncTargetCandidate[]): SyncTargetCandidate[] {
+  const seen = new Set<string>();
+  const deduped: SyncTargetCandidate[] = [];
+
+  for (const target of targets) {
+    const key = `${target.owner}/${target.repoName}`.toLowerCase();
+    if (seen.has(key)) continue;
+    seen.add(key);
+    deduped.push(target);
+  }
+
+  return deduped;
+}
+
 /**
  * Check if a repository exists in Gitea and return its details
  */
@@ -250,9 +296,12 @@ export async function getOrCreateGiteaOrgEnhanced({
 export async function syncGiteaRepoEnhanced({
   config,
   repository,
+  skipForcePushDetection,
 }: {
   config: Partial<Config>;
   repository: Repository;
+  /** When true, skip force-push detection and blocking (used by approve-sync). */
+  skipForcePushDetection?: boolean;
 }, deps?: SyncDependencies): Promise<any> {
   try {
     if (!config.userId || !config.giteaConfig?.url || !config.giteaConfig?.token) {
@@ -272,19 +321,78 @@ export async function syncGiteaRepoEnhanced({
       })
       .where(eq(repositories.id, repository.id!));
 
-    // Get the expected owner
+    // Resolve sync target in a backward-compatible order:
+    // 1) recorded mirroredLocation (actual historical mirror location)
+    // 2) owner derived from current strategy/config
     const dependencies = deps ?? (await import("./gitea"));
-    const repoOwner = await dependencies.getGiteaRepoOwnerAsync({ config, repository });
+    const expectedOwner = await dependencies.getGiteaRepoOwnerAsync({ config, repository });
+    const recordedTarget = parseMirroredLocation(repository.mirroredLocation);
+    const candidateTargets = dedupeSyncTargets([
+      ...(recordedTarget ? [recordedTarget] : []),
+      { owner: expectedOwner, repoName: repository.name },
+    ]);
 
-    // Check if repo exists and get its info
-    const repoInfo = await getGiteaRepoInfo({
-      config,
-      owner: repoOwner,
-      repoName: repository.name,
-    });
+    let repoOwner = expectedOwner;
+    let repoName = repository.name;
+    let repoInfo: GiteaRepoInfo | null = null;
+    let firstNonMirrorTarget: SyncTargetCandidate | null = null;
+
+    for (const target of candidateTargets) {
+      const candidateInfo = await getGiteaRepoInfo({
+        config,
+        owner: target.owner,
+        repoName: target.repoName,
+      });
+
+      if (!candidateInfo) {
+        continue;
+      }
+
+      if (!candidateInfo.mirror) {
+        if (!firstNonMirrorTarget) {
+          firstNonMirrorTarget = target;
+        }
+        continue;
+      }
+
+      repoOwner = target.owner;
+      repoName = target.repoName;
+      repoInfo = candidateInfo;
+      break;
+    }
 
     if (!repoInfo) {
-      throw new Error(`Repository ${repository.name} not found in Gitea at ${repoOwner}/${repository.name}`);
+      if (firstNonMirrorTarget) {
+        console.warn(
+          `[Sync] Repository ${repository.name} exists at ${firstNonMirrorTarget.owner}/${firstNonMirrorTarget.repoName} but is not configured as a mirror`
+        );
+
+        await db
+          .update(repositories)
+          .set({
+            status: repoStatusEnum.parse("failed"),
+            updatedAt: new Date(),
+            errorMessage: "Repository exists in Gitea but is not configured as a mirror. Manual intervention required.",
+          })
+          .where(eq(repositories.id, repository.id!));
+
+        await createMirrorJob({
+          userId: config.userId,
+          repositoryId: repository.id,
+          repositoryName: repository.name,
+          message: `Cannot sync ${repository.name}: Not a mirror repository`,
+          details: `Repository ${repository.name} exists in Gitea but is not configured as a mirror. You may need to delete and recreate it as a mirror, or manually configure it as a mirror in Gitea.`,
+          status: "failed",
+        });
+
+        throw new Error(`Repository ${repository.name} is not a mirror. Cannot sync.`);
+      }
+
+      throw new Error(
+        `Repository ${repository.name} not found in Gitea. Tried locations: ${candidateTargets
+          .map((t) => `${t.owner}/${t.repoName}`)
+          .join(", ")}`
+      );
     }
 
     // Check if it's a mirror repository
@@ -313,25 +421,163 @@ export async function syncGiteaRepoEnhanced({
       throw new Error(`Repository ${repository.name} is not a mirror. Cannot sync.`);
     }
 
+    // ---- Smart backup strategy with force-push detection ----
+    const backupStrategy = resolveBackupStrategy(config);
+    let forcePushDetected = false;
+
+    if (backupStrategy !== "disabled") {
+      // Run force-push detection if the strategy requires it
+      // (skip when called from approve-sync to avoid re-blocking)
+      if (strategyNeedsDetection(backupStrategy) && !skipForcePushDetection) {
+        try {
+          const decryptedGithubToken = decryptedConfig.githubConfig?.token;
+          if (decryptedGithubToken) {
+            const fpOctokit = createGitHubClient(decryptedGithubToken);
+            const detectionResult = await detectForcePush({
+              giteaUrl: config.giteaConfig.url,
+              giteaToken: decryptedConfig.giteaConfig.token,
+              giteaOwner: repoOwner,
+              giteaRepo: repoName,
+              octokit: fpOctokit,
+              githubOwner: repository.owner,
+              githubRepo: repository.name,
+            });
+
+            forcePushDetected = detectionResult.detected;
+
+            if (detectionResult.skipped) {
+              console.log(
+                `[Sync] Force-push detection skipped for ${repository.name}: ${detectionResult.skipReason}`,
+              );
+            } else if (forcePushDetected) {
+              const branchNames = detectionResult.affectedBranches
+                .map((b) => `${b.name} (${b.reason})`)
+                .join(", ");
+              console.warn(
+                `[Sync] Force-push detected on ${repository.name}: ${branchNames}`,
+              );
+            }
+          } else {
+            console.log(
+              `[Sync] Skipping force-push detection for ${repository.name}: no GitHub token`,
+            );
+          }
+        } catch (detectionError) {
+          // Fail-open: detection errors should never block sync
+          console.warn(
+            `[Sync] Force-push detection failed for ${repository.name}, proceeding with sync: ${
+              detectionError instanceof Error ? detectionError.message : String(detectionError)
+            }`,
+          );
+        }
+      }
+
+      // Check if sync should be blocked (block-on-force-push mode)
+      if (shouldBlockSyncForStrategy(backupStrategy, forcePushDetected)) {
+        const branchInfo = `Force-push detected; sync blocked for manual approval.`;
+
+        await db
+          .update(repositories)
+          .set({
+            status: "pending-approval",
+            updatedAt: new Date(),
+            errorMessage: branchInfo,
+          })
+          .where(eq(repositories.id, repository.id!));
+
+        await createMirrorJob({
+          userId: config.userId,
+          repositoryId: repository.id,
+          repositoryName: repository.name,
+          message: `Sync blocked for ${repository.name}: force-push detected`,
+          details: branchInfo,
+          status: "pending-approval",
+        });
+
+        console.warn(`[Sync] Sync blocked for ${repository.name}: pending manual approval`);
+        return { blocked: true, reason: branchInfo };
+      }
+
+      // Create backup if strategy says so
+      if (shouldBackupForStrategy(backupStrategy, forcePushDetected)) {
+        const cloneUrl =
+          repoInfo.clone_url ||
+          `${config.giteaConfig.url.replace(/\/$/, "")}/${repoOwner}/${repoName}.git`;
+
+        try {
+          const backupResult = await createPreSyncBundleBackup({
+            config,
+            owner: repoOwner,
+            repoName,
+            cloneUrl,
+            force: true, // Strategy already decided to backup; skip legacy gate
+          });
+
+          await createMirrorJob({
+            userId: config.userId,
+            repositoryId: repository.id,
+            repositoryName: repository.name,
+            message: `Snapshot created for ${repository.name}`,
+            details: `Pre-sync snapshot created at ${backupResult.bundlePath}.`,
+            status: "syncing",
+          });
+        } catch (backupError) {
+          const errorMessage =
+            backupError instanceof Error ? backupError.message : String(backupError);
+
+          await createMirrorJob({
+            userId: config.userId,
+            repositoryId: repository.id,
+            repositoryName: repository.name,
+            message: `Snapshot failed for ${repository.name}`,
+            details: `Pre-sync snapshot failed: ${errorMessage}`,
+            status: "failed",
+          });
+
+          if (shouldBlockSyncOnBackupFailure(config)) {
+            await db
+              .update(repositories)
+              .set({
+                status: repoStatusEnum.parse("failed"),
+                updatedAt: new Date(),
+                errorMessage: `Snapshot failed; sync blocked to protect history. ${errorMessage}`,
+              })
+              .where(eq(repositories.id, repository.id!));
+
+            throw new Error(
+              `Snapshot failed; sync blocked to protect history. ${errorMessage}`,
+            );
+          }
+
+          console.warn(
+            `[Sync] Snapshot failed for ${repository.name}, continuing because blockSyncOnBackupFailure=false: ${errorMessage}`,
+          );
+        }
+      }
+    }
+
     // Update mirror interval if needed
+    // NOTE: Gitea/Forgejo's PATCH /repos/{owner}/{repo} API does not support
+    // updating mirror credentials (mirror_username/mirror_password). Repos that
+    // were originally migrated without credentials must be deleted and re-mirrored.
     if (config.giteaConfig?.mirrorInterval) {
       try {
-        console.log(`[Sync] Updating mirror interval for ${repository.name} to ${config.giteaConfig.mirrorInterval}`);
-        const updateUrl = `${config.giteaConfig.url}/api/v1/repos/${repoOwner}/${repository.name}`;
+        console.log(`[Sync] Updating mirror interval for ${repoOwner}/${repoName} to ${config.giteaConfig.mirrorInterval}`);
+        const updateUrl = `${config.giteaConfig.url}/api/v1/repos/${repoOwner}/${repoName}`;
         await httpPatch(updateUrl, {
           mirror_interval: config.giteaConfig.mirrorInterval,
         }, {
           Authorization: `token ${decryptedConfig.giteaConfig.token}`,
         });
-        console.log(`[Sync] Successfully updated mirror interval for ${repository.name}`);
+        console.log(`[Sync] Successfully updated mirror interval for ${repoOwner}/${repoName}`);
       } catch (updateError) {
-        console.warn(`[Sync] Failed to update mirror interval for ${repository.name}:`, updateError);
+        console.warn(`[Sync] Failed to update mirror interval for ${repoOwner}/${repoName}:`, updateError);
         // Continue with sync even if interval update fails
       }
     }
 
     // Perform the sync
-    const apiUrl = `${config.giteaConfig.url}/api/v1/repos/${repoOwner}/${repository.name}/mirror-sync`;
+    const apiUrl = `${config.giteaConfig.url}/api/v1/repos/${repoOwner}/${repoName}/mirror-sync`;
 
     try {
       const response = await httpPost(apiUrl, undefined, {
@@ -351,29 +597,27 @@ export async function syncGiteaRepoEnhanced({
         if (!decryptedConfig.githubConfig?.token) {
           return null;
         }
-        metadataOctokit = new Octokit({
-          auth: decryptedConfig.githubConfig.token,
-        });
+        metadataOctokit = createGitHubClient(decryptedConfig.githubConfig.token);
         return metadataOctokit;
       };
 
+      // Reconcile metadata on every sync (matches the release path).
+      // The underlying mirror* functions are idempotent: issues/PRs are
+      // matched via [GH-ISSUE #N] / [GH-PR #N] markers and PATCHed in
+      // place, labels are deduped by name, milestones by title.
       const shouldMirrorReleases =
         !!config.giteaConfig?.mirrorReleases && !skipMetadataForStarred;
       const shouldMirrorIssuesThisRun =
-        !!config.giteaConfig?.mirrorIssues &&
-        !skipMetadataForStarred;
+        !!config.giteaConfig?.mirrorIssues && !skipMetadataForStarred;
       const shouldMirrorPullRequests =
-        !!config.giteaConfig?.mirrorPullRequests &&
-        !skipMetadataForStarred;
+        !!config.giteaConfig?.mirrorPullRequests && !skipMetadataForStarred;
+      // Labels-only path; issues run already creates/reconciles labels.
       const shouldMirrorLabels =
         !!config.giteaConfig?.mirrorLabels &&
         !skipMetadataForStarred &&
-        !shouldMirrorIssuesThisRun &&
-        !metadataState.components.labels;
+        !shouldMirrorIssuesThisRun;
       const shouldMirrorMilestones =
-        !!config.giteaConfig?.mirrorMilestones &&
-        !skipMetadataForStarred &&
-        !metadataState.components.milestones;
+        !!config.giteaConfig?.mirrorMilestones && !skipMetadataForStarred;
 
       if (shouldMirrorReleases) {
         const octokit = ensureOctokit();
@@ -388,7 +632,7 @@ export async function syncGiteaRepoEnhanced({
               octokit,
               repository,
               giteaOwner: repoOwner,
-              giteaRepoName: repository.name,
+              giteaRepoName: repoName,
             });
             metadataState.components.releases = true;
             metadataUpdated = true;
@@ -420,7 +664,7 @@ export async function syncGiteaRepoEnhanced({
               octokit,
               repository,
               giteaOwner: repoOwner,
-              giteaRepoName: repository.name,
+              giteaRepoName: repoName,
             });
             metadataState.components.issues = true;
             metadataState.components.labels = true;
@@ -453,7 +697,7 @@ export async function syncGiteaRepoEnhanced({
               octokit,
               repository,
               giteaOwner: repoOwner,
-              giteaRepoName: repository.name,
+              giteaRepoName: repoName,
             });
             metadataState.components.pullRequests = true;
             metadataUpdated = true;
@@ -483,7 +727,7 @@ export async function syncGiteaRepoEnhanced({
               octokit,
               repository,
               giteaOwner: repoOwner,
-              giteaRepoName: repository.name,
+              giteaRepoName: repoName,
             });
             metadataState.components.labels = true;
             metadataUpdated = true;
@@ -500,13 +744,6 @@ export async function syncGiteaRepoEnhanced({
             );
           }
         }
-      } else if (
-        config.giteaConfig?.mirrorLabels &&
-        metadataState.components.labels
-      ) {
-        console.log(
-          `[Sync] Labels already mirrored for ${repository.name}; skipping`
-        );
       }
 
       if (shouldMirrorMilestones) {
@@ -522,7 +759,7 @@ export async function syncGiteaRepoEnhanced({
               octokit,
               repository,
               giteaOwner: repoOwner,
-              giteaRepoName: repository.name,
+              giteaRepoName: repoName,
             });
             metadataState.components.milestones = true;
             metadataUpdated = true;
@@ -539,13 +776,6 @@ export async function syncGiteaRepoEnhanced({
             );
           }
         }
-      } else if (
-        config.giteaConfig?.mirrorMilestones &&
-        metadataState.components.milestones
-      ) {
-        console.log(
-          `[Sync] Milestones already mirrored for ${repository.name}; skipping`
-        );
       }
 
       if (metadataUpdated) {
@@ -560,7 +790,7 @@ export async function syncGiteaRepoEnhanced({
           updatedAt: new Date(),
           lastMirrored: new Date(),
           errorMessage: null,
-          mirroredLocation: `${repoOwner}/${repository.name}`,
+          mirroredLocation: `${repoOwner}/${repoName}`,
           metadata: metadataUpdated
             ? serializeRepositoryMetadataState(metadataState)
             : repository.metadata ?? null,
@@ -572,7 +802,7 @@ export async function syncGiteaRepoEnhanced({
         repositoryId: repository.id,
         repositoryName: repository.name,
         message: `Sync requested for repository: ${repository.name}`,
-        details: `Mirror sync was requested for ${repository.name}. Gitea/Forgejo performs the actual pull asynchronously; check remote logs for pull errors.`,
+        details: `Mirror sync was requested for ${repoOwner}/${repoName}.`,
         status: "synced",
       });
 

src/lib/gitea-issue-dedup-on-retry.test.ts

@@ -0,0 +1,282 @@
+/**
+ * Regression test for duplicate-issue creation on retry-after-deadlock.
+ *
+ * `mirrorGitRepoIssuesToGitea` pre-fetches all existing Gitea issues
+ * into `giteaIssueByGitHubNumber` ONCE at function entry, then iterates
+ * per-issue via `processWithRetry`. Each iteration uses the cached map
+ * to decide CREATE vs PATCH.
+ *
+ * The bug: when Gitea's CreateIssue handler commits the issue insert
+ * in one transaction and then deadlocks on the addLabel / repository
+ * counter update in a second transaction, the issue row is committed
+ * and visible — but the in-memory map is never refreshed between
+ * retries. So `processWithRetry` would call the callback again,
+ * `existingIssue` is still `undefined` from the stale map, and a fresh
+ * `httpPost` creates a duplicate.
+ *
+ * Reproduces deterministically on MySQL (1213/40001) and PostgreSQL
+ * (40P01). SQLite escapes because writes serialize globally.
+ *
+ * This test asserts on the *structure* of the source rather than
+ * invoking the function, because behavioral tests for the issue-mirror
+ * pipeline require heavy module mocks that pollute other test files
+ * (bun's mock.module is process-wide). See
+ * `gitea-mirror-failure-recovery.test.ts` for the same convention.
+ *
+ * The two structural guarantees this test enforces:
+ *   (1) Before the create-issue httpPost call, the code performs a
+ *       defensive recheck via httpGet that queries Gitea by
+ *       `[GH-ISSUE #N]` title marker — handles "previous attempt
+ *       committed the issue then threw" scenarios.
+ *   (2) After a successful httpPost create, the new issue is written
+ *       back into `giteaIssueByGitHubNumber` — handles "this attempt
+ *       created the issue, but a later step in the same callback
+ *       (e.g. comment sync) throws and triggers another retry"
+ *       scenarios.
+ */
+import { describe, test, expect } from "bun:test";
+import { readFileSync } from "node:fs";
+import { join } from "node:path";
+
+const SOURCE = readFileSync(join(import.meta.dir, "gitea.ts"), "utf8");
+
+/**
+ * Locate the body of a function declaration by name. Walks from the
+ * declaration, balances parens to skip the parameter list (which can
+ * contain destructured object literals with their own braces), then
+ * finds the body's opening brace and its matching close.
+ *
+ * Same helper as in `gitea-mirror-failure-recovery.test.ts`; kept
+ * local to keep this test file self-contained.
+ */
+function extractFunctionBody(source: string, declarationStart: RegExp): string {
+  const match = source.match(declarationStart);
+  if (!match) {
+    throw new Error(`Could not locate declaration ${declarationStart}`);
+  }
+  let i = match.index! + match[0].length;
+  while (i < source.length && source[i] !== "(") i++;
+  if (source[i] !== "(") {
+    throw new Error(`No '(' after ${declarationStart}`);
+  }
+  let parenDepth = 0;
+  for (; i < source.length; i++) {
+    if (source[i] === "(") parenDepth++;
+    else if (source[i] === ")") {
+      parenDepth--;
+      if (parenDepth === 0) {
+        i++;
+        break;
+      }
+    }
+  }
+  while (i < source.length && source[i] !== "{") i++;
+  if (source[i] !== "{") {
+    throw new Error(`No body '{' for ${declarationStart}`);
+  }
+  let braceDepth = 0;
+  const startIdx = i;
+  for (; i < source.length; i++) {
+    if (source[i] === "{") braceDepth++;
+    else if (source[i] === "}") {
+      braceDepth--;
+      if (braceDepth === 0) {
+        return source.slice(startIdx, i + 1);
+      }
+    }
+  }
+  throw new Error(`Unterminated body for ${declarationStart}`);
+}
+
+describe("issue dedup on retry-after-deadlock", () => {
+  const body = extractFunctionBody(
+    SOURCE,
+    /export const mirrorGitRepoIssuesToGitea = async\b/
+  );
+
+  test("body contains the per-issue create branch we expect to guard", () => {
+    // Sanity: make sure the test is looking at the right code path.
+    // If these strings disappear due to a refactor, this test should
+    // fail loudly so a human reviews whether the dedup guarantees
+    // still hold in the new shape.
+    expect(
+      body.includes(
+        "giteaIssueByGitHubNumber.get(issue.number)"
+      ),
+      "expected the per-issue lookup against giteaIssueByGitHubNumber"
+    ).toBe(true);
+    expect(
+      body.match(/await httpPost\(\s*`\$\{config\.giteaConfig!\.url\}\/api\/v1\/repos\/\$\{giteaOwner\}\/\$\{repoName\}\/issues`/),
+      "expected the create-issue httpPost call"
+    ).toBeTruthy();
+  });
+
+  test("defensive recheck via httpGet runs BEFORE the create httpPost", () => {
+    // The recheck must query Gitea by [GH-ISSUE #N] marker to catch
+    // the partial-commit case. Without it, a deadlock-after-insert
+    // returns 5xx, processWithRetry re-runs the callback, and the
+    // create call produces a duplicate row.
+    const recheckIdx = body.search(
+      /await httpGet\([^)]*\[GH-ISSUE #\$\{issue\.number\}\]/
+    );
+    expect(
+      recheckIdx,
+      "defensive recheck via httpGet using [GH-ISSUE #N] marker must exist"
+    ).toBeGreaterThanOrEqual(0);
+
+    // The recheck must come before the create httpPost in source order.
+    // The first httpPost on the .../issues endpoint inside this
+    // function body is the create call; we anchor against it.
+    const createIdx = body.search(
+      /await httpPost\(\s*`\$\{config\.giteaConfig!\.url\}\/api\/v1\/repos\/\$\{giteaOwner\}\/\$\{repoName\}\/issues`/
+    );
+    expect(createIdx, "create httpPost call must exist").toBeGreaterThanOrEqual(0);
+
+    expect(
+      recheckIdx,
+      "the recheck must run BEFORE the create call so it can short-circuit on partial-commit duplicates"
+    ).toBeLessThan(createIdx);
+  });
+
+  test("recheck hit short-circuits via PATCH and updates the cache", () => {
+    // When the recheck finds a hit (i.e. a previous failed attempt
+    // already created this issue), the code should:
+    //   - cache the hit into giteaIssueByGitHubNumber so subsequent
+    //     retries within this run also find it
+    //   - go down the PATCH path (httpPatch) instead of httpPost
+    //   - log a recognisable line so operators can spot recovery
+    expect(
+      body.includes(
+        "giteaIssueByGitHubNumber.set(issue.number, recheckHit)"
+      ) ||
+        body.match(/giteaIssueByGitHubNumber\.set\(\s*issue\.number\s*,\s*recheckHit/),
+      "recheck hit must be written back into giteaIssueByGitHubNumber"
+    ).toBeTruthy();
+
+    expect(
+      body.match(/Recovered orphan from prior failed attempt/i),
+      "a log line should make the recovery path visible in operator logs"
+    ).toBeTruthy();
+  });
+
+  test("pre-fetch issues pagination uses Link header (not short-page heuristic)", () => {
+    // The previous `if (pageIssues.length < issuesPerPage) break;`
+    // heuristic was wrong in both directions:
+    //   - Gitea caps response size at `[api].MAX_RESPONSE_ITEMS`
+    //     (default 50), typically lower than `issuesPerPage` (100),
+    //     so the very first page already looks "short" and
+    //     pagination terminated after 50 items. Every issue past
+    //     that was misclassified as new and duplicated on every sync.
+    //   - Naive removal of that break, relying only on "break on
+    //     empty page", can loop forever because some Gitea endpoints
+    //     return the same data on every page when asked for a page
+    //     past the actual end (instead of returning []).
+    //
+    // The correct fix is to use the Link header (RFC 5988): if
+    // `rel="next"` is absent, we're done.
+    //
+    // This test asserts:
+    //   - the broken short-page check is gone
+    //   - the existing-issues loop checks the Link header for next
+    const issuesPaginationRegion = body.substring(
+      body.indexOf("existingGiteaIssues.push"),
+      body.indexOf("issuesPage += 1") + 30
+    );
+    expect(
+      issuesPaginationRegion,
+      "issues pagination region should be present"
+    ).not.toBe("");
+    expect(
+      /\bpageIssues\.length\s*<\s*issuesPerPage\b/.test(issuesPaginationRegion),
+      "the short-page break (pageIssues.length < issuesPerPage) must be removed"
+    ).toBe(false);
+    expect(
+      /existingIssuesRes\.headers\.get\(\s*["']link["']\s*\)/.test(
+        issuesPaginationRegion
+      ) && /rel="next"/.test(issuesPaginationRegion),
+      "the issues pagination loop must use the Link header (rel=\"next\") " +
+        "to decide whether to fetch the next page"
+    ).toBe(true);
+  });
+
+  test("per-issue comments pagination also uses Link header (not short-page heuristic)", () => {
+    // Same correctness concerns as issues pagination above. The per-
+    // issue comments endpoint is subject to the same Gitea page-size
+    // cap, and naive empty-page detection has the same risk.
+    expect(
+      /\bpageComments\.length\s*<\s*commentsPerPage\b/.test(body),
+      "the short-page break (pageComments.length < commentsPerPage) must be removed"
+    ).toBe(false);
+    // Look only at the comments-fetch region (not the whole file) so
+    // a future caller using a different response variable name in
+    // another place won't false-positive this assertion.
+    const commentsRegion = body.substring(
+      body.indexOf("existingComments.push"),
+      body.indexOf("commentsPage += 1") + 30
+    );
+    expect(
+      commentsRegion,
+      "comments pagination region should be present"
+    ).not.toBe("");
+    expect(
+      /existingCommentsRes\.headers\.get\(\s*["']link["']\s*\)/.test(
+        commentsRegion
+      ) && /rel="next"/.test(commentsRegion),
+      "the comments pagination loop must use the Link header (rel=\"next\") " +
+        "to decide whether to fetch the next page"
+    ).toBe(true);
+  });
+
+  describe("PR mirror has the same guarantees", () => {
+    // mirrorGitRepoPullRequestsToGitea has parallel structure:
+    // - pre-fetches existing Gitea "issues that are mirrored PRs",
+    //   keyed by `[PR #N]` marker in title
+    // - per-PR callback decides PATCH vs CREATE
+    // - same Gitea-side pagination cap and deadlock-after-commit
+    //   risks apply
+    // The fix mirrors gitea-issues here.
+    const prBody = extractFunctionBody(
+      SOURCE,
+      /export async function mirrorGitRepoPullRequestsToGitea\b/
+    );
+
+    test("PR pre-fetch pagination uses Link header", () => {
+      expect(
+        /\bpageIssues\.length\s*<\s*prIssuesPerPage\b/.test(prBody),
+        "the short-page break (pageIssues.length < prIssuesPerPage) must be removed"
+      ).toBe(false);
+      // The PR pre-fetch reuses the existingIssuesRes variable name
+      expect(
+        /existingIssuesRes\.headers\.get\(\s*["']link["']\s*\)/.test(prBody) &&
+          /rel="next"/.test(prBody),
+        "the PR pre-fetch loop must use the Link header (rel=\"next\")"
+      ).toBe(true);
+    });
+
+    test("PR create path defensively rechecks via [PR #N] before httpPost", () => {
+      // Both the enriched and basic-fallback create paths must have
+      // a recheck so partial-commit retries don't duplicate the PR.
+      const rechecks =
+        prBody.match(/Recovered orphan from prior failed attempt for PR/g) ||
+        [];
+      expect(
+        rechecks.length,
+        "expected at least two 'Recovered orphan' log lines " +
+          "(one for the enriched create path, one for the basic-fallback path)"
+      ).toBeGreaterThanOrEqual(2);
+    });
+  });
+
+  test("successful create caches the new issue into the dedup map", () => {
+    // Without this, a retry triggered by a *later* step in the same
+    // per-issue callback (e.g. comment sync throwing) would re-enter
+    // the create path on the next attempt — same root duplication
+    // pattern, different trigger.
+    expect(
+      body.match(
+        /giteaIssueByGitHubNumber\.set\(\s*issue\.number\s*,\s*createdIssue\.data\s*\)/
+      ),
+      "after a successful create, the new issue must be stored in giteaIssueByGitHubNumber"
+    ).toBeTruthy();
+  });
+});

src/lib/gitea-mirror-failure-recovery.test.ts

@@ -0,0 +1,132 @@
+/**
+ * Regression test for issue #268.
+ *
+ * `let migrateSucceeded = false;` was declared *inside* the try block
+ * of mirrorGithubRepoToGitea and mirrorGitHubRepoToGiteaOrg, but the
+ * catch block referenced it. `let` is block-scoped to the try, so any
+ * error inside try made the catch crash with `ReferenceError:
+ * migrateSucceeded is not defined` before reaching the DB update that
+ * marks the repo "failed". Result: repos stuck in "mirroring" forever
+ * with no entry in the activity log (see issue logs).
+ *
+ * This test asserts the declaration is hoisted above the try block in
+ * both functions. It deliberately reads the source rather than calling
+ * the functions, because behavioral tests for these functions require
+ * heavy module mocks that pollute other test files (bun's mock.module
+ * is process-wide and persists across files).
+ */
+import { describe, test, expect } from "bun:test";
+import { readFileSync } from "node:fs";
+import { join } from "node:path";
+
+const SOURCE = readFileSync(
+  join(import.meta.dir, "gitea.ts"),
+  "utf8"
+);
+
+/**
+ * Locate the body of a function declaration by name. Walks from the
+ * declaration, balances parens to skip the parameter list (which can
+ * contain destructured object literals with their own braces), then
+ * finds the body's opening brace and its matching close.
+ */
+function extractFunctionBody(source: string, declarationStart: RegExp): string {
+  const match = source.match(declarationStart);
+  if (!match) {
+    throw new Error(`Could not locate declaration ${declarationStart}`);
+  }
+  let i = match.index! + match[0].length;
+  // Skip whitespace until the opening paren of the parameter list.
+  while (i < source.length && source[i] !== "(") i++;
+  if (source[i] !== "(") {
+    throw new Error(`No '(' after ${declarationStart}`);
+  }
+  // Balance parens to find the end of the parameter list. Braces inside
+  // the parameter list (e.g. destructured `{ foo, bar }`) are allowed
+  // and ignored.
+  let parenDepth = 0;
+  for (; i < source.length; i++) {
+    if (source[i] === "(") parenDepth++;
+    else if (source[i] === ")") {
+      parenDepth--;
+      if (parenDepth === 0) {
+        i++;
+        break;
+      }
+    }
+  }
+  // Skip return-type annotation, => arrow, whitespace, until the body's `{`.
+  while (i < source.length && source[i] !== "{") i++;
+  if (source[i] !== "{") {
+    throw new Error(`No body '{' for ${declarationStart}`);
+  }
+  // Balance braces for the body.
+  let braceDepth = 0;
+  const startIdx = i;
+  for (; i < source.length; i++) {
+    if (source[i] === "{") braceDepth++;
+    else if (source[i] === "}") {
+      braceDepth--;
+      if (braceDepth === 0) {
+        return source.slice(startIdx, i + 1);
+      }
+    }
+  }
+  throw new Error(`Unterminated body for ${declarationStart}`);
+}
+
+/**
+ * Confirm that within a function body, the first `let migrateSucceeded`
+ * declaration occurs BEFORE the function's outermost `try {`.
+ *
+ * If the declaration is inside the try block, the catch block can't see
+ * it (ReferenceError in production = repo stuck mirroring).
+ */
+function assertMigrateSucceededDeclaredBeforeTry(body: string, label: string) {
+  const declIdx = body.indexOf("let migrateSucceeded");
+  expect(declIdx, `${label}: 'let migrateSucceeded' should exist`).toBeGreaterThanOrEqual(0);
+
+  // The function's outermost try is the first standalone `try {` in
+  // the body — assignments and inner try/catches don't share its name.
+  const tryIdx = body.search(/\btry\s*\{/);
+  expect(tryIdx, `${label}: outermost 'try {' should exist`).toBeGreaterThanOrEqual(0);
+
+  expect(
+    declIdx,
+    `${label}: 'let migrateSucceeded' must be declared BEFORE the try block ` +
+      `so the catch block can read it. If declared inside try, it's block-scoped ` +
+      `and the catch will throw ReferenceError, leaving repos stuck in 'mirroring'. ` +
+      `See issue #268.`
+  ).toBeLessThan(tryIdx);
+
+  // And it should still be assigned to true after the migrate call —
+  // otherwise the catch can't tell whether to clear mirroredLocation.
+  expect(
+    body.includes("migrateSucceeded = true"),
+    `${label}: 'migrateSucceeded = true' assignment should exist after the migrate call`
+  ).toBe(true);
+
+  // And the catch must read it.
+  expect(
+    body.includes("if (!migrateSucceeded)"),
+    `${label}: catch block should read 'migrateSucceeded' to decide whether to clear mirroredLocation`
+  ).toBe(true);
+}
+
+describe("issue #268 — migrateSucceeded scoping regression", () => {
+  test("mirrorGithubRepoToGitea declares migrateSucceeded outside try", () => {
+    const body = extractFunctionBody(
+      SOURCE,
+      /export const mirrorGithubRepoToGitea = async\b/
+    );
+    assertMigrateSucceededDeclaredBeforeTry(body, "mirrorGithubRepoToGitea");
+  });
+
+  test("mirrorGitHubRepoToGiteaOrg declares migrateSucceeded outside try", () => {
+    const body = extractFunctionBody(
+      SOURCE,
+      /export async function mirrorGitHubRepoToGiteaOrg\b/
+    );
+    assertMigrateSucceededDeclaredBeforeTry(body, "mirrorGitHubRepoToGiteaOrg");
+  });
+});

src/lib/gitea-starred-repos.test.ts

@@ -24,9 +24,14 @@ mock.module("@/lib/db", () => {
         values: mock(() => Promise.resolve())
       }))
     },
+    users: {},
+    configs: {},
     repositories: {},
     organizations: {},
-    events: {}
+    events: {},
+    mirrorJobs: {},
+    accounts: {},
+    sessions: {},
   };
 });
 
@@ -59,10 +64,16 @@ const mockGetOrCreateGiteaOrg = mock(async ({ orgName, config }: any) => {
 
 const mockMirrorGitHubOrgRepoToGiteaOrg = mock(async () => {});
 const mockIsRepoPresentInGitea = mock(async () => false);
+const mockMirrorGithubRepoToGitea = mock(async () => {});
+const mockGetGiteaRepoOwnerAsync = mock(async () => "starred");
+const mockGetGiteaRepoOwner = mock(() => "starred");
 
 mock.module("./gitea", () => ({
   getOrCreateGiteaOrg: mockGetOrCreateGiteaOrg,
   mirrorGitHubOrgRepoToGiteaOrg: mockMirrorGitHubOrgRepoToGiteaOrg,
+  mirrorGithubRepoToGitea: mockMirrorGithubRepoToGitea,
+  getGiteaRepoOwner: mockGetGiteaRepoOwner,
+  getGiteaRepoOwnerAsync: mockGetGiteaRepoOwnerAsync,
   isRepoPresentInGitea: mockIsRepoPresentInGitea
 }));
 
@@ -226,4 +237,4 @@ describe("Starred Repository Error Handling", () => {
     });
   });
 
-});
+});

src/lib/gitea-url.test.ts

@@ -0,0 +1,45 @@
+import { describe, expect, it } from "bun:test";
+import { buildGiteaWebUrl, getGiteaWebBaseUrl } from "@/lib/gitea-url";
+
+describe("getGiteaWebBaseUrl", () => {
+  it("prefers externalUrl when both urls are present", () => {
+    const baseUrl = getGiteaWebBaseUrl({
+      url: "http://gitea:3000",
+      externalUrl: "https://git.example.com",
+    });
+
+    expect(baseUrl).toBe("https://git.example.com");
+  });
+
+  it("falls back to url when externalUrl is missing", () => {
+    const baseUrl = getGiteaWebBaseUrl({
+      url: "http://gitea:3000",
+    });
+
+    expect(baseUrl).toBe("http://gitea:3000");
+  });
+
+  it("trims a trailing slash", () => {
+    const baseUrl = getGiteaWebBaseUrl({
+      externalUrl: "https://git.example.com/",
+    });
+
+    expect(baseUrl).toBe("https://git.example.com");
+  });
+});
+
+describe("buildGiteaWebUrl", () => {
+  it("builds a full repository url and removes leading path slashes", () => {
+    const url = buildGiteaWebUrl(
+      { externalUrl: "https://git.example.com/" },
+      "/org/repo"
+    );
+
+    expect(url).toBe("https://git.example.com/org/repo");
+  });
+
+  it("returns null when no gitea url is configured", () => {
+    const url = buildGiteaWebUrl({}, "org/repo");
+    expect(url).toBeNull();
+  });
+});

src/lib/gitea-url.ts

@@ -0,0 +1,28 @@
+interface GiteaUrlConfig {
+  url?: string | null;
+  externalUrl?: string | null;
+}
+
+export function getGiteaWebBaseUrl(
+  config?: GiteaUrlConfig | null
+): string | null {
+  const rawBaseUrl = config?.externalUrl || config?.url;
+  if (!rawBaseUrl) {
+    return null;
+  }
+
+  return rawBaseUrl.endsWith("/") ? rawBaseUrl.slice(0, -1) : rawBaseUrl;
+}
+
+export function buildGiteaWebUrl(
+  config: GiteaUrlConfig | null | undefined,
+  path: string
+): string | null {
+  const baseUrl = getGiteaWebBaseUrl(config);
+  if (!baseUrl) {
+    return null;
+  }
+
+  const normalizedPath = path.replace(/^\/+/, "");
+  return normalizedPath ? `${baseUrl}/${normalizedPath}` : baseUrl;
+}

src/lib/gitea.test.ts

@@ -27,8 +27,14 @@ mock.module("@/lib/db", () => {
         })
       })
     },
+    users: {},
+    configs: {},
     repositories: {},
-    organizations: {}
+    organizations: {},
+    mirrorJobs: {},
+    events: {},
+    accounts: {},
+    sessions: {},
   };
 });
 
@@ -55,8 +61,61 @@ mock.module("@/lib/http-client", () => {
 
 // Mock the gitea module itself
 mock.module("./gitea", () => {
+  const mockGetGiteaRepoOwner = mock(({ config, repository }: any) => {
+    if (repository?.isStarred && config?.githubConfig?.starredReposMode === "preserve-owner") {
+      return repository.organization || repository.owner;
+    }
+    if (repository?.isStarred) {
+      return config?.githubConfig?.starredReposOrg || "starred";
+    }
+
+    const mirrorStrategy =
+      config?.githubConfig?.mirrorStrategy ||
+      (config?.giteaConfig?.preserveOrgStructure ? "preserve" : "flat-user");
+    const configuredGitHubOwner =
+      (config?.githubConfig?.owner || config?.githubConfig?.username || "")
+        .trim()
+        .toLowerCase();
+    const repoOwner = repository?.owner?.trim().toLowerCase();
+
+    switch (mirrorStrategy) {
+      case "preserve":
+        if (repository?.organization) {
+          return repository.organization;
+        }
+        if (configuredGitHubOwner && repoOwner && repoOwner !== configuredGitHubOwner) {
+          return repository.owner;
+        }
+        return config?.giteaConfig?.defaultOwner || "giteauser";
+      case "single-org":
+        return config?.giteaConfig?.organization || config?.giteaConfig?.defaultOwner || "giteauser";
+      case "mixed":
+        if (repository?.organization) return repository.organization;
+        return config?.giteaConfig?.organization || config?.giteaConfig?.defaultOwner || "giteauser";
+      case "flat-user":
+      default:
+        return config?.giteaConfig?.defaultOwner || "giteauser";
+    }
+  });
+  const mockGetGiteaRepoOwnerAsync = mock(async ({ config, repository }: any) => {
+    if (repository?.isStarred && config?.githubConfig?.starredReposMode === "preserve-owner") {
+      return repository.organization || repository.owner;
+    }
+
+    if (repository?.destinationOrg) {
+      return repository.destinationOrg;
+    }
+
+    if (repository?.organization && mockDbSelectResult[0]?.destinationOrg) {
+      return mockDbSelectResult[0].destinationOrg;
+    }
+
+    return mockGetGiteaRepoOwner({ config, repository });
+  });
   return {
     isRepoPresentInGitea: mockIsRepoPresentInGitea,
+    getGiteaRepoOwner: mockGetGiteaRepoOwner,
+    getGiteaRepoOwnerAsync: mockGetGiteaRepoOwnerAsync,
     mirrorGithubRepoToGitea: mock(async () => {}),
     mirrorGitHubOrgRepoToGiteaOrg: mock(async () => {})
   };
@@ -328,6 +387,7 @@ describe("Gitea Repository Mirroring", () => {
 describe("getGiteaRepoOwner - Organization Override Tests", () => {
   const baseConfig: Partial<Config> = {
     githubConfig: {
+      owner: "testuser",
       username: "testuser",
       token: "token",
       preserveOrgStructure: false,
@@ -436,6 +496,18 @@ describe("getGiteaRepoOwner - Organization Override Tests", () => {
     expect(result).toBe("giteauser");
   });
 
+  test("preserve strategy: personal repos owned by another user keep source owner namespace", () => {
+    const repo = {
+      ...baseRepo,
+      owner: "nice-user",
+      fullName: "nice-user/test-repo",
+      organization: undefined,
+      isForked: true,
+    };
+    const result = getGiteaRepoOwner({ config: baseConfig, repository: repo });
+    expect(result).toBe("nice-user");
+  });
+
   test("preserve strategy: org repos go to same org name", () => {
     const repo = { ...baseRepo, organization: "myorg" };
     const result = getGiteaRepoOwner({ config: baseConfig, repository: repo });
@@ -541,4 +613,26 @@ describe("getGiteaRepoOwner - Organization Override Tests", () => {
 
     expect(result).toBe("FOO");
   });
+
+  test("getGiteaRepoOwnerAsync preserves external personal owner for preserve strategy", async () => {
+    const configWithUser: Partial<Config> = {
+      ...baseConfig,
+      userId: "user-id",
+    };
+
+    const repo = {
+      ...baseRepo,
+      owner: "nice-user",
+      fullName: "nice-user/test-repo",
+      organization: undefined,
+      isForked: true,
+    };
+
+    const result = await getGiteaRepoOwnerAsync({
+      config: configWithUser,
+      repository: repo,
+    });
+
+    expect(result).toBe("nice-user");
+  });
 });

src/lib/github-affiliation.test.ts

@@ -0,0 +1,100 @@
+import { describe, expect, test, mock } from "bun:test";
+import { getGithubRepositories } from "@/lib/github";
+
+function makeRepo() {
+  return {
+    name: "demo",
+    full_name: "octo/demo",
+    html_url: "https://github.com/octo/demo",
+    clone_url: "https://github.com/octo/demo.git",
+    owner: { login: "octo", type: "User" },
+    private: false,
+    fork: false,
+    has_issues: true,
+    archived: false,
+    size: 1,
+    language: "TypeScript",
+    description: "",
+    default_branch: "main",
+    visibility: "public",
+    disabled: false,
+    created_at: "2024-01-01T00:00:00Z",
+    updated_at: "2024-01-02T00:00:00Z",
+  };
+}
+
+function makeOctokit() {
+  let captured: Record<string, unknown> | null = null;
+  const paginate = mock(async (_method: unknown, options?: Record<string, unknown>) => {
+    captured = options ?? null;
+    return [makeRepo()];
+  });
+  return {
+    octokit: {
+      paginate,
+      repos: { listForAuthenticatedUser: () => {} },
+    } as any,
+    getCaptured: () => captured,
+  };
+}
+
+describe("getGithubRepositories - affiliation", () => {
+  test("defaults to owner+collaborator+organization_member when field is unset (backward compat)", async () => {
+    const { octokit, getCaptured } = makeOctokit();
+    await getGithubRepositories({ octokit, config: { githubConfig: { owner: "octo" } as any } });
+    expect(getCaptured()?.affiliation).toBe("owner,collaborator,organization_member");
+  });
+
+  test("uses owner+organization_member when includeCollaboratorRepos is false", async () => {
+    const { octokit, getCaptured } = makeOctokit();
+    await getGithubRepositories({
+      octokit,
+      config: { githubConfig: { owner: "octo", includeCollaboratorRepos: false } as any },
+    });
+    expect(getCaptured()?.affiliation).toBe("owner,organization_member");
+  });
+
+  test("uses owner+collaborator+organization_member when includeCollaboratorRepos is true", async () => {
+    const { octokit, getCaptured } = makeOctokit();
+    await getGithubRepositories({
+      octokit,
+      config: { githubConfig: { owner: "octo", includeCollaboratorRepos: true } as any },
+    });
+    expect(getCaptured()?.affiliation).toBe("owner,collaborator,organization_member");
+  });
+
+  test("override forces owner+collaborator+organization_member regardless of config (used by cleanup)", async () => {
+    const { octokit, getCaptured } = makeOctokit();
+    await getGithubRepositories({
+      octokit,
+      config: { githubConfig: { owner: "octo", includeCollaboratorRepos: false } as any },
+      includeCollaboratorReposOverride: true,
+    });
+    expect(getCaptured()?.affiliation).toBe("owner,collaborator,organization_member");
+  });
+
+  test("always includes organization_member (regression guard for org-repo invisibility)", async () => {
+    const cases: Array<{ includeCollab?: boolean; override?: boolean }> = [
+      {},
+      { includeCollab: true },
+      { includeCollab: false },
+      { override: true },
+      { includeCollab: false, override: true },
+    ];
+    for (const c of cases) {
+      const { octokit, getCaptured } = makeOctokit();
+      await getGithubRepositories({
+        octokit,
+        config: {
+          githubConfig: {
+            owner: "octo",
+            ...(c.includeCollab !== undefined && { includeCollaboratorRepos: c.includeCollab }),
+          } as any,
+        },
+        ...(c.override !== undefined && { includeCollaboratorReposOverride: c.override }),
+      });
+      const aff = String(getCaptured()?.affiliation ?? "");
+      expect(aff.split(",")).toContain("organization_member");
+    }
+  });
+});

src/lib/github-star-lists.test.ts

@@ -0,0 +1,319 @@
+import { describe, expect, test, mock } from "bun:test";
+import {
+  getGithubStarredListNames,
+  getGithubStarredRepositories,
+} from "@/lib/github";
+
+function makeRestStarredRepo(overrides: Record<string, unknown> = {}) {
+  return {
+    name: "demo",
+    full_name: "acme/demo",
+    html_url: "https://github.com/acme/demo",
+    clone_url: "https://github.com/acme/demo.git",
+    owner: {
+      login: "acme",
+      type: "Organization",
+    },
+    private: false,
+    fork: false,
+    has_issues: true,
+    archived: false,
+    size: 123,
+    language: "TypeScript",
+    description: "Demo",
+    default_branch: "main",
+    visibility: "public",
+    disabled: false,
+    created_at: "2024-01-01T00:00:00Z",
+    updated_at: "2024-01-02T00:00:00Z",
+    ...overrides,
+  };
+}
+
+function makeGraphqlListRepo(
+  nameWithOwner: string,
+  overrides: Record<string, unknown> = {},
+) {
+  const [owner, name] = nameWithOwner.split("/");
+  return {
+    __typename: "Repository" as const,
+    name,
+    nameWithOwner,
+    url: `https://github.com/${nameWithOwner}`,
+    sshUrl: `git@github.com:${nameWithOwner}.git`,
+    isPrivate: false,
+    isFork: false,
+    isArchived: false,
+    isDisabled: false,
+    hasIssuesEnabled: true,
+    diskUsage: 456,
+    description: `${name} repo`,
+    defaultBranchRef: { name: "main" },
+    visibility: "PUBLIC" as const,
+    updatedAt: "2024-01-02T00:00:00Z",
+    createdAt: "2024-01-01T00:00:00Z",
+    owner: {
+      __typename: "Organization" as const,
+      login: owner,
+    },
+    primaryLanguage: { name: "TypeScript" },
+    ...overrides,
+  };
+}
+
+describe("GitHub starred lists support", () => {
+  test("falls back to REST starred endpoint when no lists are configured", async () => {
+    const paginate = mock(async () => [makeRestStarredRepo()]);
+    const graphql = mock(async () => {
+      throw new Error("GraphQL should not be used in REST fallback path");
+    });
+
+    const octokit = {
+      paginate,
+      graphql,
+      activity: {
+        listReposStarredByAuthenticatedUser: () => {},
+      },
+    } as any;
+
+    const repos = await getGithubStarredRepositories({
+      octokit,
+      config: { githubConfig: { starredLists: [] } } as any,
+    });
+
+    expect(repos).toHaveLength(1);
+    expect(repos[0].fullName).toBe("acme/demo");
+    expect(repos[0].isStarred).toBe(true);
+    expect(paginate).toHaveBeenCalledTimes(1);
+    expect(graphql).toHaveBeenCalledTimes(0);
+  });
+
+  test("filters starred repositories by configured list names and de-duplicates", async () => {
+    const paginate = mock(async () => []);
+    const graphql = mock(async (_query: string, variables?: Record<string, unknown>) => {
+      if (!variables || !("listId" in variables)) {
+        return {
+          viewer: {
+            lists: {
+              nodes: [
+                null,
+                { id: "list-1", name: "HomeLab" },
+                { id: "list-2", name: "DotTools" },
+                { id: "list-3", name: "Ideas" },
+              ],
+              pageInfo: { hasNextPage: false, endCursor: null },
+            },
+          },
+        };
+      }
+
+      if (variables.listId === "list-1") {
+        return {
+          node: {
+            items: {
+              nodes: [
+                null,
+                makeGraphqlListRepo("acme/repo-a"),
+                makeGraphqlListRepo("acme/repo-b"),
+              ],
+              pageInfo: { hasNextPage: false, endCursor: null },
+            },
+          },
+        };
+      }
+
+      return {
+        node: {
+          items: {
+            nodes: [
+              makeGraphqlListRepo("acme/repo-b"),
+              makeGraphqlListRepo("acme/repo-c"),
+            ],
+            pageInfo: { hasNextPage: false, endCursor: null },
+          },
+        },
+      };
+    });
+
+    const octokit = {
+      paginate,
+      graphql,
+      activity: {
+        listReposStarredByAuthenticatedUser: () => {},
+      },
+    } as any;
+
+    const repos = await getGithubStarredRepositories({
+      octokit,
+      config: {
+        githubConfig: {
+          starredLists: ["homelab", "dottools"],
+        },
+      } as any,
+    });
+
+    expect(repos).toHaveLength(3);
+    expect(repos.map((repo) => repo.fullName).sort()).toEqual([
+      "acme/repo-a",
+      "acme/repo-b",
+      "acme/repo-c",
+    ]);
+    expect(paginate).toHaveBeenCalledTimes(0);
+  });
+
+  test("matches configured list names even when separators differ", async () => {
+    const paginate = mock(async () => []);
+    const graphql = mock(async (_query: string, variables?: Record<string, unknown>) => {
+      if (!variables || !("listId" in variables)) {
+        return {
+          viewer: {
+            lists: {
+              nodes: [
+                { id: "list-1", name: "UI Frontend" },
+                { id: "list-2", name: "Email | Self - Hosted" },
+                { id: "list-3", name: "PaaS | Hosting | Deploy" },
+              ],
+              pageInfo: { hasNextPage: false, endCursor: null },
+            },
+          },
+        };
+      }
+
+      if (variables.listId === "list-1") {
+        return {
+          node: {
+            items: {
+              nodes: [makeGraphqlListRepo("acme/ui-app")],
+              pageInfo: { hasNextPage: false, endCursor: null },
+            },
+          },
+        };
+      }
+
+      if (variables.listId === "list-2") {
+        return {
+          node: {
+            items: {
+              nodes: [makeGraphqlListRepo("acme/email-app")],
+              pageInfo: { hasNextPage: false, endCursor: null },
+            },
+          },
+        };
+      }
+
+      return {
+        node: {
+          items: {
+            nodes: [makeGraphqlListRepo("acme/paas-app")],
+            pageInfo: { hasNextPage: false, endCursor: null },
+          },
+        },
+      };
+    });
+
+    const octokit = {
+      paginate,
+      graphql,
+      activity: {
+        listReposStarredByAuthenticatedUser: () => {},
+      },
+    } as any;
+
+    const repos = await getGithubStarredRepositories({
+      octokit,
+      config: {
+        githubConfig: {
+          starredLists: ["ui-frontend", "email-self-hosted", "paas-hosting-deploy"],
+        },
+      } as any,
+    });
+
+    expect(repos).toHaveLength(3);
+    expect(repos.map((repo) => repo.fullName).sort()).toEqual([
+      "acme/email-app",
+      "acme/paas-app",
+      "acme/ui-app",
+    ]);
+    expect(paginate).toHaveBeenCalledTimes(0);
+  });
+
+  test("throws when configured star list names do not match any GitHub list", async () => {
+    const paginate = mock(async () => []);
+    const graphql = mock(async (_query: string, variables?: Record<string, unknown>) => {
+      if (!variables || !("listId" in variables)) {
+        return {
+          viewer: {
+            lists: {
+              nodes: [{ id: "list-1", name: "HomeLab" }],
+              pageInfo: { hasNextPage: false, endCursor: null },
+            },
+          },
+        };
+      }
+
+      return {
+        node: {
+          items: {
+            nodes: [],
+            pageInfo: { hasNextPage: false, endCursor: null },
+          },
+        },
+      };
+    });
+
+    const octokit = {
+      paginate,
+      graphql,
+      activity: {
+        listReposStarredByAuthenticatedUser: () => {},
+      },
+    } as any;
+
+    await expect(
+      getGithubStarredRepositories({
+        octokit,
+        config: {
+          githubConfig: {
+            starredLists: ["MissingList"],
+          },
+        } as any,
+      }),
+    ).rejects.toThrow("Configured GitHub star lists not found");
+    expect(paginate).toHaveBeenCalledTimes(0);
+  });
+
+  test("returns all available starred list names with pagination", async () => {
+    const graphql = mock(async (_query: string, variables?: Record<string, unknown>) => {
+      if (!variables?.after) {
+        return {
+          viewer: {
+            lists: {
+              nodes: [
+                null,
+                { id: "a", name: "HomeLab" },
+                { id: "b", name: "DotTools" },
+              ],
+              pageInfo: { hasNextPage: true, endCursor: "cursor-1" },
+            },
+          },
+        };
+      }
+
+      return {
+        viewer: {
+          lists: {
+            nodes: [
+              { id: "c", name: "Ideas" },
+            ],
+            pageInfo: { hasNextPage: false, endCursor: null },
+          },
+        },
+      };
+    });
+
+    const octokit = { graphql } as any;
+    const lists = await getGithubStarredListNames({ octokit });
+    expect(lists).toEqual(["HomeLab", "DotTools", "Ideas"]);
+    expect(graphql).toHaveBeenCalledTimes(2);
+  });
+});

src/lib/github.ts

@@ -22,22 +22,30 @@ if (process.env.NODE_ENV !== "test") {
 // Fallback to base Octokit if .plugin is not present
 const MyOctokit: any = (Octokit as any)?.plugin?.call
   ? (Octokit as any).plugin(throttling)
-  : Octokit as any;
+  : (Octokit as any);
 
 /**
  * Creates an authenticated Octokit instance with rate limit tracking and throttling
  */
-export function createGitHubClient(token: string, userId?: string, username?: string): Octokit {
+export function createGitHubClient(
+  token: string,
+  userId?: string,
+  username?: string,
+): Octokit {
   // Create a proper User-Agent to identify our application
   // This helps GitHub understand our traffic patterns and can provide better rate limits
-  const userAgent = username 
-    ? `gitea-mirror/3.5.4 (user:${username})` 
+  const userAgent = username
+    ? `gitea-mirror/3.5.4 (user:${username})`
     : "gitea-mirror/3.5.4";
-  
+
+  // Support GH_API_URL (preferred) or GITHUB_API_URL (may conflict with GitHub Actions)
+  // GitHub Actions sets GITHUB_API_URL to https://api.github.com by default
+  const baseUrl = process.env.GH_API_URL || process.env.GITHUB_API_URL || "https://api.github.com";
+
   const octokit = new MyOctokit({
     auth: token, // Always use token for authentication (5000 req/hr vs 60 for unauthenticated)
     userAgent, // Identify our application and user
-    baseUrl: "https://api.github.com", // Explicitly set the API endpoint
+    baseUrl, // Configurable for E2E testing
     log: {
       debug: () => {},
       info: console.log,
@@ -52,14 +60,19 @@ export function createGitHubClient(token: string, userId?: string, username?: st
       },
     },
     throttle: {
-      onRateLimit: async (retryAfter: number, options: any, octokit: any, retryCount: number) => {
+      onRateLimit: async (
+        retryAfter: number,
+        options: any,
+        octokit: any,
+        retryCount: number,
+      ) => {
         const isSearch = options.url.includes("/search/");
         const maxRetries = isSearch ? 5 : 3; // Search endpoints get more retries
-        
+
         console.warn(
-          `[GitHub] Rate limit hit for ${options.method} ${options.url}. Retry ${retryCount + 1}/${maxRetries}`
+          `[GitHub] Rate limit hit for ${options.method} ${options.url}. Retry ${retryCount + 1}/${maxRetries}`,
         );
-        
+
         // Update rate limit status and notify UI (if available)
         if (userId && RateLimitManager) {
           await RateLimitManager.updateFromResponse(userId, {
@@ -68,7 +81,7 @@ export function createGitHubClient(token: string, userId?: string, username?: st
             "x-ratelimit-reset": (Date.now() / 1000 + retryAfter).toString(),
           });
         }
-        
+
         if (userId && publishEvent) {
           await publishEvent({
             userId,
@@ -83,22 +96,29 @@ export function createGitHubClient(token: string, userId?: string, username?: st
             },
           });
         }
-        
+
         // Retry with exponential backoff
         if (retryCount < maxRetries) {
           console.log(`[GitHub] Waiting ${retryAfter}s before retry...`);
           return true;
         }
-        
+
         // Max retries reached
-        console.error(`[GitHub] Max retries (${maxRetries}) reached for ${options.url}`);
+        console.error(
+          `[GitHub] Max retries (${maxRetries}) reached for ${options.url}`,
+        );
         return false;
       },
-      onSecondaryRateLimit: async (retryAfter: number, options: any, octokit: any, retryCount: number) => {
+      onSecondaryRateLimit: async (
+        retryAfter: number,
+        options: any,
+        octokit: any,
+        retryCount: number,
+      ) => {
         console.warn(
-          `[GitHub] Secondary rate limit hit for ${options.method} ${options.url}`
+          `[GitHub] Secondary rate limit hit for ${options.method} ${options.url}`,
         );
-        
+
         // Update status and notify UI (if available)
         if (userId && publishEvent) {
           await publishEvent({
@@ -114,13 +134,15 @@ export function createGitHubClient(token: string, userId?: string, username?: st
             },
           });
         }
-        
+
         // Retry up to 2 times for secondary rate limits
         if (retryCount < 2) {
-          console.log(`[GitHub] Waiting ${retryAfter}s for secondary rate limit...`);
+          console.log(
+            `[GitHub] Waiting ${retryAfter}s for secondary rate limit...`,
+          );
           return true;
         }
-        
+
         return false;
       },
       // Throttle options to prevent hitting limits
@@ -129,50 +151,57 @@ export function createGitHubClient(token: string, userId?: string, username?: st
       retryAfterBaseValue: 1000, // Base retry in ms
     },
   });
-  
-  // Add additional rate limit tracking if userId is provided and RateLimitManager is available
+
+  // Add rate limit tracking hooks if userId is provided and RateLimitManager is available
   if (userId && RateLimitManager) {
-    octokit.hook.after("request", async (response: any, options: any) => {
-      // Update rate limit from response headers
+    octokit.hook.after("request", async (response: any, _options: any) => {
       if (response.headers) {
         await RateLimitManager.updateFromResponse(userId, response.headers);
       }
     });
-    
+
     octokit.hook.error("request", async (error: any, options: any) => {
       // Handle rate limit errors
       if (error.status === 403 || error.status === 429) {
         const message = error.message || "";
-        
-        if (message.includes("rate limit") || message.includes("API rate limit")) {
-          console.error(`[GitHub] Rate limit error for user ${userId}: ${message}`);
-          
+
+        if (
+          message.includes("rate limit") ||
+          message.includes("API rate limit")
+        ) {
+          console.error(
+            `[GitHub] Rate limit error for user ${userId}: ${message}`,
+          );
+
           // Update rate limit status from error response (if available)
           if (error.response?.headers && RateLimitManager) {
-            await RateLimitManager.updateFromResponse(userId, error.response.headers);
+            await RateLimitManager.updateFromResponse(
+              userId,
+              error.response.headers,
+            );
           }
-          
+
           // Create error event for UI (if available)
           if (publishEvent) {
             await publishEvent({
               userId,
-            channel: "rate-limit",
-            payload: {
-              type: "error",
-              provider: "github",
-              error: message,
-              endpoint: options.url,
-              message: `Rate limit exceeded: ${message}`,
-            },
-          });
+              channel: "rate-limit",
+              payload: {
+                type: "error",
+                provider: "github",
+                error: message,
+                endpoint: options.url,
+                message: `Rate limit exceeded: ${message}`,
+              },
+            });
           }
         }
       }
-      
+
       throw error;
     });
   }
-  
+
   return octokit;
 }
 
@@ -206,14 +235,31 @@ export async function getGithubRepoCloneUrl({
 export async function getGithubRepositories({
   octokit,
   config,
+  includeCollaboratorReposOverride,
 }: {
   octokit: Octokit;
   config: Partial<Config>;
+  // Force-include collaborator repos regardless of user setting. Used by the
+  // cleanup service so we never mark a collab repo as orphaned just because
+  // the import filter is currently off.
+  includeCollaboratorReposOverride?: boolean;
 }): Promise<GitRepo[]> {
   try {
+    const includeCollab =
+      includeCollaboratorReposOverride ??
+      config.githubConfig?.includeCollaboratorRepos ??
+      true;
+    // Always include organization_member so repos owned by orgs the user
+    // belongs to are returned. Omitting it caused org repos to be invisible
+    // to the main sync, the scheduler, and the cleanup service (which then
+    // archived them on restart as if they had been deleted on GitHub).
+    const affiliation = includeCollab
+      ? "owner,collaborator,organization_member"
+      : "owner,organization_member";
+
     const repos = await octokit.paginate(
       octokit.repos.listForAuthenticatedUser,
-      { per_page: 100 }
+      { per_page: 100, affiliation },
     );
 
     const skipForks = config.githubConfig?.skipForks ?? false;
@@ -254,9 +300,11 @@ export async function getGithubRepositories({
       visibility: (repo.visibility ?? "public") as GitRepo["visibility"],
 
       status: "imported",
+      isDisabled: repo.disabled ?? false,
       lastMirrored: undefined,
       errorMessage: undefined,
 
+      importedAt: new Date(),
       createdAt: repo.created_at ? new Date(repo.created_at) : new Date(),
       updatedAt: repo.updated_at ? new Date(repo.updated_at) : new Date(),
     }));
@@ -264,24 +312,297 @@ export async function getGithubRepositories({
     throw new Error(
       `Error fetching repositories: ${
         error instanceof Error ? error.message : String(error)
-      }`
+      }`,
     );
   }
 }
 
+function getStarredListMatchKey(rawValue: string): string {
+  const normalized = rawValue.normalize("NFKC").trim().toLowerCase();
+  const tokens = normalized.match(/[\p{L}\p{N}]+/gu);
+  return tokens ? tokens.join("") : "";
+}
+
+function normalizeStarredListNames(rawLists: unknown): string[] {
+  if (!Array.isArray(rawLists)) return [];
+
+  const deduped = new Map<string, string>();
+  for (const value of rawLists) {
+    if (typeof value !== "string") continue;
+    const trimmed = value.trim();
+    if (!trimmed) continue;
+    const matchKey = getStarredListMatchKey(trimmed);
+    if (!matchKey || deduped.has(matchKey)) continue;
+    deduped.set(matchKey, trimmed);
+  }
+
+  return [...deduped.values()];
+}
+
+function toHttpsCloneUrl(repoUrl: string): string {
+  return repoUrl.endsWith(".git") ? repoUrl : `${repoUrl}.git`;
+}
+
+interface GitHubStarListNode {
+  id: string;
+  name: string;
+}
+
+interface GitHubRepositoryListItem {
+  __typename: "Repository";
+  name: string;
+  nameWithOwner: string;
+  url: string;
+  sshUrl: string;
+  isPrivate: boolean;
+  isFork: boolean;
+  isArchived: boolean;
+  isDisabled: boolean;
+  hasIssuesEnabled: boolean;
+  diskUsage: number;
+  description: string | null;
+  defaultBranchRef: { name: string } | null;
+  visibility: "PUBLIC" | "PRIVATE" | "INTERNAL";
+  updatedAt: string;
+  createdAt: string;
+  owner: {
+    __typename: "Organization" | "User" | string;
+    login: string;
+  };
+  primaryLanguage: {
+    name: string;
+  } | null;
+}
+
+async function getGithubStarLists(octokit: Octokit): Promise<GitHubStarListNode[]> {
+  const allLists: GitHubStarListNode[] = [];
+  let cursor: string | null = null;
+
+  do {
+    const result = await octokit.graphql<{
+      viewer: {
+        lists: {
+          nodes: Array<GitHubStarListNode | null> | null;
+          pageInfo: {
+            hasNextPage: boolean;
+            endCursor: string | null;
+          };
+        };
+      };
+    }>(
+      `
+        query($after: String) {
+          viewer {
+            lists(first: 50, after: $after) {
+              nodes {
+                id
+                name
+              }
+              pageInfo {
+                hasNextPage
+                endCursor
+              }
+            }
+          }
+        }
+      `,
+      { after: cursor },
+    );
+
+    const lists = (result.viewer.lists.nodes ?? []).filter(
+      (list): list is GitHubStarListNode =>
+        !!list &&
+        typeof list.id === "string" &&
+        typeof list.name === "string",
+    );
+    allLists.push(...lists);
+
+    if (!result.viewer.lists.pageInfo.hasNextPage) break;
+    cursor = result.viewer.lists.pageInfo.endCursor;
+  } while (cursor);
+
+  return allLists;
+}
+
+async function getGithubRepositoriesForStarList(
+  octokit: Octokit,
+  listId: string,
+): Promise<GitHubRepositoryListItem[]> {
+  const repositories: GitHubRepositoryListItem[] = [];
+  let cursor: string | null = null;
+
+  do {
+    const result = await octokit.graphql<{
+      node: {
+        items: {
+          nodes: Array<GitHubRepositoryListItem | null> | null;
+          pageInfo: {
+            hasNextPage: boolean;
+            endCursor: string | null;
+          };
+        };
+      } | null;
+    }>(
+      `
+        query($listId: ID!, $after: String) {
+          node(id: $listId) {
+            ... on UserList {
+              items(first: 100, after: $after) {
+                nodes {
+                  __typename
+                  ... on Repository {
+                    name
+                    nameWithOwner
+                    url
+                    sshUrl
+                    isPrivate
+                    isFork
+                    isArchived
+                    isDisabled
+                    hasIssuesEnabled
+                    diskUsage
+                    description
+                    defaultBranchRef {
+                      name
+                    }
+                    visibility
+                    updatedAt
+                    createdAt
+                    owner {
+                      __typename
+                      login
+                    }
+                    primaryLanguage {
+                      name
+                    }
+                  }
+                }
+                pageInfo {
+                  hasNextPage
+                  endCursor
+                }
+              }
+            }
+          }
+        }
+      `,
+      { listId, after: cursor },
+    );
+
+    const listNode = result.node;
+    if (!listNode) break;
+
+    const nodes = listNode.items.nodes ?? [];
+    for (const node of nodes) {
+      if (node?.__typename === "Repository") {
+        repositories.push(node);
+      }
+    }
+
+    if (!listNode.items.pageInfo.hasNextPage) break;
+    cursor = listNode.items.pageInfo.endCursor;
+  } while (cursor);
+
+  return repositories;
+}
+
+function mapGraphqlRepoToGitRepo(repo: GitHubRepositoryListItem): GitRepo {
+  const visibility = (repo.visibility ?? "PUBLIC").toLowerCase() as GitRepo["visibility"];
+  const createdAt = repo.createdAt ? new Date(repo.createdAt) : new Date();
+  const updatedAt = repo.updatedAt ? new Date(repo.updatedAt) : new Date();
+
+  return {
+    name: repo.name,
+    fullName: repo.nameWithOwner,
+    url: repo.url,
+    cloneUrl: toHttpsCloneUrl(repo.url),
+
+    owner: repo.owner.login,
+    organization: repo.owner.__typename === "Organization" ? repo.owner.login : undefined,
+    mirroredLocation: "",
+    destinationOrg: null,
+
+    isPrivate: repo.isPrivate,
+    isForked: repo.isFork,
+    forkedFrom: undefined,
+
+    hasIssues: repo.hasIssuesEnabled,
+    isStarred: true,
+    isArchived: repo.isArchived,
+
+    size: repo.diskUsage ?? 0,
+    hasLFS: false,
+    hasSubmodules: false,
+
+    language: repo.primaryLanguage?.name ?? null,
+    description: repo.description,
+    defaultBranch: repo.defaultBranchRef?.name || "main",
+    visibility,
+
+    status: "imported",
+    isDisabled: repo.isDisabled,
+    lastMirrored: undefined,
+    errorMessage: undefined,
+
+    importedAt: new Date(),
+    createdAt,
+    updatedAt,
+  };
+}
+
 export async function getGithubStarredRepositories({
   octokit,
   config,
 }: {
   octokit: Octokit;
   config: Partial<Config>;
-}) {
+}): Promise<GitRepo[]> {
   try {
+    const configuredLists = normalizeStarredListNames(
+      config.githubConfig?.starredLists,
+    );
+
+    if (configuredLists.length > 0) {
+      const allLists = await getGithubStarLists(octokit);
+      const configuredMatchKeySet = new Set(
+        configuredLists.map((list) => getStarredListMatchKey(list)),
+      );
+
+      const matchedLists = allLists.filter((list) =>
+        configuredMatchKeySet.has(getStarredListMatchKey(list.name)),
+      );
+
+      if (matchedLists.length === 0) {
+        const availableListNames = normalizeStarredListNames(
+          allLists.map((list) => list.name),
+        );
+        const preview = availableListNames.slice(0, 20).join(", ");
+        const availableSuffix = preview
+          ? `. Available lists: ${preview}${availableListNames.length > 20 ? ", ..." : ""}`
+          : "";
+        throw new Error(
+          `Configured GitHub star lists not found: ${configuredLists.join(", ")}${availableSuffix}`,
+        );
+      }
+
+      const deduped = new Map<string, GitRepo>();
+      for (const list of matchedLists) {
+        const repos = await getGithubRepositoriesForStarList(octokit, list.id);
+        for (const repo of repos) {
+          const key = repo.nameWithOwner.toLowerCase();
+          if (deduped.has(key)) continue;
+          deduped.set(key, mapGraphqlRepoToGitRepo(repo));
+        }
+      }
+
+      return [...deduped.values()];
+    }
+
     const starredRepos = await octokit.paginate(
       octokit.activity.listReposStarredByAuthenticatedUser,
       {
         per_page: 100,
-      }
+      },
     );
 
     return starredRepos.map((repo) => ({
@@ -314,9 +635,11 @@ export async function getGithubStarredRepositories({
       visibility: (repo.visibility ?? "public") as GitRepo["visibility"],
 
       status: "imported",
+      isDisabled: repo.disabled ?? false,
       lastMirrored: undefined,
       errorMessage: undefined,
 
+      importedAt: new Date(),
       createdAt: repo.created_at ? new Date(repo.created_at) : new Date(),
       updatedAt: repo.updated_at ? new Date(repo.updated_at) : new Date(),
     }));
@@ -324,11 +647,20 @@ export async function getGithubStarredRepositories({
     throw new Error(
       `Error fetching starred repositories: ${
         error instanceof Error ? error.message : String(error)
-      }`
+      }`,
     );
   }
 }
 
+export async function getGithubStarredListNames({
+  octokit,
+}: {
+  octokit: Octokit;
+}): Promise<string[]> {
+  const lists = await getGithubStarLists(octokit);
+  return normalizeStarredListNames(lists.map((list) => list.name));
+}
+
 /**
  * Get user github organizations
  */
@@ -338,7 +670,7 @@ export async function getGithubOrganizations({
 }: {
   octokit: Octokit;
   config: Partial<Config>;
-}): Promise<GitOrg[]> {
+}): Promise<{ organizations: GitOrg[]; failedOrgs: { name: string; avatarUrl: string; reason: string }[] }> {
   try {
     const { data: orgs } = await octokit.orgs.listForAuthenticatedUser({
       per_page: 100,
@@ -347,47 +679,66 @@ export async function getGithubOrganizations({
     // Get excluded organizations from environment variable
     const excludedOrgsEnv = process.env.GITHUB_EXCLUDED_ORGS;
     const excludedOrgs = excludedOrgsEnv
-      ? excludedOrgsEnv.split(',').map(org => org.trim().toLowerCase())
+      ? excludedOrgsEnv.split(",").map((org) => org.trim().toLowerCase())
       : [];
 
     // Filter out excluded organizations
-    const filteredOrgs = orgs.filter(org => {
+    const filteredOrgs = orgs.filter((org) => {
       if (excludedOrgs.includes(org.login.toLowerCase())) {
-        console.log(`Skipping organization ${org.login} - excluded via GITHUB_EXCLUDED_ORGS environment variable`);
+        console.log(
+          `Skipping organization ${org.login} - excluded via GITHUB_EXCLUDED_ORGS environment variable`,
+        );
         return false;
       }
       return true;
     });
 
-    const organizations = await Promise.all(
+    const failedOrgs: { name: string; avatarUrl: string; reason: string }[] = [];
+    const results = await Promise.all(
       filteredOrgs.map(async (org) => {
-        const [{ data: orgDetails }, { data: membership }] = await Promise.all([
-          octokit.orgs.get({ org: org.login }),
-          octokit.orgs.getMembershipForAuthenticatedUser({ org: org.login }),
-        ]);
+        try {
+          const [{ data: orgDetails }, { data: membership }] = await Promise.all([
+            octokit.orgs.get({ org: org.login }),
+            octokit.orgs.getMembershipForAuthenticatedUser({ org: org.login }),
+          ]);
 
-        const totalRepos =
-          orgDetails.public_repos + (orgDetails.total_private_repos ?? 0);
+          const totalRepos =
+            orgDetails.public_repos + (orgDetails.total_private_repos ?? 0);
 
-        return {
-          name: org.login,
-          avatarUrl: org.avatar_url,
-          membershipRole: membership.role as MembershipRole,
-          isIncluded: false,
-          status: "imported" as RepoStatus,
-          repositoryCount: totalRepos,
-          createdAt: new Date(),
-          updatedAt: new Date(),
-        };
-      })
+          return {
+            name: org.login,
+            avatarUrl: org.avatar_url,
+            membershipRole: membership.role as MembershipRole,
+            isIncluded: false,
+            status: "imported" as RepoStatus,
+            repositoryCount: totalRepos,
+            createdAt: new Date(),
+            updatedAt: new Date(),
+          };
+        } catch (error: any) {
+          // Capture organizations that return 403 (SAML enforcement, insufficient token scope, etc.)
+          if (error?.status === 403) {
+            const reason = error?.message || "access denied";
+            console.warn(
+              `Failed to import organization ${org.login} - ${reason}`,
+            );
+            failedOrgs.push({ name: org.login, avatarUrl: org.avatar_url, reason });
+            return null;
+          }
+          throw error;
+        }
+      }),
     );
 
-    return organizations;
+    return {
+      organizations: results.filter((org): org is NonNullable<typeof org> => org !== null),
+      failedOrgs,
+    };
   } catch (error) {
     throw new Error(
       `Error fetching organizations: ${
         error instanceof Error ? error.message : String(error)
-      }`
+      }`,
     );
   }
 }
@@ -438,9 +789,11 @@ export async function getGithubOrganizationRepositories({
       visibility: (repo.visibility ?? "public") as GitRepo["visibility"],
 
       status: "imported",
+      isDisabled: repo.disabled ?? false,
       lastMirrored: undefined,
       errorMessage: undefined,
 
+      importedAt: new Date(),
       createdAt: repo.created_at ? new Date(repo.created_at) : new Date(),
       updatedAt: repo.updated_at ? new Date(repo.updated_at) : new Date(),
     }));
@@ -448,7 +801,7 @@ export async function getGithubOrganizationRepositories({
     throw new Error(
       `Error fetching organization repositories: ${
         error instanceof Error ? error.message : String(error)
-      }`
+      }`,
     );
   }
 }

src/lib/helpers.ts

@@ -3,6 +3,7 @@ import { db, mirrorJobs } from "./db";
 import { eq, and, or, lt, isNull } from "drizzle-orm";
 import { v4 as uuidv4 } from "uuid";
 import { publishEvent } from "./events";
+import { triggerJobNotification } from "./notification-service";
 
 export async function createMirrorJob({
   userId,
@@ -19,6 +20,7 @@ export async function createMirrorJob({
   itemIds,
   inProgress,
   skipDuplicateEvent,
+  skipNotification,
 }: {
   userId: string;
   organizationId?: string;
@@ -34,6 +36,7 @@ export async function createMirrorJob({
   itemIds?: string[];
   inProgress?: boolean;
   skipDuplicateEvent?: boolean; // Option to skip event publishing for internal operations
+  skipNotification?: boolean; // Option to skip push notifications for specific internal operations
 }) {
   const jobId = uuidv4();
   const currentTimestamp = new Date();
@@ -67,7 +70,7 @@ export async function createMirrorJob({
     // Insert the job into the database
     await db.insert(mirrorJobs).values(job);
 
-    // Publish the event using SQLite instead of Redis (unless skipped)
+    // Publish realtime status events unless explicitly skipped
     if (!skipDuplicateEvent) {
       const channel = `mirror-status:${userId}`;
 
@@ -89,6 +92,15 @@ export async function createMirrorJob({
       });
     }
 
+    // Trigger push notifications for terminal statuses (never blocks the mirror flow).
+    // Keep this independent from skipDuplicateEvent so event-stream suppression does not
+    // silently disable user-facing notifications.
+    if (!skipNotification && (status === "failed" || status === "mirrored" || status === "synced")) {
+      triggerJobNotification({ userId, status, repositoryName, organizationName, message, details }).catch(err => {
+        console.error("[NotificationService] Background notification failed:", err);
+      });
+    }
+
     return jobId;
   } catch (error) {
     console.error("Error creating mirror job:", error);
@@ -204,9 +216,21 @@ export async function updateMirrorJobProgress({
 }
 
 /**
- * Finds interrupted jobs that need to be resumed with enhanced criteria
+ * Finds interrupted jobs that need to be resumed with enhanced criteria.
+ *
+ * `logFound` defaults to false because this function is polled from
+ * passive callers (`hasJobsNeedingRecovery` from the health endpoint
+ * and middleware checks). Logging on every poll produces log spam at
+ * one-line-per-poll-per-stuck-job for as long as a job stays stuck.
+ *
+ * Callers that intend to act on the result (i.e. immediately resume
+ * the returned jobs) should pass `logFound: true` so the surfacing
+ * still happens in the recovery flow.
  */
-export async function findInterruptedJobs() {
+export async function findInterruptedJobs(
+  options: { logFound?: boolean } = {}
+) {
+  const { logFound = false } = options;
   try {
     // Find jobs that are marked as in-progress but haven't been updated recently
     const cutoffTime = new Date();
@@ -231,8 +255,9 @@ export async function findInterruptedJobs() {
         )
       );
 
-    // Log details about found jobs for debugging
-    if (interruptedJobs.length > 0) {
+    // Log details about found jobs for debugging — opt-in to avoid
+    // spamming the log when called from periodic passive checks.
+    if (logFound && interruptedJobs.length > 0) {
       console.log(`Found ${interruptedJobs.length} interrupted jobs:`);
       interruptedJobs.forEach(job => {
         const lastCheckpoint = job.lastCheckpoint ? new Date(job.lastCheckpoint).toISOString() : 'never';