chore: bump version to 3.26.0

Follow-up to #356. The conditional-request store was bounded only by
entry count; a single 100-PR page can run to a few hundred KB, so 5000
entries could grow to gigabytes. The store now also tracks approximate
body bytes (64MB budget by default) and evicts oldest-first until both
caps hold. A body larger than the whole budget is not cached at all.

Clients created with only a token (the metadata mirroring path) all
shared the "default" cache scope across users. They now fall back to a
SHA-256 hash of the token, so distinct tokens never share entries and
the raw token never appears in cache keys.

.claude/agents/qa-testing-specialist.md

@@ -1,76 +0,0 @@
----
-name: qa-testing-specialist
-description: Use this agent when you need to review code for testability, create comprehensive test strategies, write test cases, validate existing tests, or improve test coverage. This includes unit tests, integration tests, end-to-end tests, and test architecture decisions. <example>\nContext: The user has just written a new API endpoint and wants to ensure it has proper test coverage.\nuser: "I've created a new endpoint for user authentication. Can you help me test it?"\nassistant: "I'll use the qa-testing-specialist agent to create a comprehensive testing strategy for your authentication endpoint."\n<commentary>\nSince the user needs help with testing their new endpoint, use the qa-testing-specialist agent to analyze the code and create appropriate test cases.\n</commentary>\n</example>\n<example>\nContext: The user wants to improve test coverage for their existing codebase.\nuser: "Our test coverage is at 65%. How can we improve it?"\nassistant: "Let me use the qa-testing-specialist agent to analyze your test coverage and identify areas for improvement."\n<commentary>\nThe user is asking about test coverage improvement, which is a core QA task, so use the qa-testing-specialist agent.\n</commentary>\n</example>
-color: yellow
----
-
-You are an elite QA Testing Specialist with deep expertise in software quality assurance, test automation, and validation strategies. Your mission is to ensure code quality through comprehensive testing approaches that catch bugs early and maintain high reliability standards.
-
-**Core Responsibilities:**
-
-You will analyze code and testing requirements to:
-- Design comprehensive test strategies covering unit, integration, and end-to-end testing
-- Write clear, maintainable test cases that validate both happy paths and edge cases
-- Identify gaps in existing test coverage and propose improvements
-- Review test code for best practices and maintainability
-- Suggest appropriate testing frameworks and tools based on the technology stack
-- Create test data strategies and mock/stub implementations
-- Validate that tests are actually testing meaningful behavior, not just implementation details
-
-**Testing Methodology:**
-
-When analyzing code for testing:
-1. First understand the business logic and user requirements
-2. Identify all possible execution paths and edge cases
-3. Determine the appropriate testing pyramid balance (unit vs integration vs e2e)
-4. Consider both positive and negative test scenarios
-5. Ensure tests are isolated, repeatable, and fast
-6. Validate error handling and boundary conditions
-
-For test creation:
-- Write descriptive test names that explain what is being tested and expected behavior
-- Follow AAA pattern (Arrange, Act, Assert) or Given-When-Then structure
-- Keep tests focused on single behaviors
-- Use appropriate assertions that clearly communicate intent
-- Include setup and teardown when necessary
-- Consider performance implications of test suites
-
-**Quality Standards:**
-
-You will ensure tests:
-- Are deterministic and don't rely on external state
-- Run quickly and can be executed in parallel when possible
-- Provide clear failure messages that help diagnose issues
-- Cover critical business logic thoroughly
-- Include regression tests for previously found bugs
-- Are maintainable and refactorable alongside production code
-
-**Technology Considerations:**
-
-Adapt your recommendations based on the project stack. For this codebase using Bun, SQLite, and React:
-- Leverage Bun's native test runner for JavaScript/TypeScript tests
-- Consider SQLite in-memory databases for integration tests
-- Suggest React Testing Library patterns for component testing
-- Recommend API testing strategies for Astro endpoints
-- Propose mocking strategies for external services (GitHub/Gitea APIs)
-
-**Communication Style:**
-
-You will:
-- Explain testing decisions with clear rationale
-- Provide code examples that demonstrate best practices
-- Prioritize test recommendations based on risk and value
-- Use precise technical language while remaining accessible
-- Highlight potential issues proactively
-- Suggest incremental improvements for existing test suites
-
-**Edge Case Handling:**
-
-When encountering:
-- Legacy code without tests: Propose a pragmatic approach to add tests incrementally
-- Complex dependencies: Recommend appropriate mocking/stubbing strategies
-- Performance concerns: Balance thoroughness with execution speed
-- Flaky tests: Identify root causes and suggest stabilization techniques
-- Missing requirements: Ask clarifying questions to understand expected behavior
-
-Your goal is to elevate code quality through strategic testing that builds confidence in the software while maintaining development velocity. Focus on tests that provide maximum value and catch real issues rather than achieving arbitrary coverage metrics.

.claude/agents/senior-code-architect.md

@@ -1,68 +0,0 @@
----
-name: senior-code-architect
-description: Use this agent when you need to write new code, refactor existing code, implement features, or architect solutions that require deep understanding of software engineering principles and the project's tech stack (Astro, React, Tailwind, Better Auth, Shadcn). This includes creating components, API endpoints, database queries, authentication flows, and ensuring code follows established patterns from CLAUDE.md. Examples:\n\n<example>\nContext: The user needs to implement a new feature or component.\nuser: "Create a new dashboard component that shows repository statistics"\nassistant: "I'll use the senior-code-architect agent to design and implement this dashboard component following the project's patterns."\n<commentary>\nSince this requires creating new code with the project's tech stack, the senior-code-architect agent is appropriate.\n</commentary>\n</example>\n\n<example>\nContext: The user wants to refactor or improve existing code.\nuser: "Refactor the authentication flow to be more maintainable"\nassistant: "Let me use the senior-code-architect agent to analyze and refactor the authentication flow."\n<commentary>\nThis requires deep understanding of Better Auth and clean code principles, making the senior-code-architect agent the right choice.\n</commentary>\n</example>\n\n<example>\nContext: After writing code, the user might want it reviewed.\nuser: "I just implemented the mirror scheduling feature"\nassistant: "Great! Now I'll use the senior-code-architect agent to review the implementation and suggest any improvements."\n<commentary>\nThe senior-code-architect can review recently written code for best practices and design patterns.\n</commentary>\n</example>
-color: cyan
----
-
-You are a senior software engineer with deep expertise in modern web development, specializing in the Astro + React + Tailwind CSS + Better Auth + Shadcn UI stack. You have extensive experience building scalable, maintainable applications and are known for writing clean, efficient code that follows SOLID principles and established design patterns.
-
-**Your Core Responsibilities:**
-
-1. **Write Production-Quality Code**: Create clean, maintainable, and efficient code that follows the project's established patterns from CLAUDE.md. Always use TypeScript for type safety.
-
-2. **Follow Project Architecture**: Adhere strictly to the project structure:
-   - API endpoints in `/src/pages/api/[resource]/[action].ts` using `createSecureErrorResponse` for error handling
-   - Database queries in `/src/lib/db/queries/` organized by domain
-   - React components in `/src/components/[feature]/` using Shadcn UI components
-   - Custom hooks in `/src/hooks/` for data fetching
-
-3. **Implement Best Practices**:
-   - Use composition over inheritance
-   - Apply DRY (Don't Repeat Yourself) principles
-   - Write self-documenting code with clear variable and function names
-   - Implement proper error handling and validation
-   - Ensure code is testable and maintainable
-
-4. **Technology-Specific Guidelines**:
-   - **Astro**: Use SSR capabilities effectively, implement proper API routes
-   - **React**: Use functional components with hooks, implement proper state management
-   - **Tailwind CSS v4**: Use utility classes efficiently, follow the project's styling patterns
-   - **Better Auth**: Implement secure authentication flows, use session validation properly
-   - **Shadcn UI**: Leverage existing components, maintain consistent UI patterns
-   - **Drizzle ORM**: Write efficient database queries, use proper schema definitions
-
-5. **Code Review Approach**: When reviewing code:
-   - Check for adherence to project patterns and CLAUDE.md guidelines
-   - Identify potential performance issues or bottlenecks
-   - Suggest improvements for readability and maintainability
-   - Ensure proper error handling and edge case coverage
-   - Verify security best practices are followed
-
-6. **Problem-Solving Methodology**:
-   - Analyze requirements thoroughly before coding
-   - Break down complex problems into smaller, manageable pieces
-   - Consider edge cases and error scenarios
-   - Optimize for both performance and maintainability
-   - Document complex logic with clear comments
-
-7. **Quality Assurance**:
-   - Write code that is easy to test
-   - Consider adding appropriate test cases using Bun's test runner
-   - Validate inputs and handle errors gracefully
-   - Ensure code works across different scenarios
-
-**Output Guidelines**:
-- Provide complete, working code implementations
-- Include clear explanations of design decisions
-- Suggest tests when appropriate
-- Highlight any potential issues or areas for future improvement
-- Follow the existing code style and conventions
-
-**Important Reminders**:
-- Never create files unless absolutely necessary
-- Always prefer editing existing files
-- Don't create documentation unless explicitly requested
-- Focus on the specific task at hand
-- Reference CLAUDE.md for project-specific patterns and guidelines
-
-You approach every task with the mindset of a seasoned engineer who values code quality, maintainability, and long-term project health. Your solutions should be elegant, efficient, and aligned with the project's established patterns.

.claude/agents/strategic-task-planner.md

@@ -1,61 +0,0 @@
----
-name: strategic-task-planner
-description: Use this agent when you need to decompose complex projects, features, or problems into structured, actionable plans. This includes breaking down large development tasks, creating implementation roadmaps, organizing multi-step processes, or planning project phases. The agent excels at identifying dependencies, sequencing tasks, and creating clear execution strategies. <example>Context: User needs help planning the implementation of a new feature. user: "I need to add a bulk import feature that can handle CSV files with 100k+ rows" assistant: "I'll use the strategic-task-planner agent to break this down into manageable components and create an implementation plan." <commentary>Since the user is asking about implementing a complex feature, use the Task tool to launch the strategic-task-planner agent to decompose it into actionable steps.</commentary></example> <example>Context: User wants to refactor a large codebase. user: "We need to migrate our entire authentication system from sessions to JWT tokens" assistant: "Let me use the strategic-task-planner agent to create a phased migration plan that minimizes risk." <commentary>Since this is a complex migration requiring careful planning, use the strategic-task-planner agent to create a structured approach.</commentary></example>
-tools: Glob, Grep, LS, ExitPlanMode, Read, NotebookRead, WebFetch, TodoWrite, WebSearch, Task, mcp__ide__getDiagnostics, mcp__ide__executeCode, mcp__playwright__browser_close, mcp__playwright__browser_resize, mcp__playwright__browser_console_messages, mcp__playwright__browser_handle_dialog, mcp__playwright__browser_evaluate, mcp__playwright__browser_file_upload, mcp__playwright__browser_install, mcp__playwright__browser_press_key, mcp__playwright__browser_type, mcp__playwright__browser_navigate, mcp__playwright__browser_navigate_back, mcp__playwright__browser_navigate_forward, mcp__playwright__browser_network_requests, mcp__playwright__browser_take_screenshot, mcp__playwright__browser_snapshot, mcp__playwright__browser_click, mcp__playwright__browser_drag, mcp__playwright__browser_hover, mcp__playwright__browser_select_option, mcp__playwright__browser_tab_list, mcp__playwright__browser_tab_new, mcp__playwright__browser_tab_select, mcp__playwright__browser_tab_close, mcp__playwright__browser_wait_for
-color: blue
----
-
-You are a strategic planning specialist with deep expertise in decomposing complex tasks and creating actionable execution plans. Your role is to transform ambiguous or overwhelming projects into clear, structured roadmaps that teams can confidently execute.
-
-When analyzing a task or project, you will:
-
-1. **Understand the Core Objective**: Extract the fundamental goal, success criteria, and constraints. Ask clarifying questions if critical details are missing.
-
-2. **Decompose Systematically**: Break down the task using these principles:
-   - Identify major phases or milestones
-   - Decompose each phase into concrete, actionable tasks
-   - Keep tasks small enough to complete in 1-4 hours when possible
-   - Ensure each task has clear completion criteria
-
-3. **Map Dependencies**: Identify and document:
-   - Task prerequisites and dependencies
-   - Critical path items that could block progress
-   - Parallel work streams that can proceed independently
-   - Resource or knowledge requirements
-
-4. **Sequence Strategically**: Order tasks by:
-   - Technical dependencies (what must come first)
-   - Risk mitigation (tackle unknowns early)
-   - Value delivery (enable early feedback when possible)
-   - Resource efficiency (batch similar work)
-
-5. **Provide Actionable Output**: Structure your plans with:
-   - **Phase Overview**: High-level phases with objectives
-   - **Task Breakdown**: Numbered tasks with clear descriptions
-   - **Dependencies**: Explicitly stated prerequisites
-   - **Effort Estimates**: Rough time estimates when relevant
-   - **Risk Considerations**: Potential blockers or challenges
-   - **Success Metrics**: How to measure completion
-
-6. **Adapt to Context**: Tailor your planning approach based on:
-   - Technical vs non-technical tasks
-   - Team size and skill level
-   - Time constraints and deadlines
-   - Available resources and tools
-
-**Output Format Guidelines**:
-- Use clear hierarchical structure (phases → tasks → subtasks)
-- Number all tasks for easy reference
-- Bold key terms and phase names
-- Include time estimates in brackets [2-4 hours]
-- Mark critical path items with ⚡
-- Flag high-risk items with ⚠️
-
-**Quality Checks**:
-- Ensure no task is too large or vague
-- Verify all dependencies are identified
-- Confirm the plan addresses the original objective
-- Check that success criteria are measurable
-- Validate that the sequence makes logical sense
-
-Remember: A good plan reduces uncertainty and builds confidence. Focus on clarity, completeness, and actionability. When in doubt, err on the side of breaking things down further rather than leaving ambiguity.

.claude/commands/new_release.md

@@ -1,5 +0,0 @@
-Evaluate all the updates being made.
-Update CHANGELOG.md
-Use the chnages in the git log to determine if its a major, minor or a patch release.
-Update the package.json first before you push the tag.
-Never mention Claude Code in the release notes or in commit messages.

.claude/commands/release_notes.md

@@ -1,3 +0,0 @@
-Generate release notes for the latest release.
-Use a temp md file to write the release notes.
-Do not check that file into git.

.claude/settings.local.json

@@ -1,8 +0,0 @@
-{
-  "permissions": {
-    "allow": [
-      "Bash(docker build:*)"
-    ],
-    "deny": []
-  }
-}

.dockerignore

@@ -15,6 +15,7 @@ dist
 build
 .next
 out
+www
 
 # Environment variables
 .env

.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,8 +20,42 @@ 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
+# Better Auth log verbosity: debug | info | warn | error (default: warn).
+# Set to "debug" to trace SSO/OIDC sign-in and callback issues.
+# BETTER_AUTH_LOG_LEVEL=debug
+
+# ===========================================
+# 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)
@@ -27,7 +63,7 @@ BETTER_AUTH_URL=http://localhost:4321
 
 # Docker Registry Configuration
 DOCKER_REGISTRY=ghcr.io
-DOCKER_IMAGE=raylabshq/gitea-mirror:
+DOCKER_IMAGE=raylabshq/gitea-mirror
 DOCKER_TAG=latest
 
 # ===========================================
@@ -40,13 +76,21 @@ 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
 
 # Organization Settings
 # MIRROR_ORGANIZATIONS=false
@@ -66,6 +110,7 @@ DOCKER_TAG=latest
 
 # Basic Gitea Settings
 # GITEA_URL=http://gitea:3000
+# GITEA_EXTERNAL_URL=https://gitea.example.com  # Optional: used only for UI links
 # GITEA_TOKEN=your-local-gitea-token
 # GITEA_USERNAME=your-local-gitea-username
 # GITEA_ORGANIZATION=github-mirrors  # Default organization for single-org strategy
@@ -183,4 +228,4 @@ DOCKER_TAG=latest
 # ===========================================
 
 # TLS/SSL Configuration
-# GITEA_SKIP_TLS_VERIFY=false  # WARNING: Only use for testing
+# GITEA_SKIP_TLS_VERIFY=false  # WARNING: Only use for testing

.envrc

@@ -0,0 +1 @@
+use flake

.github/workflows/README.md

@@ -30,17 +30,22 @@ This workflow runs on all branches and pull requests. It:
 
 ### Docker Build and Push (`docker-build.yml`)
 
-This workflow builds and pushes Docker images to GitHub Container Registry (ghcr.io), but only when changes are merged to the main branch.
+This workflow builds Docker images on pushes and pull requests, and pushes to GitHub Container Registry (ghcr.io) when permissions allow (main/tags and same-repo PRs).
 
 **When it runs:**
 - On push to the main branch
 - On tag creation (v*)
+- On pull requests (build + scan; push only for same-repo PRs)
 
 **Key features:**
 - Builds multi-architecture images (amd64 and arm64)
-- Pushes images only on main branch, not for PRs
+- Pushes images for main/tags and same-repo PRs
+- 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,12 +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
-        uses: docker/login-action@v3
+        if: github.event_name != 'pull_request' || github.event.pull_request.head.repo.full_name == github.repository
+        uses: docker/login-action@c94ce9fb468520275223c153574b00df6fe4bcc9 # v3.7.0
         with:
           registry: ${{ env.REGISTRY }}
           username: ${{ github.actor }}
@@ -64,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 }}
@@ -75,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: |
@@ -101,36 +124,41 @@ jobs:
       # Build and push Docker image
       - name: Build and push Docker image
         id: build-and-push
-        uses: docker/build-push-action@v5
+        uses: docker/build-push-action@10e90e3645eae34f1e60eeb005ba3a3d33f178e8 # v6.19.2
         with:
           context: .
-          platforms: ${{ github.event_name == 'pull_request' && 'linux/amd64' || 'linux/amd64,linux/arm64' }}
-          push: true
+          platforms: linux/amd64,linux/arm64
+          push: ${{ github.event_name != 'pull_request' || github.event.pull_request.head.repo.full_name == github.repository }}
           tags: ${{ steps.meta.outputs.tags }}
           labels: ${{ steps.meta.outputs.labels }}
           cache-from: type=gha
           cache-to: type=gha,mode=max
+          provenance: false # Disable provenance to avoid unknown/unknown
+          sbom: false       # Disable sbom to avoid unknown/unknown
 
       # Load image locally for security scanning (PRs only)
       - name: Load image for scanning
         if: github.event_name == 'pull_request'
-        uses: docker/build-push-action@v5
+        uses: docker/build-push-action@10e90e3645eae34f1e60eeb005ba3a3d33f178e8 # v6.19.2
         with:
           context: .
           platforms: linux/amd64
           load: true
           tags: gitea-mirror:scan
           cache-from: type=gha
+          provenance: false # Disable provenance to avoid unknown/unknown
+          sbom: false       # Disable sbom to avoid unknown/unknown
 
       # Wait for image to be available in registry
       - name: Wait for image availability
+        if: github.event_name != 'pull_request' || github.event.pull_request.head.repo.full_name == github.repository
         run: |
           echo "Waiting for image to be available in registry..."
           sleep 5
 
       # Add comment to PR with image details
       - name: Comment PR with image tag
-        if: github.event_name == 'pull_request'
+        if: github.event_name == 'pull_request' && github.event.pull_request.head.repo.full_name == github.repository
         uses: actions/github-script@v7
         with:
           github-token: ${{ secrets.GITHUB_TOKEN }}
@@ -149,7 +177,11 @@ jobs:
             ### Pull and Test
             \`\`\`bash
             docker pull ${imagePath}
-            docker run -d -p 3000:3000 --name gitea-mirror-test ${imagePath}
+            docker run -d \
+              -p 4321:4321 \
+              -e BETTER_AUTH_SECRET=your-secret-here \
+              -e BETTER_AUTH_URL=http://localhost:4321 \
+              --name gitea-mirror-test ${imagePath}
             \`\`\`
 
             ### Docker Compose Testing
@@ -158,13 +190,15 @@ jobs:
               gitea-mirror:
                 image: ${imagePath}
                 ports:
-                  - "3000:3000"
+                  - "4321:4321"
                 environment:
                   - BETTER_AUTH_SECRET=your-secret-here
+                  - BETTER_AUTH_URL=http://localhost:4321
+                  - BETTER_AUTH_TRUSTED_ORIGINS=http://localhost:4321
             \`\`\`
 
-            > 💡 **Note:** PR images are tagged as \`pr-<number>\` and only built for \`linux/amd64\` to speed up CI.
-            > Production images (\`latest\`, version tags) are multi-platform (\`linux/amd64\`, \`linux/arm64\`).
+            > 💡 **Note:** PR images are tagged as \`pr-<number>\` and built for both \`linux/amd64\` and \`linux/arm64\`.
+            > Production images (\`latest\`, version tags) use the same multi-platform set.
 
             ---
             📦 View in [GitHub Packages](https://github.com/${{ github.repository }}/pkgs/container/gitea-mirror)`;
@@ -178,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
@@ -192,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
@@ -206,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
@@ -219,9 +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,303 @@
+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: |
+          # Retry pulls before `up` — Docker Hub occasionally returns
+          # "context deadline exceeded" on the first attempt. Pulling
+          # separately also keeps the failure mode obvious if it persists.
+          echo "Pulling images..."
+          for attempt in 1 2 3; do
+            if docker compose -f tests/e2e/docker-compose.e2e.yml pull --quiet; then
+              echo "✓ Images pulled (attempt $attempt)"
+              break
+            fi
+            if [ "$attempt" -eq 3 ]; then
+              echo "ERROR: docker compose pull failed after 3 attempts"
+              exit 1
+            fi
+            sleep_s=$((attempt * 10))
+            echo "Pull attempt $attempt failed, retrying in ${sleep_s}s..."
+            sleep "$sleep_s"
+          done
+
+          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

@@ -0,0 +1,65 @@
+name: Nix Flake Check
+
+on:
+  push:
+    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:
+    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@ef8a148080ab6020fd15196c2084a2eea5ff2d25 # v22
+
+      - name: Setup Nix Cache
+        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: Fail if committed bun.nix is out of date
+        run: |
+          if ! git diff --quiet -- bun.nix; then
+            echo '::error file=bun.nix::bun.nix is out of date! Run `nix run github:nix-community/bun2nix -- -o bun.nix` (requires Nix) and commit the result.'
+            git diff --stat -- bun.nix
+            exit 1
+          fi
+
+      - name: Check flake
+        run: nix flake check --accept-flake-config
+
+      - name: Show flake info
+        run: nix flake show --accept-flake-config
+
+      - 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

@@ -32,3 +32,24 @@ certs/*.pem
 certs/*.cer
 !certs/README.md
 
+# Nix build artifacts
+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/
+.playwright-mcp/

CLAUDE.md

@@ -2,255 +2,316 @@
 
 This file provides guidance to Claude Code (claude.ai/code) when working with code in this repository.
 
-DONT HALLUCIATE THINGS. IF YOU DONT KNOW LOOK AT THE CODE OR ASK FOR DOCS
-
-NEVER MENTION CLAUDE CODE ANYWHERE.
-
 ## Project Overview
 
-Gitea Mirror is a web application that automatically mirrors repositories from GitHub to self-hosted Gitea instances. It uses Astro for SSR, React for UI, SQLite for data storage, and Bun as the JavaScript runtime.
+Gitea Mirror is a self-hosted web application that automatically mirrors repositories from GitHub to Gitea instances. It's built with Astro (SSR mode), React, and runs on the Bun runtime with SQLite for data persistence.
 
-## Essential Commands
+**Key capabilities:**
+- Mirrors public, private, and starred GitHub repos to Gitea
+- Supports metadata mirroring (issues, PRs as issues, labels, milestones, releases, wiki)
+- Git LFS support
+- Multiple authentication methods (email/password, OIDC/SSO, header auth)
+- Scheduled automatic syncing with configurable intervals
+- Auto-discovery of new repos and cleanup of deleted repos
+- Multi-user support with encrypted token storage (AES-256-GCM)
+
+## Development Commands
+
+### Setup and Installation
+```bash
+# Install dependencies
+bun install
+
+# Initialize database (first time setup)
+bun run setup
+
+# Clean start (reset database)
+bun run dev:clean
+```
 
 ### Development
 ```bash
-bun run dev          # Start development server (port 3000)
-bun run build        # Build for production
-bun run preview      # Preview production build
+# Start development server (http://localhost:4321)
+bun run dev
+
+# Build for production
+bun run build
+
+# Preview production build
+bun run preview
+
+# Start production server
+bun run start
 ```
 
 ### Testing
 ```bash
-bun test             # Run all tests
-bun test:watch       # Run tests in watch mode
-bun test:coverage    # Run tests with coverage
+# Run all tests
+bun test
+
+# Run tests in watch mode
+bun test:watch
+
+# Run tests with coverage
+bun test:coverage
 ```
 
+**Test configuration:**
+- Test runner: Bun's built-in test runner (configured in `bunfig.toml`)
+- Setup file: `src/tests/setup.bun.ts` (auto-loaded via bunfig.toml)
+- Timeout: 5000ms default
+- Tests are colocated with source files using `*.test.ts` pattern
+
 ### Database Management
 ```bash
-bun run init-db      # Initialize database
-bun run reset-users  # Reset user accounts (development)
-bun run cleanup-db   # Remove database files
+# Database operations via Drizzle
+bun run db:generate    # Generate migrations from schema
+bun run db:migrate     # Run migrations
+bun run db:push        # Push schema changes directly
+bun run db:studio      # Open Drizzle Studio (database GUI)
+bun run db:check       # Check schema consistency
+
+# Database utilities via custom scripts
+bun run manage-db init       # Initialize database
+bun run manage-db check      # Check database health
+bun run manage-db fix        # Fix database issues
+bun run manage-db reset-users # Reset all users
+bun run cleanup-db           # Delete database file
 ```
 
-### Production
+### Utility Scripts
 ```bash
-bun run start        # Start production server
+# Recovery and diagnostic scripts
+bun run startup-recovery       # Recover from crashes
+bun run startup-recovery-force # Force recovery
+bun run test-recovery          # Test recovery mechanism
+bun run test-shutdown          # Test graceful shutdown
+
+# Environment configuration
+bun run startup-env-config     # Load config from env vars
 ```
 
-## Architecture & Key Concepts
+## Architecture
 
-### Technology Stack
-- **Frontend**: Astro (SSR) + React + Tailwind CSS v4 + Shadcn UI
-- **Backend**: Bun runtime + SQLite + Drizzle ORM
-- **APIs**: GitHub (Octokit) and Gitea APIs
-- **Auth**: Better Auth with email/password, SSO, and OIDC provider support
+### Tech Stack
+- **Frontend:** Astro v5 (SSR mode) + React v19 + Shadcn UI + Tailwind CSS v4
+- **Backend:** Astro API routes (Node adapter, standalone mode)
+- **Runtime:** Bun (>=1.2.9)
+- **Database:** SQLite via Drizzle ORM
+- **Authentication:** Better Auth (session-based)
+- **APIs:** GitHub (Octokit with throttling plugin), Gitea REST API
 
-### Project Structure
-- `/src/pages/api/` - API endpoints (Astro API routes)
-- `/src/components/` - React components organized by feature
-- `/src/lib/db/` - Database queries and schema (Drizzle ORM)
-- `/src/hooks/` - Custom React hooks for data fetching
-- `/data/` - SQLite database storage location
+### Directory Structure
+
+```
+src/
+├── components/          # React components (UI, features)
+│   ├── ui/             # Shadcn UI components
+│   ├── repositories/   # Repository management components
+│   ├── organizations/  # Organization management components
+│   └── ...
+├── pages/              # Astro pages and API routes
+│   ├── api/            # API endpoints (Better Auth integration)
+│   │   ├── auth/       # Authentication endpoints
+│   │   ├── github/     # GitHub operations
+│   │   ├── gitea/      # Gitea operations
+│   │   ├── sync/       # Mirror sync operations
+│   │   ├── job/        # Job management
+│   │   └── ...
+│   └── *.astro         # Page components
+├── lib/                # Core business logic
+│   ├── db/             # Database (Drizzle ORM)
+│   │   ├── schema.ts   # Database schema with Zod validation
+│   │   ├── index.ts    # Database instance and table exports
+│   │   └── adapter.ts  # Better Auth SQLite adapter
+│   ├── github.ts       # GitHub API client (Octokit)
+│   ├── gitea.ts        # Gitea API client
+│   ├── gitea-enhanced.ts # Enhanced Gitea operations (metadata)
+│   ├── scheduler-service.ts # Automatic mirroring scheduler
+│   ├── cleanup-service.ts   # Activity log cleanup
+│   ├── repository-cleanup-service.ts # Orphaned repo cleanup
+│   ├── auth.ts         # Better Auth configuration
+│   ├── config.ts       # Configuration management
+│   ├── helpers.ts      # Mirror job creation
+│   ├── utils/          # Utility functions
+│   │   ├── encryption.ts        # AES-256-GCM token encryption
+│   │   ├── config-encryption.ts # Config token encryption
+│   │   ├── duration-parser.ts   # Parse intervals (e.g., "8h", "30m")
+│   │   ├── concurrency.ts       # Concurrency control utilities
+│   │   └── mirror-strategies.ts # Mirror strategy logic
+│   └── ...
+├── types/              # TypeScript type definitions
+├── tests/              # Test utilities and setup
+└── middleware.ts       # Astro middleware (auth, session)
+
+scripts/                # Utility scripts
+├── manage-db.ts        # Database management CLI
+├── startup-recovery.ts # Crash recovery
+└── ...
+```
 
 ### Key Architectural Patterns
 
-1. **API Routes**: All API endpoints follow the pattern `/api/[resource]/[action]` and use `createSecureErrorResponse` for consistent error handling:
-```typescript
-import { createSecureErrorResponse } from '@/lib/utils/error-handler';
+#### 1. Database Schema and Validation
+- **Location:** `src/lib/db/schema.ts`
+- **Pattern:** Drizzle ORM tables + Zod schemas for validation
+- **Key tables:**
+  - `configs` - User configuration (GitHub/Gitea settings, mirror options)
+  - `repositories` - Tracked repositories with metadata
+  - `organizations` - GitHub organizations with destination overrides
+  - `mirrorJobs` - Mirror job queue and history
+  - `activities` - Activity log for dashboard
+  - `user`, `session`, `account` - Better Auth tables
 
-export async function POST({ request }: APIContext) {
-  try {
-    // Implementation
-  } catch (error) {
-    return createSecureErrorResponse(error);
-  }
-}
-```
+**Important:** All config tokens (GitHub/Gitea) are encrypted at rest using AES-256-GCM. Use helper functions from `src/lib/utils/config-encryption.ts` to decrypt.
 
-2. **Database Queries**: Located in `/src/lib/db/queries/` organized by domain (users, repositories, etc.)
+#### 2. Mirror Job System
+- **Location:** `src/lib/helpers.ts` (createMirrorJob)
+- **Flow:**
+  1. User triggers mirror via API endpoint
+  2. `createMirrorJob()` creates job record with status "pending"
+  3. Job processor (in API routes) performs GitHub → Gitea operations
+  4. Job status updated throughout: "mirroring" → "success"/"failed"
+  5. Events published via SSE for real-time UI updates
 
-3. **Real-time Updates**: Server-Sent Events (SSE) endpoint at `/api/events` for live dashboard updates
+#### 3. GitHub ↔ Gitea Mirroring
+- **GitHub Client:** `src/lib/github.ts` - Octokit with rate limit tracking
+- **Gitea Client:** `src/lib/gitea.ts` - Basic repo operations
+- **Enhanced Gitea:** `src/lib/gitea-enhanced.ts` - Metadata mirroring (issues, PRs, releases)
 
-4. **Authentication System**: 
-   - Built on Better Auth library
-   - Three authentication methods:
-     - Email & Password (traditional auth)
-     - SSO (authenticate via external OIDC providers)
-     - OIDC Provider (act as OIDC provider for other apps)
-   - Session-based authentication with secure cookies
-   - First user signup creates admin account
-   - Protected routes use Better Auth session validation
+**Mirror strategies (configured per user):**
+- `preserve` - Maintain GitHub org structure in Gitea
+- `single-org` - All repos into one Gitea org
+- `flat-user` - All repos under user account
+- `mixed` - Personal repos in one org, org repos preserve structure
 
-5. **Mirror Process**:
-   - Discovers repos from GitHub (user/org)
-   - Creates/updates mirror in Gitea
-   - Tracks status in database
-   - Supports scheduled automatic mirroring
+**Metadata mirroring:**
+- Issues transferred with comments, labels, assignees
+- PRs converted to issues (Gitea API limitation - cannot create PRs)
+  - Tagged with "pull-request" label
+  - Title prefixed with `[PR #number] [STATUS]`
+  - Body includes commit history, file changes, merge status
+- Releases mirrored with assets
+- Labels and milestones preserved
+- Wiki content cloned if enabled
+- **Sequential processing:** Issues/PRs mirrored one at a time to prevent out-of-order creation (see `src/lib/gitea-enhanced.ts`)
 
-6. **Mirror Strategies**: Four ways to organize repositories in Gitea:
-   - **preserve**: Maintains GitHub structure (default)
-     - Organization repos → Same organization name in Gitea
-     - Personal repos → Under your Gitea username
-   - **single-org**: All repos go to one organization
-     - All repos → Single configured organization
-   - **flat-user**: All repos go under user account
-     - All repos → Under your Gitea username
-   - **mixed**: Hybrid approach
-     - Organization repos → Preserve structure
-     - Personal repos → Single configured organization
-   - Starred repos always go to separate organization (starredReposOrg, default: "starred")
-   - Routing logic in `getGiteaRepoOwner()` function
+#### 4. Scheduler Service
+- **Location:** `src/lib/scheduler-service.ts`
+- **Features:**
+  - Cron-based or interval-based scheduling (uses `duration-parser.ts`)
+  - Auto-start on boot when `SCHEDULE_ENABLED=true` or `GITEA_MIRROR_INTERVAL` is set
+  - Auto-import new GitHub repos
+  - Auto-cleanup orphaned repos (archive or delete)
+  - Respects per-repo mirror intervals (not Gitea's default 24h)
+- **Concurrency control:** Uses `src/lib/utils/concurrency.ts` for batch processing
 
-### Database Schema (SQLite)
-- `users` - User accounts and authentication
-- `configs` - GitHub/Gitea connection settings
-- `repositories` - Repository mirror status and metadata
-- `organizations` - Organization structure preservation
-- `mirror_jobs` - Scheduled mirror operations
-- `events` - Activity log and notifications
+#### 5. Authentication System
+- **Location:** `src/lib/auth.ts`, `src/lib/auth-client.ts`
+- **Better Auth integration:**
+  - Email/password (always enabled)
+  - OIDC/SSO providers (configurable via UI)
+  - Header authentication for reverse proxies (Authentik, Authelia)
+- **Session management:** Cookie-based, validated in Astro middleware
+- **User helpers:** `src/lib/utils/auth-helpers.ts`
 
-### Testing Approach
-- Uses Bun's native test runner (`bun:test`)
-- Test files use `.test.ts` or `.test.tsx` extension
-- Setup file at `/src/tests/setup.bun.ts`
-- Mock utilities available for API testing.
+#### 6. Environment Configuration
+- **Startup:** `src/lib/env-config-loader.ts` + `scripts/startup-env-config.ts`
+- **Pattern:** Environment variables can pre-configure settings, but users can override via web UI
+- **Encryption:** `ENCRYPTION_SECRET` for tokens, `BETTER_AUTH_SECRET` for sessions
 
-### Development Tips
-- Environment variables in `.env` (copy from `.env.example`)
-- BETTER_AUTH_SECRET required for session signing
-- Database auto-initializes on first run
-- Use `bun run dev:clean` for fresh database start
-- Tailwind CSS v4 configured with Vite plugin
+#### 7. Real-time Updates
+- **Events:** `src/lib/events.ts` + `src/lib/events/realtime.ts`
+- **Pattern:** Server-Sent Events (SSE) for live dashboard updates
+- **Endpoints:** `/api/sse` - client subscribes to job/repo events
 
-### Authentication Setup
-- **Better Auth** handles all authentication
-- Configuration in `/src/lib/auth.ts` (server) and `/src/lib/auth-client.ts` (client)
-- Auth endpoints available at `/api/auth/*`
-- SSO providers configured through the web UI
-- OIDC provider functionality for external applications
+### Testing Patterns
 
-### Common Tasks
+**Unit tests:**
+- Colocated with source: `filename.test.ts` alongside `filename.ts`
+- Use Bun's built-in assertions and mocking
+- Mock external APIs (GitHub, Gitea) using `src/tests/mock-fetch.ts`
 
-**Adding a new API endpoint:**
-1. Create file in `/src/pages/api/[resource]/[action].ts`
-2. Use `createSecureErrorResponse` for error handling
-3. Add corresponding database query in `/src/lib/db/queries/`
-4. Update types in `/src/types/` if needed
+**Integration tests:**
+- Located in `src/tests/`
+- Test database operations with in-memory SQLite
+- Example: `src/lib/db/index.test.ts`
 
-**Adding a new component:**
-1. Create in appropriate `/src/components/[feature]/` directory
-2. Use Shadcn UI components from `/src/components/ui/`
-3. Follow existing naming patterns (e.g., `RepositoryCard`, `ConfigTabs`)
+**Test utilities:**
+- `src/tests/setup.bun.ts` - Global test setup (loaded via bunfig.toml)
+- `src/tests/mock-fetch.ts` - Fetch mocking utilities
 
-**Modifying database schema:**
-1. Update schema in `/src/lib/db/schema.ts`
-2. Run `bun run init-db` to recreate database
-3. Update related queries in `/src/lib/db/queries/`
+### Important Development Notes
 
-## Configuration Options
+1. **Path Aliases:** Use `@/` for imports (configured in `tsconfig.json`)
+   ```typescript
+   import { db } from '@/lib/db';
+   ```
 
-### GitHub Configuration (UI Fields)
+2. **Token Encryption:** Always use encryption helpers when dealing with tokens:
+   ```typescript
+   import { getDecryptedGitHubToken, getDecryptedGiteaToken } from '@/lib/utils/config-encryption';
+   ```
 
-#### Basic Settings (`githubConfig`)
-- **username**: GitHub username
-- **token**: GitHub personal access token (requires repo and admin:org scopes)
-- **privateRepositories**: Include private repositories
-- **mirrorStarred**: Mirror starred repositories
+3. **API Route Pattern:** Astro API routes in `src/pages/api/` should:
+   - Check authentication via Better Auth
+   - Validate input with Zod schemas
+   - Handle errors gracefully
+   - Return JSON responses
 
-### Gitea Configuration (UI Fields)
-- **url**: Gitea instance URL
-- **username**: Gitea username
-- **token**: Gitea access token
-- **organization**: Destination organization (for single-org/mixed strategies)
-- **starredReposOrg**: Organization for starred repositories (default: "starred")
-- **visibility**: Organization visibility - "public", "private", "limited"
-- **mirrorStrategy**: Repository organization strategy (set via UI)
-- **preserveOrgStructure**: Automatically set based on mirrorStrategy
+4. **Database Migrations:**
+   - Schema changes: Update `src/lib/db/schema.ts`
+   - Generate migration: `bun run db:generate`
+   - Review generated SQL in `drizzle/` directory
+   - Apply: `bun run db:migrate` (or `db:push` for dev)
 
-### Schedule Configuration (`scheduleConfig`)
-- **enabled**: Enable automatic mirroring (default: false)
-- **interval**: Cron expression or seconds (default: "0 2 * * *" - 2 AM daily)
-- **concurrent**: Allow concurrent mirror operations (default: false)
-- **batchSize**: Number of repos to process in parallel (default: 10)
+5. **Concurrency Control:**
+   - Use utilities from `src/lib/utils/concurrency.ts` for batch operations
+   - Respect rate limits (GitHub: 5000 req/hr authenticated, Gitea: varies)
+   - Issue/PR mirroring is sequential to maintain chronological order
 
-### Database Cleanup Configuration (`cleanupConfig`)
-- **enabled**: Enable automatic cleanup (default: false)
-- **retentionDays**: Days to keep events (stored as seconds internally)
+6. **Duration Parsing:**
+   - Use `parseInterval()` from `src/lib/utils/duration-parser.ts`
+   - Supports: "30m", "8h", "24h", "7d", cron expressions, or milliseconds
 
-### Mirror Options (UI Fields)
-- **mirrorReleases**: Mirror GitHub releases to Gitea
-- **mirrorLFS**: Mirror Git LFS (Large File Storage) objects
-  - Requires LFS enabled on Gitea server (LFS_START_SERVER = true)
-  - Requires Git v2.1.2+ on server
-- **mirrorMetadata**: Enable metadata mirroring (master toggle)
-- **metadataComponents** (only available when mirrorMetadata is enabled):
-  - **issues**: Mirror issues
-  - **pullRequests**: Mirror pull requests  
-  - **labels**: Mirror labels
-  - **milestones**: Mirror milestones
-  - **wiki**: Mirror wiki content
+7. **Graceful Shutdown:**
+   - Services implement cleanup handlers (see `src/lib/shutdown-manager.ts`)
+   - Recovery system in `src/lib/recovery.ts` handles interrupted jobs
 
-### Advanced Options (UI Fields)
-- **skipForks**: Skip forked repositories (default: false)
-- **starredCodeOnly**: Skip issues for starred repositories (default: false) - enables "Lightweight mode" for starred repos
+## Common Development Workflows
 
-### Repository Statuses
-Repositories can have the following statuses:
-- **imported**: Repository discovered from GitHub
-- **mirroring**: Currently being mirrored to Gitea
-- **mirrored**: Successfully mirrored
-- **syncing**: Repository being synchronized
-- **synced**: Successfully synchronized
-- **failed**: Mirror/sync operation failed
-- **skipped**: Skipped due to filters or conditions
-- **ignored**: User explicitly marked to ignore (won't be mirrored/synced)
-- **deleting**: Repository being deleted
-- **deleted**: Repository deleted
+### Adding a new mirror option
+1. Update Zod schema in `src/lib/db/schema.ts` (e.g., `giteaConfigSchema`)
+2. Update TypeScript types in `src/types/config.ts`
+3. Add UI control in settings page component
+4. Update API handler in `src/pages/api/config/`
+5. Implement logic in `src/lib/gitea.ts` or `src/lib/gitea-enhanced.ts`
 
-### Scheduling and Synchronization (Issue #72 Fixes)
+### Debugging mirror failures
+1. Check mirror jobs: `bun run db:studio` → `mirrorJobs` table
+2. Review activity logs: Dashboard → Activity tab
+3. Check console logs for API errors (GitHub/Gitea rate limits, auth issues)
+4. Use diagnostic scripts: `bun run test-recovery`
 
-#### Fixed Issues
-1. **Mirror Interval Bug**: Added `mirror_interval` parameter to Gitea API calls when creating mirrors (previously defaulted to 24h)
-2. **Auto-Discovery**: Scheduler now automatically discovers and imports new GitHub repositories
-3. **Interval Updates**: Sync operations now update existing mirrors' intervals to match configuration
-4. **Repository Cleanup**: Integrated automatic cleanup of orphaned repositories (repos removed from GitHub)
+### Adding authentication provider
+1. Update Better Auth config in `src/lib/auth.ts`
+2. Add provider configuration UI in settings
+3. Test with `src/tests/test-gitea-auth.ts` patterns
+4. Update documentation in `docs/SSO-OIDC-SETUP.md`
 
-#### Environment Variables for Auto-Import
-- **AUTO_IMPORT_REPOS**: Set to `false` to disable automatic repository discovery (default: enabled)
+## Docker Deployment
 
-#### How Scheduling Works
-- **Scheduler Service**: Runs every minute to check for scheduled tasks
-- **Sync Interval**: Configured via `GITEA_MIRROR_INTERVAL` or UI (e.g., "8h", "30m", "1d")
-- **Auto-Import**: Checks GitHub for new repositories during each scheduled sync
-- **Auto-Cleanup**: Removes repositories that no longer exist in GitHub (if enabled)
-- **Mirror Interval Update**: Updates Gitea's internal mirror interval during sync operations
+- **Dockerfile:** Multi-stage build (bun base → build → production)
+- **Entrypoint:** `docker-entrypoint.sh` - handles CA certs, user permissions, database init
+- **Compose files:**
+  - `docker-compose.alt.yml` - Quick start (pre-built image, minimal config)
+  - `docker-compose.yml` - Full setup (build from source, all env vars)
+  - `docker-compose.dev.yml` - Development with hot reload
 
-### Authentication Configuration
+## Additional Resources
 
-#### SSO Provider Configuration
-- **issuerUrl**: OIDC issuer URL (e.g., https://accounts.google.com)
-- **domain**: Email domain for this provider
-- **providerId**: Unique identifier for the provider
-- **clientId**: OAuth client ID from provider
-- **clientSecret**: OAuth client secret from provider
-- **authorizationEndpoint**: OAuth authorization URL (auto-discovered if supported)
-- **tokenEndpoint**: OAuth token exchange URL (auto-discovered if supported)
-- **jwksEndpoint**: JSON Web Key Set URL (optional, auto-discovered)
-- **userInfoEndpoint**: User information endpoint (optional, auto-discovered)
-
-#### OIDC Provider Settings (for external apps)
-- **allowedRedirectUris**: Comma-separated list of allowed redirect URIs
-- **clientId**: Generated client ID for the application
-- **clientSecret**: Generated client secret for the application
-- **scopes**: Available scopes (openid, profile, email)
-
-#### Environment Variables
-- **BETTER_AUTH_SECRET**: Secret key for signing sessions (required)
-- **BETTER_AUTH_URL**: Base URL for authentication (default: http://localhost:4321)
-
-## Security Guidelines
-
-- **Confidentiality Guidelines**:
-  - Dont ever say Claude Code or generated with AI anyhwere.
-- Never commit without the explicict ask
+- **Environment Variables:** See `docs/ENVIRONMENT_VARIABLES.md` for complete list
+- **Development Workflow:** See `docs/DEVELOPMENT_WORKFLOW.md`
+- **SSO Setup:** See `docs/SSO-OIDC-SETUP.md`
+- **Contributing:** See `CONTRIBUTING.md` for code guidelines and scope
+- **Graceful Shutdown:** See `docs/GRACEFUL_SHUTDOWN.md` for crash recovery details

Dockerfile

@@ -1,51 +1,91 @@
 # syntax=docker/dockerfile:1.4
 
-FROM oven/bun:1.2.23-alpine AS base
+FROM oven/bun:1.3.14-debian@sha256:9dba1a1b43ce28c9d7931bfc4eb00feb63b0114720a0277a8f939ae4dfc9db6f AS base
 WORKDIR /app
-RUN apk add --no-cache libc6-compat python3 make g++ gcc wget sqlite openssl ca-certificates
+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/*
 
 # ----------------------------
-FROM base AS deps
+FROM base AS builder
 COPY package.json ./
 COPY bun.lock* ./
 RUN bun install --frozen-lockfile
 
-# ----------------------------
-FROM deps AS builder
 COPY . .
 RUN bun run build
 RUN mkdir -p dist/scripts && \
-    for script in scripts/*.ts; do \
-      bun build "$script" --target=bun --outfile=dist/scripts/$(basename "${script%.ts}.js"); \
-    done
+  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
 
 # ----------------------------
-FROM deps AS pruner
-RUN bun install --production --frozen-lockfile
+FROM base AS pruner
+COPY package.json ./
+COPY bun.lock* ./
+RUN bun install --production --omit=peer --frozen-lockfile
 
 # ----------------------------
-FROM base AS runner
+# 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 ./scripts
+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 && \
-    chmod +x ./docker-entrypoint.sh && \
-    mkdir -p /app/data && \
-    addgroup --system --gid 1001 nodejs && \
-    adduser --system --uid 1001 gitea-mirror && \
-    chown -R gitea-mirror:nodejs /app/data && \
-    chown -R gitea-mirror:nodejs /app/certs
+  chmod +x ./docker-entrypoint.sh && \
+  mkdir -p /app/data && \
+  groupadd --system --gid 1001 nodejs && \
+  useradd --system --uid 1001 --gid 1001 --create-home --home-dir /home/gitea-mirror gitea-mirror && \
+  chown -R gitea-mirror:nodejs /app/data && \
+  chown -R gitea-mirror:nodejs /app/certs && \
+  chown -R gitea-mirror:nodejs /home/gitea-mirror
 
 USER gitea-mirror
 
@@ -53,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"]
+ENTRYPOINT ["./docker-entrypoint.sh"]

NIX.md

@@ -0,0 +1,189 @@
+# Nix Deployment Quick Reference
+
+## TL;DR
+
+```bash
+# From GitHub (no clone needed!)
+nix run --extra-experimental-features 'nix-command flakes' github:RayLabsHQ/gitea-mirror
+
+# Or from local clone
+nix run --extra-experimental-features 'nix-command flakes' .#gitea-mirror
+```
+
+Secrets auto-generate, database auto-initializes, and the web UI starts at http://localhost:4321.
+
+**Note:** If you have flakes enabled in your nix config, you can omit `--extra-experimental-features 'nix-command flakes'`
+
+---
+
+## Installation Options
+
+### 1. Run Without Installing (from GitHub)
+```bash
+# Latest version from main branch
+nix run --extra-experimental-features 'nix-command flakes' github:RayLabsHQ/gitea-mirror
+
+# Pin to specific version
+nix run github:RayLabsHQ/gitea-mirror/vX.Y.Z
+```
+
+### 2. Install to Profile
+```bash
+# Install from GitHub
+nix profile install --extra-experimental-features 'nix-command flakes' github:RayLabsHQ/gitea-mirror
+
+# Run the installed binary
+gitea-mirror
+```
+
+### 3. Use Local Clone
+```bash
+# Clone and run
+git clone https://github.com/RayLabsHQ/gitea-mirror.git
+cd gitea-mirror
+nix run --extra-experimental-features 'nix-command flakes' .#gitea-mirror
+```
+
+### 4. NixOS System Service
+```nix
+# configuration.nix
+{
+  inputs.gitea-mirror.url = "github:RayLabsHQ/gitea-mirror";
+
+  services.gitea-mirror = {
+    enable = true;
+    betterAuthUrl = "https://mirror.example.com";  # For production
+    openFirewall = true;
+  };
+}
+```
+
+### 5. Development (Local Clone)
+```bash
+nix develop --extra-experimental-features 'nix-command flakes'
+# or
+direnv allow  # Handles experimental features automatically
+```
+
+---
+
+## Enable Flakes Permanently (Recommended)
+
+To avoid typing `--extra-experimental-features` every time, add to `~/.config/nix/nix.conf`:
+```
+experimental-features = nix-command flakes
+```
+
+---
+
+## What Gets Auto-Generated?
+
+On first run, the wrapper automatically:
+
+1. Creates `~/.local/share/gitea-mirror/` (or `$DATA_DIR`)
+2. Generates `BETTER_AUTH_SECRET` → `.better_auth_secret`
+3. Generates `ENCRYPTION_SECRET` → `.encryption_secret`
+4. Initializes SQLite database
+5. Runs startup recovery and repair scripts
+6. Starts the application
+
+---
+
+## Key Commands
+
+```bash
+# Database management
+gitea-mirror-db init      # Initialize database
+gitea-mirror-db check     # Health check
+gitea-mirror-db fix       # Fix issues
+
+# Development (add --extra-experimental-features 'nix-command flakes' if needed)
+nix develop               # Enter dev shell
+nix build                 # Build package
+nix flake check           # Validate flake
+nix flake update          # Update dependencies
+```
+
+---
+
+## Environment Variables
+
+All vars from `docker-compose.alt.yml` are supported:
+
+```bash
+DATA_DIR="$HOME/.local/share/gitea-mirror"
+PORT=4321
+HOST="0.0.0.0"
+BETTER_AUTH_URL="http://localhost:4321"
+
+# Secrets (auto-generated if not set)
+BETTER_AUTH_SECRET=auto-generated
+ENCRYPTION_SECRET=auto-generated
+
+# Concurrency (for perfect ordering, set both to 1)
+MIRROR_ISSUE_CONCURRENCY=3
+MIRROR_PULL_REQUEST_CONCURRENCY=5
+```
+
+---
+
+## NixOS Module Options
+
+```nix
+services.gitea-mirror = {
+  enable = true;
+  package = ...;                        # Override package
+  dataDir = "/var/lib/gitea-mirror";   # Data location
+  user = "gitea-mirror";               # Service user
+  group = "gitea-mirror";              # Service group
+  host = "0.0.0.0";                    # Bind address
+  port = 4321;                         # Listen port
+  betterAuthUrl = "http://...";        # External URL
+  betterAuthTrustedOrigins = "...";    # CORS origins
+  mirrorIssueConcurrency = 3;          # Concurrency
+  mirrorPullRequestConcurrency = 5;    # Concurrency
+  environmentFile = null;              # Optional secrets file
+  openFirewall = true;                 # Open firewall
+};
+```
+
+---
+
+## Comparison: Docker vs Nix
+
+| Feature | Docker | Nix |
+|---------|--------|-----|
+| **Config Required** | BETTER_AUTH_SECRET | None (auto-generated) |
+| **Startup** | `docker-compose up` | `nix run .#gitea-mirror` |
+| **Service** | Docker daemon | systemd (NixOS) |
+| **Updates** | `docker pull` | `nix flake update` |
+| **Reproducible** | Image-based | Hash-based |
+
+---
+
+## Full Documentation
+
+- **[docs/NIX_DEPLOYMENT.md](docs/NIX_DEPLOYMENT.md)** - Complete deployment guide
+  - NixOS module configuration
+  - Home Manager integration
+  - Production deployment examples
+  - Migration from Docker
+  - Troubleshooting guide
+
+- **[docs/NIX_DISTRIBUTION.md](docs/NIX_DISTRIBUTION.md)** - Distribution guide for maintainers
+  - How users consume the package
+  - CI build caching
+  - Releasing new versions
+  - Submitting to nixpkgs
+
+---
+
+## Key Features
+
+- **Zero-config deployment** - Runs immediately without setup
+- **Auto-secret generation** - Secure secrets created and persisted
+- **Startup recovery** - Handles interrupted jobs automatically
+- **Graceful shutdown** - Proper signal handling
+- **Health checks** - Built-in monitoring support
+- **Security hardening** - NixOS module includes systemd protections
+- **Docker parity** - Same behavior as `docker-compose.alt.yml`

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>
@@ -10,10 +10,6 @@
   </p>
 </p>
 
-> [!IMPORTANT]
-> **Upgrading to v3?** v3 requires a fresh start with a new data volume. Please read the [Upgrade Guide](UPGRADE.md) for instructions.
-
-
 ## 🚀 Quick Start
 
 ```bash
@@ -23,7 +19,9 @@ 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!
+
+📖 **[Full documentation](https://gitea-mirror.raylabs.io/docs/)** - quickstart, deployment, configuration, notifications, SSO and more. Offline copies live in [`docs/`](docs/).
 
 <p align="center">
   <img src=".github/assets/dashboard.png" alt="Dashboard" width="600" />
@@ -32,18 +30,21 @@ 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
-- 📝 **Metadata mirroring** - Issues, pull requests (as issues), labels, milestones, wiki
+- 📝 **Metadata mirroring** - Issues, pull requests (as issues), labels, milestones, releases, wiki
 - 🚫 **Repository ignore** - Mark specific repos to skip
-- 🔐 Secure authentication with Better Auth (email/password, SSO, OIDC)
+- 🔐 Secure authentication with Better Auth (email/password, SSO, OIDC, header auth)
+- 🔔 **[Notifications](docs/NOTIFICATIONS.md)** - ntfy, Apprise, Gotify, or any webhook with signed payloads
 - 📊 Real-time dashboard with activity logs
 - ⏱️ Scheduled automatic mirroring with configurable intervals
-- 🔄 **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+)
+- 🔄 **Auto-discovery** - Automatically import new GitHub repositories
+- 🧹 **Repository cleanup** - Auto-remove repos deleted from GitHub
+- 🎯 **Proper mirror intervals** - Respects configured sync intervals
+- 🛡️ **[Force-push protection](docs/FORCE_PUSH_PROTECTION.md)** - Smart detection with backup-on-demand or block-and-approve modes
 - 🗑️ Automatic database cleanup with configurable retention
 - 🐳 Dockerized with multi-arch support (AMD64/ARM64)
 
@@ -51,7 +52,7 @@ First user signup becomes admin. Configure GitHub and Gitea through the web inte
 
 <div align="center">
   <img src=".github/assets/repositories.png" alt="Repositories" width="600" />
-  <img src=".github/assets/repositories_mobile.png" alt="Rrepositories Mobile" width="200" />
+  <img src=".github/assets/repositories_mobile.png" alt="Repositories Mobile" width="200" />
 </div>
 
 <div align="center">
@@ -116,7 +117,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
@@ -154,6 +155,38 @@ bash -c "$(curl -fsSL https://raw.githubusercontent.com/community-scripts/Proxmo
 
 See the [Proxmox VE Community Scripts](https://community-scripts.github.io/ProxmoxVE/scripts?id=gitea-mirror) for more details.
 
+### Nix/NixOS
+
+Zero-configuration deployment with Nix:
+
+```bash
+# Run immediately - no setup needed!
+nix run --extra-experimental-features 'nix-command flakes' github:RayLabsHQ/gitea-mirror
+
+# Or build and run locally
+nix build --extra-experimental-features 'nix-command flakes'
+./result/bin/gitea-mirror
+
+# Or install to profile
+nix profile install --extra-experimental-features 'nix-command flakes' github:RayLabsHQ/gitea-mirror
+gitea-mirror
+```
+
+**NixOS users** - add to your configuration:
+```nix
+{
+  inputs.gitea-mirror.url = "github:RayLabsHQ/gitea-mirror";
+
+  services.gitea-mirror = {
+    enable = true;
+    betterAuthUrl = "https://mirror.example.com";
+    openFirewall = true;
+  };
+}
+```
+
+Secrets auto-generate, database auto-initializes. See [NIX.md](NIX.md) for quick reference or [docs/NIX_DEPLOYMENT.md](docs/NIX_DEPLOYMENT.md) for full documentation.
+
 ### Manual Installation
 
 ```bash
@@ -170,31 +203,31 @@ 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**
    - Click edit buttons on organization cards to set custom destinations
    - Override individual repository destinations in the table view
-   - Starred repositories automatically go to a dedicated organization
+   - Starred repositories can go to a dedicated org or preserve source owner/org paths
 
 ## Advanced Features
 
 ### 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
@@ -214,7 +247,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!
 
@@ -225,7 +258,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
@@ -254,22 +287,87 @@ CLEANUP_DRY_RUN=false                 # Set to true to test without changes
 **Important Notes**:
 - **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/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)
+
+For existing pull-mirror repositories, changing the GitHub token in Gitea Mirror does not always update stored mirror credentials in Gitea/Forgejo for already-created repositories.
+
+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 so it is recreated with current credentials.
+
+### Re-sync Metadata After Changing Mirror Options
+
+If you enable metadata options (issues/PRs/labels/milestones/releases) after repositories were already mirrored:
+
+1. Go to **Repositories**, select the repositories, and click **Sync** to run a fresh sync pass.
+2. For a full metadata refresh, use **Re-run Metadata** on selected repositories. This clears metadata sync state for those repos and immediately starts Sync.
+3. If some repositories still miss metadata, reset metadata sync state in SQLite and sync again:
+
+```bash
+sqlite3 data/gitea-mirror.db "UPDATE repositories SET metadata = NULL;"
+```
+
+This clears per-repository metadata completion flags so the next sync can re-run metadata import steps.
+
+### Mirror Interval vs Gitea/Forgejo `MIN_INTERVAL`
+
+Gitea Mirror treats the interval configured in **Configuration** (or `GITEA_MIRROR_INTERVAL`) as the source of truth and applies it to mirrored repositories during sync.
+
+If your Gitea/Forgejo server has `mirror.MIN_INTERVAL` set to a higher value (for example `24h`) and Gitea Mirror is set lower (for example `8h`), sync/mirror operations can fail when updating mirror settings.
+
+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, as they will be overwritten on sync.
 
 ## Development
 
@@ -291,13 +389,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
@@ -307,6 +405,20 @@ bun run build
 - Never stored in plaintext
 - Secure cookie-based session management
 
+### Admin Password Recovery (CLI)
+If email delivery is not configured, an admin with server access can reset a user password from the command line:
+
+```bash
+bun run reset-password -- --email=user@example.com --new-password='new-secure-password'
+```
+
+What this does:
+- Updates the credential password hash for the matching user
+- Creates a credential account if one does not already exist
+- Invalidates all active sessions for that user (forces re-login)
+
+Use this only from trusted server/admin environments.
+
 ## Authentication
 
 Gitea Mirror supports multiple authentication methods. **Email/password authentication is the default and always enabled.**
@@ -330,6 +442,8 @@ Enable users to sign in with external identity providers like Google, Azure AD,
 https://your-domain.com/api/auth/sso/callback/{provider-id}
 ```
 
+Need help? The [SSO & OIDC guide](docs/SSO-OIDC-SETUP.md) now includes a working Authentik walkthrough plus troubleshooting tips. If you upgraded from a version earlier than v3.8.10 and see `TypeError … url.startsWith` after the callback, delete the old provider and add it again using the Discover button (see [#73](https://github.com/RayLabsHQ/gitea-mirror/issues/73) and [#122](https://github.com/RayLabsHQ/gitea-mirror/issues/122)).
+
 ### 3. Header Authentication (Reverse Proxy)
 Perfect for automatic authentication when using reverse proxies like Authentik, Authelia, or Traefik Forward Auth.
 
@@ -375,13 +489,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:
@@ -395,7 +509,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
 
@@ -403,22 +517,23 @@ 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
 
-<a href="https://www.star-history.com/#RayLabsHQ/gitea-mirror&Date">
+<a href="https://www.star-history.com/#RayLabsHQ/gitea-mirror&type=date&legend=bottom-right">
  <picture>
-   <source media="(prefers-color-scheme: dark)" srcset="https://api.star-history.com/svg?repos=RayLabsHQ/gitea-mirror&type=Date&theme=dark" />
-   <source media="(prefers-color-scheme: light)" srcset="https://api.star-history.com/svg?repos=RayLabsHQ/gitea-mirror&type=Date" />
-   <img alt="Star History Chart" src="https://api.star-history.com/svg?repos=RayLabsHQ/gitea-mirror&type=Date" />
+   <source media="(prefers-color-scheme: dark)" srcset="https://api.star-history.com/svg?repos=RayLabsHQ/gitea-mirror&type=date&theme=dark&legend=bottom-right" />
+   <source media="(prefers-color-scheme: light)" srcset="https://api.star-history.com/svg?repos=RayLabsHQ/gitea-mirror&type=date&legend=bottom-right" />
+   <img alt="Star History Chart" src="https://api.star-history.com/svg?repos=RayLabsHQ/gitea-mirror&type=date&legend=bottom-right" />
  </picture>
 </a>
 
 ## 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)

UPGRADE.md

@@ -1,74 +0,0 @@
-# Upgrade Guide
-
-## Upgrading to v3.0
-
-> **⚠️ IMPORTANT**: v3.0 requires a fresh start. There is no automated migration from v2.x to v3.0.
-
-### Why No Migration?
-
-v3.0 introduces fundamental changes to the application architecture:
-- **Authentication**: Switched from JWT to Better Auth
-- **Database**: Now uses Drizzle ORM with proper migrations
-- **Security**: All tokens are now encrypted
-- **Features**: Added SSO support and OIDC provider functionality
-
-Due to these extensive changes, we recommend starting fresh with v3.0 for the best experience.
-
-### Upgrade Steps
-
-1. **Stop your v2.x container**
-   ```bash
-   docker stop gitea-mirror
-   docker rm gitea-mirror
-   ```
-
-2. **Backup your v2.x data (optional)**
-   ```bash
-   # If you want to keep your v2 data for reference
-   docker run --rm -v gitea-mirror-data:/data -v $(pwd):/backup alpine tar czf /backup/gitea-mirror-v2-backup.tar.gz -C /data .
-   ```
-
-3. **Create a new volume for v3**
-   ```bash
-   docker volume create gitea-mirror-v3-data
-   ```
-
-4. **Run v3 with the new volume**
-   ```bash
-   docker run -d \
-     --name gitea-mirror \
-     -p 4321:4321 \
-     -v gitea-mirror-v3-data:/app/data \
-     -e BETTER_AUTH_SECRET=your-secret-key \
-     -e ENCRYPTION_SECRET=your-encryption-key \
-     arunavo4/gitea-mirror:latest
-   ```
-
-5. **Set up your configuration again**
-   - Navigate to http://localhost:4321
-   - Create a new admin account
-   - Re-enter your GitHub and Gitea credentials
-   - Configure your mirror settings
-
-### What Happens to My Existing Mirrors?
-
-Your existing mirrors in Gitea are **not affected**. The application will:
-- Recognize existing repositories when you re-import
-- Skip creating duplicates
-- Resume normal mirror operations
-
-### Environment Variable Changes
-
-v3.0 uses different environment variables:
-
-| v2.x | v3.0 | Notes |
-|------|------|-------|
-| `JWT_SECRET` | `BETTER_AUTH_SECRET` | Required for session management |
-| - | `ENCRYPTION_SECRET` | New - required for token encryption |
-
-### Need Help?
-
-If you have questions about upgrading:
-1. Check the [README](README.md) for v3 setup instructions
-2. Review your v2 configuration before upgrading
-3. Open an issue if you encounter problems

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/"

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,10 +30,19 @@ 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
+      - MIRROR_ISSUE_CONCURRENCY=${MIRROR_ISSUE_CONCURRENCY:-3}
+      - 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
@@ -54,4 +68,4 @@ services:
 #    - Auto-import settings
 #    - Cleanup preferences
 #
-# That's it! Everything else can be configured via the web interface.
+# That's it! Everything else can be configured via the web interface.

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
@@ -47,6 +60,8 @@ services:
       - PRESERVE_ORG_STRUCTURE=${PRESERVE_ORG_STRUCTURE:-false}
       - ONLY_MIRROR_ORGS=${ONLY_MIRROR_ORGS:-false}
       - SKIP_STARRED_ISSUES=${SKIP_STARRED_ISSUES:-false}
+      - MIRROR_ISSUE_CONCURRENCY=${MIRROR_ISSUE_CONCURRENCY:-3}
+      - MIRROR_PULL_REQUEST_CONCURRENCY=${MIRROR_PULL_REQUEST_CONCURRENCY:-5}
       - GITEA_URL=${GITEA_URL:-}
       - GITEA_TOKEN=${GITEA_TOKEN:-}
       - GITEA_USERNAME=${GITEA_USERNAME:-}
@@ -72,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/BETTER_AUTH_MIGRATION.md

@@ -1,175 +0,0 @@
-# Better Auth Migration Guide
-
-This document describes the migration from the legacy authentication system to Better Auth.
-
-## Overview
-
-Gitea Mirror has been migrated to use Better Auth, a modern authentication library that provides:
-- Built-in support for email/password authentication
-- Session management with secure cookies
-- Database adapter with Drizzle ORM
-- Ready for OAuth2, OIDC, and SSO integrations
-- Type-safe authentication throughout the application
-
-## Key Changes
-
-### 1. Database Schema
-
-New tables added:
-- `sessions` - User session management
-- `accounts` - Authentication providers (credentials, OAuth, etc.)
-- `verification_tokens` - Email verification and password reset tokens
-
-Modified tables:
-- `users` - Added `emailVerified` field
-
-### 2. Authentication Flow
-
-**Login:**
-- Users now log in with email instead of username
-- Endpoint: `/api/auth/sign-in/email`
-- Session cookies are automatically managed
-
-**Registration:**
-- Users register with username, email, and password
-- Username is stored as an additional field
-- Endpoint: `/api/auth/sign-up/email`
-
-### 3. API Routes
-
-All auth routes are now handled by Better Auth's catch-all handler:
-- `/api/auth/[...all].ts` handles all authentication endpoints
-
-Legacy routes have been backed up to `/src/pages/api/auth/legacy-backup/`
-
-### 4. Session Management
-
-Sessions are now managed by Better Auth:
-- Middleware automatically populates `context.locals.user` and `context.locals.session`
-- Use `useAuth()` hook in React components for client-side auth
-- Sessions expire after 30 days by default
-
-## Future OIDC/SSO Configuration
-
-The project is now ready for OIDC and SSO integrations. To enable:
-
-### 1. Enable SSO Plugin
-
-```typescript
-// src/lib/auth.ts
-import { sso } from "better-auth/plugins/sso";
-
-export const auth = betterAuth({
-  // ... existing config
-  plugins: [
-    sso({
-      provisionUser: async (data) => {
-        // Custom user provisioning logic
-        return data;
-      },
-    }),
-  ],
-});
-```
-
-### 2. Register OIDC Providers
-
-```typescript
-// Example: Register an OIDC provider
-await authClient.sso.register({
-  issuer: "https://idp.example.com",
-  domain: "example.com",
-  clientId: "your-client-id",
-  clientSecret: "your-client-secret",
-  providerId: "example-provider",
-});
-```
-
-### 3. Enable OIDC Provider Mode
-
-To make Gitea Mirror act as an OIDC provider:
-
-```typescript
-// src/lib/auth.ts
-import { oidcProvider } from "better-auth/plugins/oidc";
-
-export const auth = betterAuth({
-  // ... existing config
-  plugins: [
-    oidcProvider({
-      loginPage: "/signin",
-      consentPage: "/oauth/consent",
-      metadata: {
-        issuer: process.env.BETTER_AUTH_URL || "http://localhost:3000",
-      },
-    }),
-  ],
-});
-```
-
-### 4. Database Migration for SSO
-
-When enabling SSO/OIDC, run migrations to add required tables:
-
-```bash
-# Generate the schema
-bun drizzle-kit generate
-
-# Apply the migration
-bun drizzle-kit migrate
-```
-
-New tables that will be added:
-- `sso_providers` - SSO provider configurations
-- `oauth_applications` - OAuth2 client applications
-- `oauth_access_tokens` - OAuth2 access tokens
-- `oauth_consents` - User consent records
-
-## Environment Variables
-
-Required environment variables:
-
-```env
-# Better Auth configuration
-BETTER_AUTH_SECRET=your-secret-key
-BETTER_AUTH_URL=http://localhost:3000
-
-# Legacy (kept for compatibility)
-JWT_SECRET=your-secret-key
-```
-
-## Migration Script
-
-To migrate existing users to Better Auth:
-
-```bash
-bun run migrate:better-auth
-```
-
-This script:
-1. Creates credential accounts for existing users
-2. Moves password hashes to the accounts table
-3. Preserves user creation dates
-
-## Troubleshooting
-
-### Login Issues
-- Ensure users log in with email, not username
-- Check that BETTER_AUTH_SECRET is set
-- Verify database migrations have been applied
-
-### Session Issues
-- Clear browser cookies if experiencing session problems
-- Check middleware is properly configured
-- Ensure auth routes are accessible at `/api/auth/*`
-
-### Development Tips
-- Use `bun db:studio` to inspect database tables
-- Check `/api/auth/session` to verify current session
-- Enable debug logging in Better Auth for troubleshooting
-
-## Resources
-
-- [Better Auth Documentation](https://better-auth.com)
-- [Better Auth Astro Integration](https://better-auth.com/docs/integrations/astro)
-- [Better Auth Plugins](https://better-auth.com/docs/plugins)

docs/BUILD_GUIDE.md

@@ -1,206 +0,0 @@
-# Build Guide
-
-This guide covers building the open-source version of Gitea Mirror.
-
-## Prerequisites
-
-- **Bun** >= 1.2.9 (primary runtime)
-- **Node.js** >= 20 (for compatibility)
-- **Git**
-
-## Quick Start
-
-```bash
-# Clone repository
-git clone https://github.com/yourusername/gitea-mirror.git
-cd gitea-mirror
-
-# Install dependencies
-bun install
-
-# Initialize database
-bun run init-db
-
-# Build for production
-bun run build
-
-# Start the application
-bun run start
-```
-
-## Build Commands
-
-| Command | Description |
-|---------|-------------|
-| `bun run build` | Production build |
-| `bun run dev` | Development server |
-| `bun run preview` | Preview production build |
-| `bun test` | Run tests |
-| `bun run cleanup-db` | Remove database files |
-
-## Build Output
-
-The build creates:
-- `dist/` - Production-ready server files
-- `.astro/` - Build cache (git-ignored)
-- `data/` - SQLite database location
-
-## Development Build
-
-For active development with hot reload:
-
-```bash
-bun run dev
-```
-
-Access the application at http://localhost:4321
-
-## Production Build
-
-```bash
-# Build
-bun run build
-
-# Test the build
-bun run preview
-
-# Run in production
-bun run start
-```
-
-## Docker Build
-
-```dockerfile
-# Build Docker image
-docker build -t gitea-mirror:latest .
-
-# Run container
-docker run -p 3000:3000 gitea-mirror:latest
-```
-
-## Environment Variables
-
-Create a `.env` file:
-
-```env
-# Database
-DATABASE_PATH=./data/gitea-mirror.db
-
-# Authentication
-JWT_SECRET=your-secret-here
-
-# GitHub Configuration
-GITHUB_TOKEN=ghp_...
-GITHUB_WEBHOOK_SECRET=...
-GITHUB_EXCLUDED_ORGS=org1,org2,org3  # Optional: Comma-separated list of organizations to exclude from sync
-
-# Gitea Configuration
-GITEA_URL=https://your-gitea.com
-GITEA_TOKEN=...
-```
-
-## Common Build Issues
-
-### Missing Dependencies
-
-```bash
-# Solution
-bun install
-```
-
-### Database Not Initialized
-
-```bash
-# Solution
-bun run init-db
-```
-
-### Port Already in Use
-
-```bash
-# Change port
-PORT=3001 bun run dev
-```
-
-### Build Cache Issues
-
-```bash
-# Clear cache
-rm -rf .astro/ dist/
-bun run build
-```
-
-## Build Optimization
-
-### Development Speed
-
-- Use `bun run dev` for hot reload
-- Skip type checking during rapid development
-- Keep `.astro/` cache between builds
-
-### Production Optimization
-
-- Minification enabled automatically
-- Tree shaking removes unused code
-- Image optimization with Sharp
-
-## Validation
-
-After building, verify:
-
-```bash
-# Check build output
-ls -la dist/
-
-# Test server starts
-bun run start
-
-# Check health endpoint
-curl http://localhost:3000/api/health
-```
-
-## CI/CD Build
-
-Example GitHub Actions workflow:
-
-```yaml
-name: Build and Test
-on: [push, pull_request]
-
-jobs:
-  build:
-    runs-on: ubuntu-latest
-    steps:
-      - uses: actions/checkout@v4
-      - uses: oven-sh/setup-bun@v2
-      - run: bun install
-      - run: bun run build
-      - run: bun test
-```
-
-## Troubleshooting
-
-### Build Fails
-
-1. Check Bun version: `bun --version`
-2. Clear dependencies: `rm -rf node_modules && bun install`
-3. Check for syntax errors: `bunx tsc --noEmit`
-
-### Runtime Errors
-
-1. Check environment variables
-2. Verify database exists
-3. Check file permissions
-
-## Performance
-
-Expected build times:
-- Clean build: ~5-10 seconds
-- Incremental build: ~2-5 seconds
-- Development startup: ~1-2 seconds
-
-## Next Steps
-
-- Configure with [Configuration Guide](./CONFIGURATION.md)
-- Deploy with [Deployment Guide](./DEPLOYMENT.md)
-- Set up authentication with [SSO Guide](./SSO-OIDC-SETUP.md)

docs/CA_CERTIFICATES.md

@@ -1 +0,0 @@
-../certs/README.md

docs/DEVELOPMENT_WORKFLOW.md

@@ -16,27 +16,22 @@ This guide covers the development workflow for the open-source Gitea Mirror.
 
 1. **Clone the repository**:
 ```bash
-git clone https://github.com/yourusername/gitea-mirror.git
+git clone https://github.com/RayLabsHQ/gitea-mirror.git
 cd gitea-mirror
 ```
 
-2. **Install dependencies**:
+2. **Install dependencies and seed the SQLite database**:
 ```bash
-bun install
+bun run setup
 ```
 
-3. **Initialize database**:
-```bash
-bun run init-db
-```
-
-4. **Configure environment**:
+3. **Configure environment (optional)**:
 ```bash
 cp .env.example .env
 # Edit .env with your settings
 ```
 
-5. **Start development server**:
+4. **Start the development server**:
 ```bash
 bun run dev
 ```
@@ -45,29 +40,33 @@ bun run dev
 
 | Command | Description |
 |---------|-------------|
-| `bun run dev` | Start development server with hot reload |
-| `bun run build` | Build for production |
-| `bun run preview` | Preview production build |
-| `bun test` | Run all tests |
+| `bun run dev` | Start the Bun + Astro dev server with hot reload |
+| `bun run build` | Build the production bundle |
+| `bun run preview` | Preview the production build locally |
+| `bun test` | Run the Bun test suite |
 | `bun test:watch` | Run tests in watch mode |
-| `bun run db:studio` | Open database GUI |
+| `bun run db:studio` | Launch Drizzle Kit Studio |
 
 ## Project Structure
 
 ```
 gitea-mirror/
-├── src/
-│   ├── components/      # React components
-│   ├── pages/          # Astro pages & API routes
-│   ├── lib/            # Core logic
-│   │   ├── db/         # Database queries
-│   │   ├── utils/      # Helper functions
-│   │   └── modules/    # Module system
-│   ├── hooks/          # React hooks
-│   └── types/          # TypeScript types
-├── public/             # Static assets
-├── scripts/            # Utility scripts
-└── tests/              # Test files
+├── src/                     # Application UI, API routes, and services
+│   ├── components/          # React components rendered inside Astro pages
+│   ├── pages/               # Astro pages and API routes (e.g., /api/*)
+│   ├── lib/                 # Core logic: GitHub/Gitea clients, scheduler, recovery, db helpers
+│   │   ├── db/              # Drizzle adapter + schema
+│   │   ├── modules/         # Module wiring (jobs, integrations)
+│   │   └── utils/           # Shared utilities
+│   ├── hooks/               # React hooks
+│   ├── content/             # In-app documentation and templated content
+│   ├── layouts/             # Shared layout components
+│   ├── styles/              # Tailwind CSS entrypoints
+│   └── types/               # TypeScript types
+├── scripts/                 # Bun scripts for DB management and maintenance
+├── www/                     # Marketing site (Astro + MDX use cases)
+├── public/                  # Static assets served by Vite/Astro
+└── tests/                   # Dedicated integration/unit test helpers
 ```
 
 ## Feature Development
@@ -80,10 +79,10 @@ git checkout -b feature/my-feature
 ```
 
 2. **Plan your changes**:
-- UI components in `/src/components/`
-- API endpoints in `/src/pages/api/`
-- Database queries in `/src/lib/db/queries/`
-- Types in `/src/types/`
+- UI components live in `src/components/`
+- API endpoints live in `src/pages/api/`
+- Database logic is under `src/lib/db/` (schema + adapter)
+- Shared types are in `src/types/`
 
 3. **Implement the feature**:
 
@@ -120,7 +119,7 @@ describe('My Feature', () => {
 
 5. **Update documentation**:
 - Add JSDoc comments
-- Update README if needed
+- Update README/docs if needed
 - Document API changes
 
 ## Database Development
@@ -311,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
 
@@ -350,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,39 @@ 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 |
+| `BETTER_AUTH_LOG_LEVEL` | Better Auth logger verbosity. Set to `debug` to surface the full SSO/OIDC sign-in and callback trace when troubleshooting authentication. Accepted values: `debug`, `info`, `warn`, `error`. (Better Auth does **not** use the `DEBUG` env var.) | `warn` | 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 +78,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,9 +101,13 @@ 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` |
+| `STARRED_DUPLICATE_STRATEGY` | Name collision strategy when two starred repos share a name from different owners (`suffix` = `repo-owner`, `prefix` = `owner-repo`) | `suffix` | `suffix`, `prefix`, `owner-org` |
 
 ### Organization Settings
 
@@ -69,7 +115,8 @@ Settings for connecting to and configuring GitHub repository sources.
 |----------|-------------|---------|---------|
 | `MIRROR_ORGANIZATIONS` | Mirror organization repositories | `false` | `true`, `false` |
 | `PRESERVE_ORG_STRUCTURE` | Preserve GitHub organization structure in Gitea | `false` | `true`, `false` |
-| `ONLY_MIRROR_ORGS` | Only mirror organization repos (skip personal) | `false` | `true`, `false` |
+| `ONLY_MIRROR_ORGS` | Only mirror organization repos (skip personal); sets `skipPersonalRepos: true` in GitHub config | `false` | `true`, `false` |
+| `INCLUDE_ORGANIZATIONS` | Opt-in allowlist: only mirror repos from these organizations (empty = all orgs you belong to). Sets `includeOrganizations` in GitHub config | - | Comma-separated org names |
 | `MIRROR_STRATEGY` | Repository organization strategy | `preserve` | `preserve`, `single-org`, `flat-user`, `mixed` |
 
 ### Advanced Settings
@@ -77,6 +124,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
 
@@ -87,6 +135,7 @@ Settings for the destination Gitea instance.
 | Variable | Description | Default | Options |
 |----------|-------------|---------|---------|
 | `GITEA_URL` | Gitea instance URL | - | Valid URL |
+| `GITEA_EXTERNAL_URL` | Optional external/browser URL used for dashboard links. API and mirroring still use `GITEA_URL`. | - | Valid URL |
 | `GITEA_TOKEN` | Gitea access token | - | - |
 | `GITEA_USERNAME` | Gitea username | - | - |
 | `GITEA_ORGANIZATION` | Default organization for single-org strategy | `github-mirrors` | Any string |
@@ -141,6 +190,10 @@ Control what content gets mirrored from GitHub to Gitea.
 | `MIRROR_PULL_REQUESTS` | Mirror pull requests (requires MIRROR_METADATA=true) | `false` | `true`, `false` |
 | `MIRROR_LABELS` | Mirror labels (requires MIRROR_METADATA=true) | `false` | `true`, `false` |
 | `MIRROR_MILESTONES` | Mirror milestones (requires MIRROR_METADATA=true) | `false` | `true`, `false` |
+| `MIRROR_ISSUE_CONCURRENCY` | Number of issues processed in parallel. Set above `1` to speed up mirroring at the risk of out-of-order creation. | `3` | Integer ≥ 1 |
+| `MIRROR_PULL_REQUEST_CONCURRENCY` | Number of pull requests processed in parallel. Values above `1` may cause ordering differences. | `5` | Integer ≥ 1 |
+
+> **Ordering vs Throughput:** Metadata now mirrors sequentially by default to preserve chronology. Increase the concurrency variables only if you can tolerate minor out-of-order entries.
 
 ## Automation Configuration
 
@@ -294,6 +347,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:
@@ -362,6 +416,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/EXTENDING.md

@@ -1,77 +0,0 @@
-# Extending Gitea Mirror
-
-Gitea Mirror is designed with extensibility in mind through a module system.
-
-## Module System
-
-The application provides a module interface that allows extending functionality:
-
-```typescript
-export interface Module {
-  name: string;
-  version: string;
-  init(app: AppContext): Promise<void>;
-  cleanup?(): Promise<void>;
-}
-```
-
-## Creating Custom Modules
-
-You can create custom modules to add features:
-
-```typescript
-// my-module.ts
-export class MyModule implements Module {
-  name = 'my-module';
-  version = '1.0.0';
-
-  async init(app: AppContext) {
-    // Add your functionality
-    app.addRoute('/api/my-endpoint', this.handler);
-  }
-
-  async handler(context) {
-    return new Response('Hello from my module!');
-  }
-}
-```
-
-## Module Context
-
-Modules receive an `AppContext` with:
-- Database access
-- Event system
-- Route registration
-- Configuration
-
-## Private Extensions
-
-If you're developing private extensions:
-
-1. Create a separate package/repository
-2. Implement the module interface
-3. Use Bun's linking feature for development:
-   ```bash
-   # In your extension
-   bun link
-   
-   # In gitea-mirror
-   bun link your-extension
-   ```
-
-## Best Practices
-
-- Keep modules focused on a single feature
-- Use TypeScript for type safety
-- Handle errors gracefully
-- Clean up resources in `cleanup()`
-- Document your module's API
-
-## Community Modules
-
-Share your modules with the community:
-- Create a GitHub repository
-- Tag it with `gitea-mirror-module`
-- Submit a PR to list it in our docs
-
-For more details on the module system, see the source code in `/src/lib/modules/`.

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 **Configuration → Connections → 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_DEPLOYMENT.md

@@ -0,0 +1,486 @@
+# Nix Deployment Guide
+
+This guide covers deploying Gitea Mirror using Nix flakes. The Nix deployment follows the same minimal configuration philosophy as `docker-compose.alt.yml` - secrets are auto-generated, and everything else can be configured via the web UI.
+
+## Prerequisites
+
+- Nix 2.4+ installed
+- For NixOS module: NixOS 23.05+
+
+### Enable Flakes (Recommended)
+
+To enable flakes permanently and avoid typing flags, add to `/etc/nix/nix.conf` or `~/.config/nix/nix.conf`:
+```
+experimental-features = nix-command flakes
+```
+
+**Note:** If you don't enable flakes globally, add `--extra-experimental-features 'nix-command flakes'` to all nix commands shown below.
+
+## Quick Start (Zero Configuration!)
+
+### Run Immediately - No Setup Required
+
+```bash
+# Run directly from the flake (local)
+nix run --extra-experimental-features 'nix-command flakes' .#gitea-mirror
+
+# Or from GitHub (once published)
+nix run --extra-experimental-features 'nix-command flakes' github:RayLabsHQ/gitea-mirror
+
+# If you have flakes enabled globally, simply:
+nix run .#gitea-mirror
+```
+
+That's it! On first run:
+- Secrets (`BETTER_AUTH_SECRET` and `ENCRYPTION_SECRET`) are auto-generated
+- Database is automatically created and initialized
+- Startup recovery and repair scripts run automatically
+- Access the web UI at http://localhost:4321
+
+Everything else (GitHub credentials, Gitea settings, mirror options) is configured through the web interface after signup.
+
+### Development Environment
+
+```bash
+# Enter development shell with all dependencies
+nix develop --extra-experimental-features 'nix-command flakes'
+
+# Or use direnv for automatic environment loading (handles flags automatically)
+echo "use flake" > .envrc
+direnv allow
+```
+
+### Build and Install
+
+```bash
+# Build the package
+nix build --extra-experimental-features 'nix-command flakes'
+
+# Run the built package
+./result/bin/gitea-mirror
+
+# Install to your profile
+nix profile install --extra-experimental-features 'nix-command flakes' .#gitea-mirror
+```
+
+## What Happens on First Run?
+
+Following the same pattern as the Docker deployment, the Nix package automatically:
+
+1. **Creates data directory**: `~/.local/share/gitea-mirror` (or `$DATA_DIR`)
+2. **Generates secrets** (stored securely in data directory):
+   - `BETTER_AUTH_SECRET` - Session authentication (32-char hex)
+   - `ENCRYPTION_SECRET` - Token encryption (48-char base64)
+3. **Initializes database**: SQLite database with Drizzle migrations
+4. **Runs startup scripts**:
+   - Environment configuration loader
+   - Crash recovery for interrupted jobs
+   - Repository status repair
+5. **Starts the application** with graceful shutdown handling
+
+## NixOS Module - Minimal Deployment
+
+### Simplest Possible Configuration
+
+Add to your NixOS configuration (`/etc/nixos/configuration.nix`):
+
+```nix
+{
+  inputs = {
+    nixpkgs.url = "github:NixOS/nixpkgs/nixos-unstable";
+    gitea-mirror.url = "github:RayLabsHQ/gitea-mirror";
+  };
+
+  outputs = { nixpkgs, gitea-mirror, ... }: {
+    nixosConfigurations.your-hostname = nixpkgs.lib.nixosSystem {
+      system = "x86_64-linux";
+      modules = [
+        gitea-mirror.nixosModules.default
+        {
+          # That's it! Just enable the service
+          services.gitea-mirror.enable = true;
+        }
+      ];
+    };
+  };
+}
+```
+
+Apply with:
+```bash
+sudo nixos-rebuild switch
+```
+
+Access at http://localhost:4321, sign up (first user is admin), and configure everything via the web UI.
+
+### Production Configuration
+
+For production with custom domain and firewall:
+
+```nix
+{
+  services.gitea-mirror = {
+    enable = true;
+    host = "0.0.0.0";
+    port = 4321;
+    betterAuthUrl = "https://mirror.example.com";
+    betterAuthTrustedOrigins = "https://mirror.example.com";
+    openFirewall = true;
+  };
+
+  # Optional: Use with nginx reverse proxy
+  services.nginx = {
+    enable = true;
+    virtualHosts."mirror.example.com" = {
+      locations."/" = {
+        proxyPass = "http://127.0.0.1:4321";
+        proxyWebsockets = true;
+      };
+      enableACME = true;
+      forceSSL = true;
+    };
+  };
+}
+```
+
+### Advanced: Manual Secret Management
+
+If you prefer to manage secrets manually (e.g., with sops-nix or agenix):
+
+1. Create a secrets file:
+```bash
+# /var/lib/gitea-mirror/secrets.env
+BETTER_AUTH_SECRET=your-32-character-minimum-secret-key-here
+ENCRYPTION_SECRET=your-encryption-secret-here
+```
+
+2. Reference it in your configuration:
+```nix
+{
+  services.gitea-mirror = {
+    enable = true;
+    environmentFile = "/var/lib/gitea-mirror/secrets.env";
+  };
+}
+```
+
+### Full Configuration Options
+
+```nix
+{
+  services.gitea-mirror = {
+    enable = true;
+    package = gitea-mirror.packages.x86_64-linux.default;  # Override package
+    dataDir = "/var/lib/gitea-mirror";
+    user = "gitea-mirror";
+    group = "gitea-mirror";
+    host = "0.0.0.0";
+    port = 4321;
+    betterAuthUrl = "https://mirror.example.com";
+    betterAuthTrustedOrigins = "https://mirror.example.com";
+
+    # Concurrency controls (match docker-compose.alt.yml)
+    mirrorIssueConcurrency = 3;  # Set to 1 for perfect chronological order
+    mirrorPullRequestConcurrency = 5;  # Set to 1 for perfect chronological order
+
+    environmentFile = null;  # Optional secrets file
+    openFirewall = true;
+  };
+}
+```
+
+## Service Management (NixOS)
+
+```bash
+# Start the service
+sudo systemctl start gitea-mirror
+
+# Stop the service
+sudo systemctl stop gitea-mirror
+
+# Restart the service
+sudo systemctl restart gitea-mirror
+
+# Check status
+sudo systemctl status gitea-mirror
+
+# View logs
+sudo journalctl -u gitea-mirror -f
+
+# Health check
+curl http://localhost:4321/api/health
+```
+
+## Environment Variables
+
+All variables from `docker-compose.alt.yml` are supported:
+
+```bash
+# === AUTO-GENERATED (Don't set unless you want specific values) ===
+BETTER_AUTH_SECRET          # Auto-generated, stored in data dir
+ENCRYPTION_SECRET           # Auto-generated, stored in data dir
+
+# === CORE SETTINGS (Have good defaults) ===
+DATA_DIR="$HOME/.local/share/gitea-mirror"
+DATABASE_URL="file:$DATA_DIR/gitea-mirror.db"
+HOST="0.0.0.0"
+PORT="4321"
+NODE_ENV="production"
+
+# === BETTER AUTH (Override for custom domains) ===
+BETTER_AUTH_URL="http://localhost:4321"
+BETTER_AUTH_TRUSTED_ORIGINS="http://localhost:4321"
+PUBLIC_BETTER_AUTH_URL="http://localhost:4321"
+
+# === CONCURRENCY CONTROLS ===
+MIRROR_ISSUE_CONCURRENCY=3           # Default: 3 (set to 1 for perfect order)
+MIRROR_PULL_REQUEST_CONCURRENCY=5    # Default: 5 (set to 1 for perfect order)
+
+# === CONFIGURE VIA WEB UI (Not needed at startup) ===
+# GitHub credentials, Gitea settings, mirror options, scheduling, etc.
+# All configured after signup through the web interface
+```
+
+## Database Management
+
+The Nix package includes a database management helper:
+
+```bash
+# Initialize database (done automatically on first run)
+gitea-mirror-db init
+
+# Check database health
+gitea-mirror-db check
+
+# Fix database issues
+gitea-mirror-db fix
+
+# Reset users
+gitea-mirror-db reset-users
+```
+
+## Home Manager Integration
+
+For single-user deployments:
+
+```nix
+{ config, pkgs, ... }:
+let
+  gitea-mirror = (import (fetchTarball "https://github.com/RayLabsHQ/gitea-mirror/archive/main.tar.gz")).packages.${pkgs.system}.default;
+in {
+  home.packages = [ gitea-mirror ];
+
+  # Optional: Run as user service
+  systemd.user.services.gitea-mirror = {
+    Unit = {
+      Description = "Gitea Mirror Service";
+      After = [ "network.target" ];
+    };
+
+    Service = {
+      Type = "simple";
+      ExecStart = "${gitea-mirror}/bin/gitea-mirror";
+      Restart = "always";
+      Environment = [
+        "DATA_DIR=%h/.local/share/gitea-mirror"
+        "HOST=127.0.0.1"
+        "PORT=4321"
+      ];
+    };
+
+    Install = {
+      WantedBy = [ "default.target" ];
+    };
+  };
+}
+```
+
+## Docker Image from Nix (Optional)
+
+You can also use Nix to create a Docker image:
+
+```nix
+# Add to flake.nix packages section
+dockerImage = pkgs.dockerTools.buildLayeredImage {
+  name = "gitea-mirror";
+  tag = "latest";
+  contents = [ self.packages.${system}.default pkgs.cacert pkgs.openssl ];
+  config = {
+    Cmd = [ "${self.packages.${system}.default}/bin/gitea-mirror" ];
+    ExposedPorts = { "4321/tcp" = {}; };
+    Env = [
+      "DATA_DIR=/data"
+      "DATABASE_URL=file:/data/gitea-mirror.db"
+    ];
+    Volumes = { "/data" = {}; };
+  };
+};
+```
+
+Build and load:
+```bash
+nix build --extra-experimental-features 'nix-command flakes' .#dockerImage
+docker load < result
+docker run -p 4321:4321 -v gitea-mirror-data:/data gitea-mirror:latest
+```
+
+## Comparison: Docker vs Nix
+
+Both deployment methods follow the same philosophy:
+
+| Feature | Docker Compose | Nix |
+|---------|---------------|-----|
+| **Configuration** | Minimal (only BETTER_AUTH_SECRET) | Zero config (auto-generated) |
+| **Secret Generation** | Auto-generated & persisted | Auto-generated & persisted |
+| **Database Init** | Automatic on first run | Automatic on first run |
+| **Startup Scripts** | Runs recovery/repair/env-config | Runs recovery/repair/env-config |
+| **Graceful Shutdown** | Signal handling in entrypoint | Signal handling in wrapper |
+| **Health Check** | Docker healthcheck | systemd timer (optional) |
+| **Updates** | `docker pull` | `nix flake update && nixos-rebuild` |
+
+## Troubleshooting
+
+### Check Auto-Generated Secrets
+```bash
+# For standalone
+cat ~/.local/share/gitea-mirror/.better_auth_secret
+cat ~/.local/share/gitea-mirror/.encryption_secret
+
+# For NixOS service
+sudo cat /var/lib/gitea-mirror/.better_auth_secret
+sudo cat /var/lib/gitea-mirror/.encryption_secret
+```
+
+### Database Issues
+```bash
+# Check if database exists
+ls -la ~/.local/share/gitea-mirror/gitea-mirror.db
+
+# Reinitialize (deletes all data!)
+rm ~/.local/share/gitea-mirror/gitea-mirror.db
+gitea-mirror-db init
+```
+
+### Permission Issues (NixOS)
+```bash
+sudo chown -R gitea-mirror:gitea-mirror /var/lib/gitea-mirror
+sudo chmod 700 /var/lib/gitea-mirror
+```
+
+### Port Already in Use
+```bash
+# Change port
+export PORT=8080
+gitea-mirror
+
+# Or in NixOS config
+services.gitea-mirror.port = 8080;
+```
+
+### View Startup Logs
+```bash
+# Standalone (verbose output on console)
+gitea-mirror
+
+# NixOS service
+sudo journalctl -u gitea-mirror -f --since "5 minutes ago"
+```
+
+## Updating
+
+### Standalone Installation
+```bash
+# Update flake lock
+nix flake update --extra-experimental-features 'nix-command flakes'
+
+# Rebuild
+nix build --extra-experimental-features 'nix-command flakes'
+
+# Or update profile
+nix profile upgrade --extra-experimental-features 'nix-command flakes' gitea-mirror
+```
+
+### NixOS
+```bash
+# Update input
+sudo nix flake lock --update-input gitea-mirror --extra-experimental-features 'nix-command flakes'
+
+# Rebuild system
+sudo nixos-rebuild switch --flake .#your-hostname
+```
+
+## Migration from Docker
+
+To migrate from Docker to Nix while keeping your data:
+
+1. **Stop Docker container:**
+   ```bash
+   docker-compose -f docker-compose.alt.yml down
+   ```
+
+2. **Copy data directory:**
+   ```bash
+   # For standalone
+   cp -r ./data ~/.local/share/gitea-mirror
+
+   # For NixOS
+   sudo cp -r ./data /var/lib/gitea-mirror
+   sudo chown -R gitea-mirror:gitea-mirror /var/lib/gitea-mirror
+   ```
+
+3. **Copy secrets (if you want to keep them):**
+   ```bash
+   # Extract from Docker volume
+   docker run --rm -v gitea-mirror_data:/data alpine \
+     cat /data/.better_auth_secret > better_auth_secret
+   docker run --rm -v gitea-mirror_data:/data alpine \
+     cat /data/.encryption_secret > encryption_secret
+
+   # Copy to new location
+   cp better_auth_secret ~/.local/share/gitea-mirror/.better_auth_secret
+   cp encryption_secret ~/.local/share/gitea-mirror/.encryption_secret
+   chmod 600 ~/.local/share/gitea-mirror/.*_secret
+   ```
+
+4. **Start Nix version:**
+   ```bash
+   gitea-mirror
+   ```
+
+## CI/CD Integration
+
+Example GitHub Actions workflow (see `.github/workflows/nix-build.yml`):
+
+```yaml
+name: Nix Build
+
+on: [push, pull_request]
+
+permissions:
+  contents: read
+
+jobs:
+  build:
+    strategy:
+      matrix:
+        os: [ubuntu-latest, macos-latest]
+    runs-on: ${{ matrix.os }}
+    steps:
+    - uses: actions/checkout@v4
+    - uses: DeterminateSystems/nix-installer-action@main
+    - uses: DeterminateSystems/magic-nix-cache-action@main
+    - run: nix flake check
+    - run: nix build --print-build-logs
+```
+
+This uses:
+- **Determinate Nix Installer** - Fast, reliable Nix installation with flakes enabled by default
+- **Magic Nix Cache** - Free caching using GitHub Actions cache (no account needed)
+
+## Resources
+
+- [Nix Manual](https://nixos.org/manual/nix/stable/)
+- [NixOS Options Search](https://search.nixos.org/options)
+- [Nix Pills Tutorial](https://nixos.org/guides/nix-pills/)
+- [Project Documentation](../README.md)
+- [Docker Deployment](../docker-compose.alt.yml) - Equivalent minimal config

docs/NIX_DISTRIBUTION.md

@@ -0,0 +1,322 @@
+# Nix Package Distribution Guide
+
+This guide explains how Gitea Mirror is distributed via Nix and how users can consume it.
+
+## Distribution Methods
+
+### Method 1: Direct GitHub Usage (Zero Infrastructure)
+
+**No CI, releases, or setup needed!** Users can consume directly from GitHub:
+
+```bash
+# Latest from main branch
+nix run --extra-experimental-features 'nix-command flakes' github:RayLabsHQ/gitea-mirror
+
+# Pin to specific commit
+nix run github:RayLabsHQ/gitea-mirror/abc123def
+
+# Pin to git tag
+nix run github:RayLabsHQ/gitea-mirror/vX.Y.Z
+```
+
+**How it works:**
+1. Nix fetches the repository from GitHub
+2. Nix reads `flake.nix` and `flake.lock`
+3. Nix builds the package locally on the user's machine
+4. Package is cached in `/nix/store` for reuse
+
+**Pros:**
+- Zero infrastructure needed
+- Works immediately after pushing code
+- Users always get reproducible builds
+
+**Cons:**
+- Users must build from source (slower first time)
+- Requires build dependencies (Bun, etc.)
+
+---
+
+### Method 2: CI Build Caching
+
+The GitHub Actions workflow uses **Magic Nix Cache** (by Determinate Systems) to cache builds:
+
+- **Zero configuration required** - no accounts or tokens needed
+- **Automatic** - CI workflow handles everything
+- **Uses GitHub Actions cache** - fast, reliable, free
+
+#### How It Works:
+
+1. GitHub Actions builds the package on each push/PR
+2. Build artifacts are cached in GitHub Actions cache
+3. Subsequent builds reuse cached dependencies (faster CI)
+
+Note: This caches CI builds. Users still build locally, but the flake.lock ensures reproducibility.
+
+---
+
+### Method 3: nixpkgs Submission (Official Distribution)
+
+Submit to the official Nix package repository for maximum visibility.
+
+#### Process:
+
+1. **Prepare package** (already done with `flake.nix`)
+2. **Test thoroughly**
+3. **Submit PR to nixpkgs:** https://github.com/NixOS/nixpkgs
+
+#### User Experience:
+
+```bash
+# After acceptance into nixpkgs
+nix run nixpkgs#gitea-mirror
+
+# NixOS configuration
+environment.systemPackages = [ pkgs.gitea-mirror ];
+```
+
+**Pros:**
+- Maximum discoverability (official repo)
+- Trusted by Nix community
+- Included in NixOS search
+- Binary caching by cache.nixos.org
+
+**Cons:**
+- Submission/review process
+- Must follow nixpkgs guidelines
+- Updates require PRs
+
+---
+
+## Current Distribution Strategy
+
+### Phase 1: Direct GitHub (Immediate) ✅
+
+Already working! Users can:
+
+```bash
+nix run github:RayLabsHQ/gitea-mirror
+```
+
+### Phase 2: CI Build Validation ✅
+
+GitHub Actions workflow validates builds on every push/PR:
+
+- Uses Magic Nix Cache for fast CI builds
+- Tests on both Linux and macOS
+- No setup required - works automatically
+
+### Phase 3: Version Releases (Optional)
+
+Tag releases for version pinning:
+
+```bash
+git tag vX.Y.Z
+git push origin vX.Y.Z
+
+# Users can then pin:
+nix run github:RayLabsHQ/gitea-mirror/vX.Y.Z
+```
+
+### Phase 4: nixpkgs Submission (Long Term)
+
+Once package is stable and well-tested, submit to nixpkgs.
+
+---
+
+## User Documentation
+
+### For Users: How to Install
+
+Add this to your `docs/NIX_DEPLOYMENT.md`:
+
+#### Option 1: Direct Install (No Configuration)
+
+```bash
+# Run immediately
+nix run --extra-experimental-features 'nix-command flakes' github:RayLabsHQ/gitea-mirror
+
+# Install to profile
+nix profile install --extra-experimental-features 'nix-command flakes' github:RayLabsHQ/gitea-mirror
+```
+
+#### Option 2: Pin to Specific Version
+
+```bash
+# Pin to git tag
+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/vX.Y.Z";
+```
+
+#### Option 3: NixOS Configuration
+
+```nix
+{
+  inputs = {
+    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/vX.Y.Z";
+  };
+
+  outputs = { nixpkgs, gitea-mirror, ... }: {
+    nixosConfigurations.your-host = nixpkgs.lib.nixosSystem {
+      modules = [
+        gitea-mirror.nixosModules.default
+        {
+          services.gitea-mirror = {
+            enable = true;
+            betterAuthUrl = "https://mirror.example.com";
+            openFirewall = true;
+          };
+        }
+      ];
+    };
+  };
+}
+```
+
+---
+
+## Maintaining the Distribution
+
+### Releasing New Versions
+
+```bash
+# 1. Update version in package.json
+vim package.json  # Update version field
+
+# 2. Update flake.nix version (line 17)
+vim flake.nix  # Update version = "X.Y.Z";
+
+# 3. Commit changes
+git add package.json flake.nix
+git commit -m "chore: bump version to vX.Y.Z"
+
+# 4. Create git tag
+git tag vX.Y.Z
+git push origin main
+git push origin vX.Y.Z
+
+# 5. GitHub Actions builds and caches automatically
+```
+
+Users can then pin to the new version:
+```bash
+nix run github:RayLabsHQ/gitea-mirror/vX.Y.Z
+```
+
+### Updating Flake Lock
+
+The `flake.lock` file pins all dependencies. Update it periodically:
+
+```bash
+# Update all inputs
+nix flake update
+
+# Update specific input
+nix flake lock --update-input nixpkgs
+
+# Test after update
+nix build
+nix flake check
+
+# Commit the updated lock file
+git add flake.lock
+git commit -m "chore: update flake dependencies"
+git push
+```
+
+---
+
+## Troubleshooting Distribution Issues
+
+### Users Report Build Failures
+
+1. **Check GitHub Actions:** Ensure CI is passing
+2. **Test locally:** `nix flake check`
+3. **Check flake.lock:** May need update if dependencies changed
+
+### CI Cache Not Working
+
+1. **Check workflow logs:** Review GitHub Actions for errors
+2. **Clear cache:** GitHub Actions → Caches → Delete relevant cache
+3. **Verify flake.lock:** May need `nix flake update` if dependencies changed
+
+### Version Pinning Not Working
+
+```bash
+# Verify tag exists
+git tag -l
+
+# Ensure tag is pushed
+git ls-remote --tags origin
+
+# Test specific tag
+nix run github:RayLabsHQ/gitea-mirror/vX.Y.Z
+```
+
+---
+
+## Advanced: Custom Binary Cache
+
+If you prefer self-hosting instead of Cachix:
+
+### Option 1: S3-Compatible Storage
+
+```nix
+# Generate signing key
+nix-store --generate-binary-cache-key cache.example.com cache-priv-key.pem cache-pub-key.pem
+
+# Push to S3
+nix copy --to s3://my-nix-cache?region=us-east-1 $(nix-build)
+```
+
+Users configure:
+```nix
+substituters = https://my-bucket.s3.amazonaws.com/nix-cache
+trusted-public-keys = cache.example.com:BASE64_PUBLIC_KEY
+```
+
+### Option 2: Self-Hosted Nix Store
+
+Run `nix-serve` on your server:
+
+```bash
+# On server
+nix-serve -p 8080
+
+# Behind nginx/caddy
+proxy_pass http://localhost:8080;
+```
+
+Users configure:
+```nix
+substituters = https://cache.example.com
+trusted-public-keys = YOUR_KEY
+```
+
+---
+
+## Comparison: Distribution Methods
+
+| Method | Setup Time | User Speed | Cost | Discoverability |
+|--------|-----------|------------|------|-----------------|
+| Direct GitHub | 0 min | Slow (build) | Free | Low |
+| nixpkgs | Hours/days | Fast (binary) | Free | High |
+| Self-hosted cache | 30+ min | Fast (binary) | Server cost | Low |
+
+**Current approach:** Direct GitHub consumption with CI validation using Magic Nix Cache. Users build locally (reproducible via flake.lock). Consider **nixpkgs** submission for maximum reach once the package is mature.
+
+---
+
+## Resources
+
+- [Nix Flakes Documentation](https://nixos.wiki/wiki/Flakes)
+- [Magic Nix Cache](https://github.com/DeterminateSystems/magic-nix-cache-action)
+- [nixpkgs Contributing Guide](https://github.com/NixOS/nixpkgs/blob/master/CONTRIBUTING.md)
+- [Nix Binary Cache Setup](https://nixos.org/manual/nix/stable/package-management/binary-cache-substituter.html)

docs/NOTIFICATIONS.md

@@ -0,0 +1,135 @@
+# 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
+
+### 3. Gotify (Direct)
+
+[Gotify](https://gotify.net/) is a simple self-hosted push notification server.
+
+**Setup:**
+1. In Gotify, create an application and copy its token
+2. In Gitea Mirror, go to **Configuration > Notifications**
+3. Enable notifications and select **Gotify**
+4. Set the **Server URL** to your Gotify instance (e.g., `https://gotify.example.com`)
+5. Paste the **Application token**
+6. Pick a **Default priority** (0 to 10; error notifications are always sent at priority 8)
+
+The token is encrypted at rest like all other provider credentials.
+
+### 4. Webhook (Generic)
+
+Sends a plain JSON POST to any URL you control. Works with n8n, Home Assistant, or any service that accepts a generic webhook.
+
+**Setup:**
+1. In Gitea Mirror, go to **Configuration > Notifications**
+2. Enable notifications and select **Webhook**
+3. Set the **Webhook URL** to your endpoint
+4. Optionally set a **Signing secret**
+
+**Payload:**
+```json
+{
+  "title": "Mirror Failed: my-repo",
+  "message": "Repository my-repo failed to mirror",
+  "type": "sync_error",
+  "timestamp": "2026-08-03T02:33:29.707Z"
+}
+```
+
+**Signature verification:**
+When a signing secret is set, every request includes an `X-Webhook-Signature` header containing `sha256=<hex>`, an HMAC-SHA256 digest of the raw request body. Verify it on the receiving end:
+
+```js
+const crypto = require("node:crypto");
+const expected = "sha256=" +
+  crypto.createHmac("sha256", secret).update(rawBody).digest("hex");
+const valid = crypto.timingSafeEqual(
+  Buffer.from(signatureHeader), Buffer.from(expected));
+```
+
+The secret is encrypted at rest.
+
+## Event Types
+
+| Event | Default | Description |
+|-------|---------|-------------|
+| Sync errors | On | A mirror job failed |
+| Sync success | Off | A mirror job completed successfully |
+| New repo discovered | Off | Not yet implemented; the toggle is disabled in the UI |
+
+## 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

@@ -1,118 +1,39 @@
 # Gitea Mirror Documentation
 
-Welcome to the Gitea Mirror documentation. This guide covers everything you need to know about developing, building, and deploying the open-source version of Gitea Mirror.
+This folder contains engineering and operations references for the open-source Gitea Mirror project. Each guide focuses on the parts of the system that still require bespoke explanation beyond the in-app help and the main `README.md`.
 
-## Documentation Overview
+## Available Guides
 
-### Getting Started
+### 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.
 
-- **[Development Workflow](./DEVELOPMENT_WORKFLOW.md)** - Set up your development environment and start contributing
-- **[Build Guide](./BUILD_GUIDE.md)** - Build Gitea Mirror from source
-- **[Configuration Guide](./CONFIGURATION.md)** - Configure all available options
+### Reliability & recovery
+- **[GRACEFUL_SHUTDOWN.md](./GRACEFUL_SHUTDOWN.md)** – How signal handling, shutdown coordination, and job persistence work in v3.
+- **[RECOVERY_IMPROVEMENTS.md](./RECOVERY_IMPROVEMENTS.md)** – Deep dive into the startup recovery workflow and supporting scripts.
 
-### Deployment
+### Authentication
+- **[SSO-OIDC-SETUP.md](./SSO-OIDC-SETUP.md)** – Configure OIDC/SSO providers through the admin UI.
+- **[SSO_TESTING.md](./SSO_TESTING.md)** – Recipes for local and staging SSO testing (Google, Keycloak, mock providers).
 
-- **[Deployment Guide](./DEPLOYMENT.md)** - Deploy to production environments
-- **[Docker Guide](./DOCKER.md)** - Container-based deployment
-- **[Reverse Proxy Setup](./REVERSE_PROXY.md)** - Configure with nginx/Caddy
+If you are looking for customer-facing playbooks, see the MDX use cases under `www/src/pages/use-cases/`.
 
-### Features
+## Quick start for local development
 
-- **[SSO/OIDC Setup](./SSO-OIDC-SETUP.md)** - Configure authentication providers
-- **[Sponsor Integration](./SPONSOR_INTEGRATION.md)** - GitHub Sponsors integration
-- **[Webhook Configuration](./WEBHOOKS.md)** - Set up GitHub webhooks
-
-### Architecture
-
-- **[Architecture Overview](./ARCHITECTURE.md)** - System design and components
-- **[API Documentation](./API.md)** - REST API endpoints
-- **[Database Schema](./DATABASE.md)** - SQLite structure
-
-### Maintenance
-
-- **[Migration Guide](../MIGRATION_GUIDE.md)** - Upgrade from previous versions
-- **[Better Auth Migration](./BETTER_AUTH_MIGRATION.md)** - Migrate authentication system
-- **[Troubleshooting](./TROUBLESHOOTING.md)** - Common issues and solutions
-- **[Backup & Restore](./BACKUP.md)** - Data management
-
-## Quick Start
-
-1. **Clone and install**:
 ```bash
-git clone https://github.com/yourusername/gitea-mirror.git
+git clone https://github.com/RayLabsHQ/gitea-mirror.git
 cd gitea-mirror
-bun install
+bun run setup           # installs deps and seeds the SQLite DB
+bun run dev             # starts the Astro/Bun app on http://localhost:4321
 ```
 
-2. **Configure**:
-```bash
-cp .env.example .env
-# Edit .env with your GitHub and Gitea tokens
-```
+The first user you create locally becomes the administrator. All other configuration—GitHub owners, Gitea targets, scheduling, cleanup—is done through the **Configuration** screen in the UI.
 
-3. **Initialize and run**:
-```bash
-bun run init-db
-bun run dev
-```
+## Contributing & support
 
-4. **Access**: Open http://localhost:4321
-
-## Key Features
-
-- 🔄 **Automatic Syncing** - Keep repositories synchronized
-- 🗂️ **Organization Support** - Mirror entire organizations
-- ⭐ **Starred Repos** - Mirror your starred repositories
-- 🔐 **Self-Hosted** - Full control over your data
-- 🚀 **Fast** - Built with Bun for optimal performance
-- 🔒 **Secure** - JWT authentication, encrypted tokens
-
-## Technology Stack
-
-- **Runtime**: Bun
-- **Framework**: Astro with React
-- **Database**: SQLite with Drizzle ORM
-- **Styling**: Tailwind CSS v4
-- **Authentication**: Better Auth
-
-## System Requirements
-
-- Bun >= 1.2.9
-- Node.js >= 20 (optional, for compatibility)
-- SQLite 3
-- 512MB RAM minimum
-- 1GB disk space
-
-## Contributing
-
-We welcome contributions! Please see our [Contributing Guide](../CONTRIBUTING.md) for details.
-
-### Development Setup
-
-1. Fork the repository
-2. Create a feature branch
-3. Make your changes
-4. Add tests
-5. Submit a pull request
-
-### Code of Conduct
-
-Please read our [Code of Conduct](../CODE_OF_CONDUCT.md) before contributing.
-
-## Support
-
-- **Issues**: [GitHub Issues](https://github.com/yourusername/gitea-mirror/issues)
-- **Discussions**: [GitHub Discussions](https://github.com/yourusername/gitea-mirror/discussions)
-- **Wiki**: [GitHub Wiki](https://github.com/yourusername/gitea-mirror/wiki)
-
-## Security
-
-For security issues, please see [SECURITY.md](../SECURITY.md).
-
-## License
-
-Gitea Mirror is open source software licensed under the [MIT License](../LICENSE).
-
----
-
-For detailed information on any topic, please refer to the specific documentation guides listed above.
+- 🎯 Contribution guide: [../CONTRIBUTING.md](../CONTRIBUTING.md)
+- 🐞 Issues & feature requests: <https://github.com/RayLabsHQ/gitea-mirror/issues>
+- 💬 Discussions: <https://github.com/RayLabsHQ/gitea-mirror/discussions>
+- 🔐 Security policy & advisories: <https://github.com/RayLabsHQ/gitea-mirror/security>

docs/SHUTDOWN_PROCESS.md

@@ -1,236 +0,0 @@
-# Graceful Shutdown Process
-
-This document details how the gitea-mirror application handles graceful shutdown during active mirroring operations, with specific focus on job interruption and recovery.
-
-## Overview
-
-The graceful shutdown system is designed for **fast, clean termination** without waiting for long-running jobs to complete. It prioritizes **quick shutdown times** (under 30 seconds) while **preserving all progress** for seamless recovery.
-
-## Key Principle
-
-**The application does NOT wait for jobs to finish before shutting down.** Instead, it saves the current state and resumes after restart.
-
-## Shutdown Scenario Example
-
-### Initial State
-- **Job**: Mirror 500 repositories
-- **Progress**: 200 repositories completed
-- **Remaining**: 300 repositories pending
-- **Action**: User initiates shutdown (SIGTERM, Ctrl+C, Docker stop)
-
-### Shutdown Process (Under 30 seconds)
-
-#### Step 1: Signal Detection (Immediate)
-```
-📡 Received SIGTERM signal
-🛑 Graceful shutdown initiated by signal: SIGTERM
-📊 Shutdown status: 1 active jobs, 2 callbacks
-```
-
-#### Step 2: Job State Saving (1-10 seconds)
-```
-📝 Step 1: Saving active job states...
-Saving state for job abc-123...
-✅ Saved state for job abc-123
-```
-
-**What gets saved:**
-- `inProgress: false` - Mark job as not currently running
-- `completedItems: 200` - Number of repos successfully mirrored
-- `totalItems: 500` - Total repos in the job
-- `completedItemIds: [repo1, repo2, ..., repo200]` - List of completed repos
-- `itemIds: [repo1, repo2, ..., repo500]` - Full list of repos
-- `lastCheckpoint: 2025-05-24T17:30:00Z` - Exact shutdown time
-- `message: "Job interrupted by application shutdown - will resume on restart"`
-- `status: "imported"` - Keeps status as resumable (not "failed")
-
-#### Step 3: Service Cleanup (1-5 seconds)
-```
-🔧 Step 2: Executing shutdown callbacks...
-🛑 Shutting down cleanup service...
-✅ Cleanup service stopped
-✅ Shutdown callback 1 completed
-```
-
-#### Step 4: Clean Exit (Immediate)
-```
-💾 Step 3: Closing database connections...
-✅ Graceful shutdown completed successfully
-```
-
-**Total shutdown time: ~15 seconds** (well under the 30-second limit)
-
-## What Happens to the Remaining 300 Repos?
-
-### During Shutdown
-- **NOT processed** - The remaining 300 repos are not mirrored
-- **NOT lost** - Their IDs are preserved in the job state
-- **NOT marked as failed** - Job status remains "imported" for recovery
-
-### After Restart
-The recovery system automatically:
-
-1. **Detects interrupted job** during startup
-2. **Calculates remaining work**: 500 - 200 = 300 repos
-3. **Extracts remaining repo IDs**: repos 201-500 from the original list
-4. **Resumes processing** from exactly where it left off
-5. **Continues until completion** of all 500 repos
-
-## Timeout Configuration
-
-### Shutdown Timeouts
-```typescript
-const SHUTDOWN_TIMEOUT = 30000; // 30 seconds max shutdown time
-const JOB_SAVE_TIMEOUT = 10000; // 10 seconds to save job state
-```
-
-### Timeout Behavior
-- **Normal case**: Shutdown completes in 10-20 seconds
-- **Slow database**: Up to 30 seconds allowed
-- **Timeout exceeded**: Force exit with code 1
-- **Container kill**: Orchestrator should allow 45+ seconds grace period
-
-## Job State Persistence
-
-### Database Schema
-The `mirror_jobs` table stores complete job state:
-
-```sql
--- Job identification
-id TEXT PRIMARY KEY,
-user_id TEXT NOT NULL,
-job_type TEXT NOT NULL DEFAULT 'mirror',
-
--- Progress tracking  
-total_items INTEGER,
-completed_items INTEGER DEFAULT 0,
-item_ids TEXT, -- JSON array of all repo IDs
-completed_item_ids TEXT DEFAULT '[]', -- JSON array of completed repo IDs
-
--- State management
-in_progress INTEGER NOT NULL DEFAULT 0, -- Boolean: currently running
-started_at TIMESTAMP,
-completed_at TIMESTAMP,
-last_checkpoint TIMESTAMP, -- Last progress save
-
--- Status and messaging
-status TEXT NOT NULL DEFAULT 'imported',
-message TEXT NOT NULL
-```
-
-### Recovery Query
-The recovery system finds interrupted jobs:
-
-```sql
-SELECT * FROM mirror_jobs 
-WHERE in_progress = 0 
-  AND status = 'imported' 
-  AND completed_at IS NULL
-  AND total_items > completed_items;
-```
-
-## Shutdown-Aware Processing
-
-### Concurrency Check
-During job execution, each repo processing checks for shutdown:
-
-```typescript
-// Before processing each repository
-if (isShuttingDown()) {
-  throw new Error('Processing interrupted by application shutdown');
-}
-```
-
-### Checkpoint Intervals
-Jobs save progress periodically (every 10 repos by default):
-
-```typescript
-checkpointInterval: 10, // Save progress every 10 repositories
-```
-
-This ensures minimal work loss even if shutdown occurs between checkpoints.
-
-## Container Integration
-
-### Docker Entrypoint
-The Docker entrypoint properly forwards signals:
-
-```bash
-# Set up signal handlers
-trap 'shutdown_handler' TERM INT HUP
-
-# Start application in background
-bun ./dist/server/entry.mjs &
-APP_PID=$!
-
-# Wait for application to finish
-wait "$APP_PID"
-```
-
-### Kubernetes Configuration
-Recommended pod configuration:
-
-```yaml
-apiVersion: v1
-kind: Pod
-spec:
-  terminationGracePeriodSeconds: 45  # Allow time for graceful shutdown
-  containers:
-  - name: gitea-mirror
-    # ... other configuration
-```
-
-## Monitoring and Logging
-
-### Shutdown Logs
-```
-🛑 Graceful shutdown initiated by signal: SIGTERM
-📊 Shutdown status: 1 active jobs, 2 callbacks
-📝 Step 1: Saving active job states...
-Saving state for 1 active jobs...
-✅ Completed saving all active jobs
-🔧 Step 2: Executing shutdown callbacks...
-✅ Completed all shutdown callbacks  
-💾 Step 3: Closing database connections...
-✅ Graceful shutdown completed successfully
-```
-
-### Recovery Logs
-```
-⚠️  Jobs found that need recovery. Starting recovery process...
-Resuming job abc-123 with 300 remaining items...
-✅ Recovery completed successfully
-```
-
-## Best Practices
-
-### For Operations
-1. **Monitor shutdown times** - Should complete under 30 seconds
-2. **Check recovery logs** - Verify jobs resume correctly after restart
-3. **Set appropriate grace periods** - Allow 45+ seconds in orchestrators
-4. **Plan maintenance windows** - Jobs will resume but may take time to complete
-
-### For Development
-1. **Test shutdown scenarios** - Use `bun run test-shutdown`
-2. **Monitor job progress** - Check checkpoint frequency and timing
-3. **Verify recovery** - Ensure interrupted jobs resume correctly
-4. **Handle edge cases** - Test shutdown during different job phases
-
-## Troubleshooting
-
-### Shutdown Takes Too Long
-- **Check**: Database performance during job state saving
-- **Solution**: Increase `SHUTDOWN_TIMEOUT` environment variable
-- **Monitor**: Job complexity and checkpoint frequency
-
-### Jobs Don't Resume
-- **Check**: Recovery logs for errors during startup
-- **Verify**: Database contains interrupted jobs with correct status
-- **Test**: Run `bun run startup-recovery` manually
-
-### Container Force-Killed
-- **Check**: Container orchestrator termination grace period
-- **Increase**: Grace period to 45+ seconds
-- **Monitor**: Application shutdown completion time
-
-This design ensures **production-ready graceful shutdown** with **zero data loss** and **fast recovery times** suitable for modern containerized deployments.

docs/SPONSOR_INTEGRATION.md

@@ -1,91 +0,0 @@
-# GitHub Sponsors Integration
-
-This guide shows how GitHub Sponsors is integrated into the open-source version of Gitea Mirror.
-
-## Components
-
-### GitHubSponsors Card
-
-A card component that displays in the sidebar or dashboard:
-
-```tsx
-import { GitHubSponsors } from '@/components/sponsors/GitHubSponsors';
-
-// In your layout or dashboard
-<GitHubSponsors />
-```
-
-### SponsorButton
-
-A smaller button for headers or navigation:
-
-```tsx
-import { SponsorButton } from '@/components/sponsors/GitHubSponsors';
-
-// In your header
-<SponsorButton />
-```
-
-## Integration Points
-
-### 1. Dashboard Sidebar
-
-Add the sponsor card to the dashboard sidebar for visibility:
-
-```tsx
-// src/components/layout/DashboardLayout.tsx
-<aside>
-  {/* Other sidebar content */}
-  <GitHubSponsors />
-</aside>
-```
-
-### 2. Header Navigation
-
-Add the sponsor button to the main navigation:
-
-```tsx
-// src/components/layout/Header.tsx
-<nav>
-  {/* Other nav items */}
-  <SponsorButton />
-</nav>
-```
-
-### 3. Settings Page
-
-Add a support section in settings:
-
-```tsx
-// src/components/settings/SupportSection.tsx
-<Card>
-  <CardHeader>
-    <CardTitle>Support Development</CardTitle>
-  </CardHeader>
-  <CardContent>
-    <GitHubSponsors />
-  </CardContent>
-</Card>
-```
-
-## Behavior
-
-- **Only appears in self-hosted mode**: The components automatically hide in hosted mode
-- **Non-intrusive**: Designed to be helpful without being annoying
-- **Multiple options**: GitHub Sponsors, Buy Me a Coffee, and starring the repo
-
-## Customization
-
-You can customize the sponsor components by:
-
-1. Updating the GitHub Sponsors URL
-2. Adding/removing donation platforms
-3. Changing the styling to match your theme
-4. Adjusting the placement based on user feedback
-
-## Best Practices
-
-1. **Don't be pushy**: Show sponsor options tastefully
-2. **Provide value first**: Ensure the tool is useful before asking for support
-3. **Be transparent**: Explain how sponsorships help the project
-4. **Thank sponsors**: Acknowledge supporters in README or releases

docs/SSO-OIDC-SETUP.md

@@ -4,15 +4,16 @@ This guide explains how to configure Single Sign-On (SSO) and OpenID Connect (OI
 
 ## Overview
 
-Gitea Mirror supports three authentication methods:
+Gitea Mirror supports four authentication methods:
 
 1. **Email & Password** - Traditional authentication (always enabled)
 2. **SSO (Single Sign-On)** - Allow users to authenticate using external OIDC providers
-3. **OIDC Provider** - Allow other applications to authenticate users through Gitea Mirror
+3. **Header / Forward Authentication** - Trust pre-authenticated requests from a reverse proxy (Authentik, Authelia, oauth2-proxy, etc.)
+4. **OIDC Provider** - Allow other applications to authenticate users through Gitea Mirror
 
 ## Configuration
 
-All SSO and OIDC settings are managed through the web UI in the Configuration page under the "Authentication" tab.
+SSO and OIDC Provider settings are managed through the web UI in the Configuration page under the "Authentication" tab. Header / Forward Authentication is configured via environment variables only — see [Setting up Header / Forward Authentication](#setting-up-header--forward-authentication) below.
 
 ## Setting up SSO (Single Sign-On)
 
@@ -27,7 +28,7 @@ SSO allows your users to sign in using external identity providers like Google,
 #### Required Fields
 
 - **Issuer URL**: The OIDC issuer URL (e.g., `https://accounts.google.com`)
-- **Domain**: The email domain for this provider (e.g., `example.com`)
+- **Domain**: The email domain this provider serves (e.g., `example.com`). **This is load-bearing for account-linking trust — see [Account Linking](#account-linking) below.** Multi-domain IdPs can use a comma-separated list (`example.com,subsidiary.com`).
 - **Provider ID**: A unique identifier for this provider (e.g., `google-sso`)
 - **Client ID**: The OAuth client ID from your provider
 - **Client Secret**: The OAuth client secret from your provider
@@ -56,6 +57,22 @@ https://your-domain.com/api/auth/sso/callback/{provider-id}
 
 Replace `{provider-id}` with your chosen Provider ID.
 
+### Account Linking
+
+When a user signs in via SSO whose email matches an **existing** email/password account, Gitea Mirror will try to *link* the SSO identity to that account so the user lands on the same dashboard — instead of being bounced to the login page or creating a duplicate account.
+
+The trust model is **domain-scoped**:
+
+- Every SSO provider you register is automatically marked `domainVerified: true` for the **Domain** field you set on registration.
+- An SSO sign-in is auto-linked to an existing local account **only when** the user's email address actually belongs to that registered domain. Cross-domain emails are rejected even if the provider is registered.
+- Local email/password accounts in this app are never verified (no email-verification flow exists), so we deliberately turn off `requireLocalEmailVerified` on the linker — otherwise no one could ever link.
+
+**What this means for you:**
+
+- Set the **Domain** field to the email domain(s) your IdP actually issues identities for. Don't set it to `example.com` if your IdP issues `@elsewhere.com` emails — auto-linking will silently refuse them.
+- If your IdP allows users to self-register or claim arbitrary emails *within the registered domain*, an attacker on that IdP can absorb a local account by claiming the same email. This is a trust decision: by registering an IdP, you're vouching for its identity model for that domain.
+- Multi-domain IdPs (one Authentik serving `acme.com,acquired.io`) work fine — list every domain comma-separated in the **Domain** field.
+
 ### Example: Google SSO Setup
 
 1. Go to [Google Cloud Console](https://console.cloud.google.com/)
@@ -81,6 +98,97 @@ Replace `{provider-id}` with your chosen Provider ID.
    - Client Secret: [Your Okta Client Secret]
    - Click "Discover" to auto-fill endpoints
 
+### Example: Authentik SSO Setup
+
+Working Authentik deployments (see [#134](https://github.com/RayLabsHQ/gitea-mirror/issues/134)) follow these steps:
+
+1. In Authentik, create a new **Application** and OIDC **Provider** (implicit flow works well for testing).
+2. Start creating an SSO provider inside Gitea Mirror so you can copy the redirect URL shown (`https://your-domain.com/api/auth/sso/callback/authentik` if you pick `authentik` as your Provider ID).
+3. Paste that redirect URL into the Authentik Provider configuration and finish creating the provider.
+4. Copy the Authentik issuer URL, client ID, and client secret.
+5. Back in Gitea Mirror:
+   - Issuer URL: the exact value from Authentik (keep any trailing slash Authentik shows).
+   - Provider ID: match the one you used in step 2.
+   - Click **Discover** so Gitea Mirror stores the authorization, token, and JWKS endpoints (Authentik publishes them via discovery).
+   - Domain: enter the email domain you expect to match (e.g. `example.com`).
+6. Save the provider and test the login flow.
+
+Notes:
+- Make sure `BETTER_AUTH_URL` and (if you serve the UI from multiple origins) `BETTER_AUTH_TRUSTED_ORIGINS` point at the public URL users reach. A mismatch can surface as 500 errors after redirect.
+- Set the **Domain** field to the email domain your Authentik users actually have. Auto-linking to an existing local admin only happens for emails in that domain — see [Account Linking](#account-linking) for the trust model. (Authentik's default email scope mapping returns `email_verified: False` for OIDC clients, which is why account linking is gated on the domain match here rather than the IdP's verified-email claim.)
+- If you created an Authentik provider before v3.8.10 you should delete it and re-add it after upgrading; older versions saved incomplete endpoint data which leads to the `url.startsWith` error explained in the Troubleshooting section.
+
+## Setting up Header / Forward Authentication
+
+Header authentication trusts a reverse proxy (Authentik, Authelia, oauth2-proxy, Traefik forward-auth, etc.) to authenticate users upstream and pass identity in HTTP headers. When enabled, Gitea Mirror reads the configured headers on each request and resolves the user automatically — no login form, no callback.
+
+> **Important — operator-controlled by design.** Header auth is configured via environment variables only, not the UI. This is intentional: trusting a header means trusting whatever upstream sets it, and that decision belongs to the operator who controls the reverse proxy, not to a logged-in user inside the app. Make sure your reverse proxy strips these headers from inbound client requests, otherwise anyone can spoof them.
+
+### Environment variables
+
+| Variable | Description | Default |
+|----------|-------------|---------|
+| `HEADER_AUTH_ENABLED` | Master switch — must be `true` to enable | `false` |
+| `HEADER_AUTH_USER_HEADER` | Header containing the username | `X-Authentik-Username` |
+| `HEADER_AUTH_EMAIL_HEADER` | Header containing the email address | `X-Authentik-Email` |
+| `HEADER_AUTH_NAME_HEADER` | Header containing the display name | `X-Authentik-Name` |
+| `HEADER_AUTH_AUTO_PROVISION` | If `true`, create a new user when an unknown username arrives. If `false`, unknown users are rejected. | `false` |
+| `HEADER_AUTH_ALLOWED_DOMAINS` | Comma-separated email domain allowlist. Empty = allow any. | _(empty)_ |
+
+See also: [`docs/ENVIRONMENT_VARIABLES.md`](./ENVIRONMENT_VARIABLES.md#header-authentication-reverse-proxy-sso).
+
+### Example: Docker Compose with Authentik
+
+```yaml
+services:
+  gitea-mirror:
+    image: ghcr.io/raylabshq/gitea-mirror:latest
+    environment:
+      HEADER_AUTH_ENABLED: "true"
+      HEADER_AUTH_USER_HEADER: "X-Authentik-Username"
+      HEADER_AUTH_EMAIL_HEADER: "X-Authentik-Email"
+      HEADER_AUTH_NAME_HEADER: "X-Authentik-Name"
+      HEADER_AUTH_AUTO_PROVISION: "true"
+      HEADER_AUTH_ALLOWED_DOMAINS: "example.com,example.org"
+```
+
+The defaults are Authentik-shaped, so for an Authentik proxy provider you generally only need to set `HEADER_AUTH_ENABLED=true` (and `HEADER_AUTH_AUTO_PROVISION=true` if you want first-login self-registration).
+
+### Example: Authelia
+
+Authelia uses different header names — override them:
+
+```yaml
+environment:
+  HEADER_AUTH_ENABLED: "true"
+  HEADER_AUTH_USER_HEADER: "Remote-User"
+  HEADER_AUTH_EMAIL_HEADER: "Remote-Email"
+  HEADER_AUTH_NAME_HEADER: "Remote-Name"
+  HEADER_AUTH_AUTO_PROVISION: "true"
+```
+
+Then configure Authelia's `authz` rules to protect the gitea-mirror route and inject the `Remote-*` headers.
+
+### Behaviour and lookup order
+
+- The middleware checks for a cookie session **first**. Header auth only fires when there is no existing session, so users who logged in via password or SSO are not affected.
+- Lookup is by `HEADER_AUTH_USER_HEADER` value matched against `users.username`; if no match and `HEADER_AUTH_EMAIL_HEADER` is set, a second lookup is tried against `users.email`.
+- If neither matches:
+  - With `HEADER_AUTH_AUTO_PROVISION=true`, a new user row is created (email defaults to `<username>@header-auth.local` if no email header is present).
+  - With `HEADER_AUTH_AUTO_PROVISION=false`, the request is rejected with a warning logged.
+- If `HEADER_AUTH_ALLOWED_DOMAINS` is non-empty and the email header arrives, the email's domain must be in the list or the request is rejected.
+
+### Verifying it's enabled
+
+When header auth is active, the Authentication settings page renders a green "Header Authentication / Via reverse proxy" badge under the auth-methods status block. You can also probe `/api/auth/header-status`, which returns `{ "enabled": true, ... }` once the env vars are set.
+
+### Security checklist
+
+1. **Strip the headers at your edge.** Your reverse proxy must remove inbound `HEADER_AUTH_USER_HEADER` / email / name headers from client requests before re-injecting its own. Otherwise any unauthenticated client can set `X-Authentik-Username: admin` and walk in.
+2. **Bind the app to the proxy only.** Don't expose Gitea Mirror's port directly to the network when header auth is on; only the trusted proxy should reach it.
+3. **Use HTTPS between proxy and clients.** Headers travel in plaintext on the link they cross.
+4. **Be conservative with `HEADER_AUTH_AUTO_PROVISION`.** With it off, you provision users in the UI/DB once and the proxy fills in sessions thereafter — safer for shared deployments.
+
 ## Setting up OIDC Provider
 
 The OIDC Provider feature allows other applications to use Gitea Mirror as their authentication provider.
@@ -165,6 +273,8 @@ When an application requests authentication:
 1. **"Invalid origin" error**: Check that your Gitea Mirror URL matches the configured redirect URI
 2. **"Provider not found" error**: Ensure the provider is properly configured and enabled
 3. **Redirect loop**: Verify the redirect URI in both Gitea Mirror and the SSO provider match exactly
+4. **`?error=UNKNOWN` on the homepage after a successful upstream login** (or `?error=account%20not%20linked` in development): the SSO callback succeeded but Better Auth refused to link the SSO identity to an existing local account. The most common cause is the SSO provider's registered **Domain** not matching the user's actual email domain — see [Account Linking](#account-linking). Set `BETTER_AUTH_LOG_LEVEL=debug` to see Better Auth's full callback trace (look for "User already exist but account isn't linked to ...") and confirm the diagnosis. The same symptom in production gets sanitized to `UNKNOWN` by Better Auth's error page before the redirect, which is why the visible error is opaque.
+5. **`TypeError: undefined is not an object (evaluating 'url.startsWith')`**: This indicates the stored provider configuration is missing OIDC endpoints. Delete the provider from Gitea Mirror and re-register it using the **Discover** button so authorization/token URLs are saved (see [#73](https://github.com/RayLabsHQ/gitea-mirror/issues/73) and [#122](https://github.com/RayLabsHQ/gitea-mirror/issues/122) for examples).
 
 ### OIDC Provider Issues
 
@@ -202,4 +312,4 @@ This immediately prevents the application from authenticating new users.
 If migrating from the previous JWT-based authentication:
 - Existing users remain unaffected
 - Users can continue using email/password authentication
-- SSO can be added as an additional authentication method
+- SSO can be added as an additional authentication method

docs/SSO_TESTING.md

@@ -125,11 +125,59 @@ npm start
 
 ### Debug Mode:
 
-Enable debug logging by setting environment variable:
+> **Note:** Better Auth uses its own logger and does **not** read the `DEBUG`
+> environment variable (it is not based on the `debug` npm package). An older
+> version of this guide suggested `DEBUG=better-auth:*` — that has no effect.
+
+Better Auth's logger defaults to the `warn` level, so SSO/OIDC sign-in and
+callback details are hidden. Set the log level to `debug` to surface the full
+trace:
+
 ```bash
-DEBUG=better-auth:* bun run dev
+# Local dev
+BETTER_AUTH_LOG_LEVEL=debug bun run dev
 ```
 
+```yaml
+# Docker Compose
+services:
+  gitea-mirror:
+    environment:
+      - BETTER_AUTH_LOG_LEVEL=debug
+```
+
+Then watch the server logs (e.g. `docker compose logs -f gitea-mirror`) while you
+attempt an SSO login. Lines are prefixed with `[Better Auth]:`. Accepted values
+are `debug`, `info`, `warn`, and `error`.
+
+#### Debugging a login that bounces back to `/login`
+
+If clicking the SSO button sends you to the provider and then straight back to
+the login screen, the OAuth flow itself usually succeeded but **no session
+cookie was persisted**. Work through these checks:
+
+1. **Enable `BETTER_AUTH_LOG_LEVEL=debug`** (above) and look for errors during
+   the `/api/auth/sso/callback/<provider-id>` request.
+2. **Check for `?error=UNKNOWN` on the landing URL** (or `?error=account%20not%20linked` in dev).
+   That's Better Auth's account-linking step refusing to attach the SSO identity
+   to an existing email/password account. The debug log line to look for is
+   `User already exist but account isn't linked to <providerId>`. The fix is
+   almost always to set the SSO provider's **Domain** field to the email domain
+   your users actually have — auto-linking is gated on that domain match.
+   See [docs/SSO-OIDC-SETUP.md#account-linking](./SSO-OIDC-SETUP.md#account-linking).
+3. **Check the redirect URI** registered in your IdP exactly matches
+   `https://<your-domain>/api/auth/sso/callback/<provider-id>` (scheme, host,
+   and provider ID — no trailing slash).
+4. **Confirm the session cookie is set.** In the browser DevTools → Network,
+   inspect the callback response for a `Set-Cookie: better-auth-session=…`
+   header, and DevTools → Application → Cookies for the stored cookie. Behind a
+   reverse proxy, ensure `BETTER_AUTH_URL` is your **external HTTPS** URL so the
+   cookie is issued with the correct domain and `Secure` flag, and that the
+   proxy forwards `X-Forwarded-Proto: https` and `X-Forwarded-Host`.
+5. **A `401` on `/api/sso/applications` is unrelated** to client login — that
+   endpoint backs the OAuth *provider* (consent) management UI and requires an
+   existing session. It is not part of the Authentik/OIDC sign-in flow.
+
 ## Testing Different Scenarios
 
 ### 1. New User Registration

docs/testing.md

@@ -1,127 +0,0 @@
-# Testing in Gitea Mirror
-
-This document provides guidance on testing in the Gitea Mirror project.
-
-## Current Status
-
-The project now uses Bun's built-in test runner, which is Jest-compatible and provides a fast, reliable testing experience. We've migrated away from Vitest due to compatibility issues with Bun.
-
-## Running Tests
-
-To run tests, use the following commands:
-
-```bash
-# Run all tests
-bun test
-
-# Run tests in watch mode (automatically re-run when files change)
-bun test --watch
-
-# Run tests with coverage reporting
-bun test --coverage
-```
-
-## Test File Naming Conventions
-
-Bun's test runner automatically discovers test files that match the following patterns:
-
-- `*.test.{js|jsx|ts|tsx}`
-- `*_test.{js|jsx|ts|tsx}`
-- `*.spec.{js|jsx|ts|tsx}`
-- `*_spec.{js|jsx|ts|tsx}`
-
-## Writing Tests
-
-The project uses Bun's test runner with a Jest-compatible API. Here's an example test:
-
-```typescript
-// example.test.ts
-import { describe, test, expect } from "bun:test";
-
-describe("Example Test", () => {
-  test("should pass", () => {
-    expect(true).toBe(true);
-  });
-});
-```
-
-### Testing React Components
-
-For testing React components, we use React Testing Library:
-
-```typescript
-// component.test.tsx
-import { describe, test, expect } from "bun:test";
-import { render, screen } from "@testing-library/react";
-import MyComponent from "../components/MyComponent";
-
-describe("MyComponent", () => {
-  test("renders correctly", () => {
-    render(<MyComponent />);
-    expect(screen.getByText("Hello World")).toBeInTheDocument();
-  });
-});
-```
-
-## Test Setup
-
-The test setup is defined in `src/tests/setup.bun.ts` and includes:
-
-- Automatic cleanup after each test
-- Setup for any global test environment needs
-
-## Mocking
-
-Bun's test runner provides built-in mocking capabilities:
-
-```typescript
-import { test, expect, mock } from "bun:test";
-
-// Create a mock function
-const mockFn = mock(() => "mocked value");
-
-test("mock function", () => {
-  const result = mockFn();
-  expect(result).toBe("mocked value");
-  expect(mockFn).toHaveBeenCalled();
-});
-
-// Mock a module
-mock.module("./some-module", () => {
-  return {
-    someFunction: () => "mocked module function"
-  };
-});
-```
-
-## CI Integration
-
-The CI workflow has been updated to use Bun's test runner. Tests are automatically run as part of the CI pipeline.
-
-## Test Coverage
-
-To generate test coverage reports, run:
-
-```bash
-bun test --coverage
-```
-
-This will generate a coverage report in the `coverage` directory.
-
-## Types of Tests
-
-The project includes several types of tests:
-
-1. **Unit Tests**: Testing individual functions and utilities
-2. **API Tests**: Testing API endpoints
-3. **Component Tests**: Testing React components
-4. **Integration Tests**: Testing how components work together
-
-## Future Improvements
-
-When expanding the test suite, consider:
-
-1. Adding more comprehensive API endpoint tests
-2. Increasing component test coverage
-3. Setting up end-to-end tests with a tool like Playwright
-4. Adding performance tests for critical paths

drizzle/0006_military_la_nuit.sql

@@ -0,0 +1,4 @@
+ALTER TABLE `accounts` ADD `id_token` text;--> statement-breakpoint
+ALTER TABLE `accounts` ADD `access_token_expires_at` integer;--> statement-breakpoint
+ALTER TABLE `accounts` ADD `refresh_token_expires_at` integer;--> statement-breakpoint
+ALTER TABLE `accounts` ADD `scope` text;

drizzle/0007_whole_hellion.sql

@@ -0,0 +1,18 @@
+ALTER TABLE `organizations` ADD `normalized_name` text NOT NULL DEFAULT '';--> statement-breakpoint
+UPDATE `organizations` SET `normalized_name` = lower(trim(`name`));--> statement-breakpoint
+DELETE FROM `organizations`
+WHERE rowid NOT IN (
+  SELECT MIN(rowid)
+  FROM `organizations`
+  GROUP BY `user_id`, `normalized_name`
+);--> statement-breakpoint
+CREATE UNIQUE INDEX `uniq_organizations_user_normalized_name` ON `organizations` (`user_id`,`normalized_name`);--> statement-breakpoint
+ALTER TABLE `repositories` ADD `normalized_full_name` text NOT NULL DEFAULT '';--> statement-breakpoint
+UPDATE `repositories` SET `normalized_full_name` = lower(trim(`full_name`));--> statement-breakpoint
+DELETE FROM `repositories`
+WHERE rowid NOT IN (
+  SELECT MIN(rowid)
+  FROM `repositories`
+  GROUP BY `user_id`, `normalized_full_name`
+);--> statement-breakpoint
+CREATE UNIQUE INDEX `uniq_repositories_user_normalized_full_name` ON `repositories` (`user_id`,`normalized_full_name`);

drizzle/0008_serious_thena.sql

@@ -0,0 +1 @@
+ALTER TABLE `repositories` ADD `metadata` text;

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/0012_oauth_provider_migration.sql

@@ -0,0 +1,126 @@
+-- Migrate the OAuth/OIDC *provider* feature from the deprecated
+-- `oidc-provider` plugin to `@better-auth/oauth-provider`.
+--
+-- Tables: oauth_applications -> oauth_clients, oauth_access_tokens reshaped,
+-- new oauth_refresh_tokens, oauth_consent -> oauth_consents, plus a `jwks`
+-- table for the `jwt` plugin (id_token signing keys).
+--
+-- Data preservation:
+--   * Registered clients are copied from oauth_applications into oauth_clients,
+--     converting the legacy comma-separated `redirect_urls` into the JSON
+--     string[] (`redirect_uris`) the new adapter expects.
+--   * Access tokens and consent records are NOT migrated: access tokens are
+--     short-lived (and the column shape changed entirely), and consents are
+--     cheaply re-granted on next authorization. Both old tables are dropped.
+--
+-- NOTE: legacy client secrets were stored in plaintext, whereas the new
+-- provider stores them hashed. Migrated client secrets will therefore not
+-- validate as-is — affected applications must rotate their secret after
+-- upgrade.
+
+CREATE TABLE `oauth_clients` (
+	`id` text PRIMARY KEY NOT NULL,
+	`client_id` text NOT NULL,
+	`client_secret` text,
+	`name` text,
+	`disabled` integer DEFAULT false,
+	`skip_consent` integer,
+	`enable_end_session` integer,
+	`subject_type` text,
+	`scopes` text,
+	`user_id` text,
+	`uri` text,
+	`icon` text,
+	`contacts` text,
+	`tos` text,
+	`policy` text,
+	`software_id` text,
+	`software_version` text,
+	`software_statement` text,
+	`redirect_uris` text NOT NULL,
+	`post_logout_redirect_uris` text,
+	`token_endpoint_auth_method` text,
+	`grant_types` text,
+	`response_types` text,
+	`public` integer,
+	`type` text,
+	`require_pkce` integer,
+	`reference_id` text,
+	`metadata` text,
+	`created_at` integer DEFAULT (unixepoch()),
+	`updated_at` integer DEFAULT (unixepoch()),
+	FOREIGN KEY (`user_id`) REFERENCES `users`(`id`) ON UPDATE no action ON DELETE no action
+);
+--> statement-breakpoint
+CREATE UNIQUE INDEX `oauth_clients_client_id_unique` ON `oauth_clients` (`client_id`);--> statement-breakpoint
+CREATE INDEX `idx_oauth_clients_client_id` ON `oauth_clients` (`client_id`);--> statement-breakpoint
+CREATE INDEX `idx_oauth_clients_user_id` ON `oauth_clients` (`user_id`);--> statement-breakpoint
+INSERT INTO `oauth_clients` (
+	`id`, `client_id`, `client_secret`, `name`, `disabled`, `user_id`,
+	`redirect_uris`, `type`, `metadata`, `created_at`, `updated_at`
+)
+SELECT
+	`id`, `client_id`, `client_secret`, `name`, `disabled`, `user_id`,
+	'["' || replace(`redirect_urls`, ',', '","') || '"]',
+	`type`, `metadata`, `created_at`, `updated_at`
+FROM `oauth_applications`;--> statement-breakpoint
+DROP TABLE `oauth_applications`;--> statement-breakpoint
+DROP TABLE `oauth_access_tokens`;--> statement-breakpoint
+CREATE TABLE `oauth_access_tokens` (
+	`id` text PRIMARY KEY NOT NULL,
+	`token` text,
+	`client_id` text NOT NULL,
+	`session_id` text,
+	`user_id` text,
+	`reference_id` text,
+	`refresh_id` text,
+	`expires_at` integer,
+	`created_at` integer DEFAULT (unixepoch()),
+	`scopes` text NOT NULL,
+	FOREIGN KEY (`user_id`) REFERENCES `users`(`id`) ON UPDATE no action ON DELETE no action
+);
+--> statement-breakpoint
+CREATE UNIQUE INDEX `oauth_access_tokens_token_unique` ON `oauth_access_tokens` (`token`);--> statement-breakpoint
+CREATE INDEX `idx_oauth_access_tokens_token` ON `oauth_access_tokens` (`token`);--> statement-breakpoint
+CREATE INDEX `idx_oauth_access_tokens_client_id` ON `oauth_access_tokens` (`client_id`);--> statement-breakpoint
+CREATE INDEX `idx_oauth_access_tokens_user_id` ON `oauth_access_tokens` (`user_id`);--> statement-breakpoint
+CREATE TABLE `oauth_refresh_tokens` (
+	`id` text PRIMARY KEY NOT NULL,
+	`token` text NOT NULL,
+	`client_id` text NOT NULL,
+	`session_id` text,
+	`user_id` text NOT NULL,
+	`reference_id` text,
+	`expires_at` integer,
+	`created_at` integer DEFAULT (unixepoch()),
+	`revoked` integer,
+	`auth_time` integer,
+	`scopes` text NOT NULL,
+	FOREIGN KEY (`user_id`) REFERENCES `users`(`id`) ON UPDATE no action ON DELETE no action
+);
+--> statement-breakpoint
+CREATE UNIQUE INDEX `oauth_refresh_tokens_token_unique` ON `oauth_refresh_tokens` (`token`);--> statement-breakpoint
+CREATE INDEX `idx_oauth_refresh_tokens_token` ON `oauth_refresh_tokens` (`token`);--> statement-breakpoint
+CREATE INDEX `idx_oauth_refresh_tokens_client_id` ON `oauth_refresh_tokens` (`client_id`);--> statement-breakpoint
+CREATE INDEX `idx_oauth_refresh_tokens_user_id` ON `oauth_refresh_tokens` (`user_id`);--> statement-breakpoint
+DROP TABLE `oauth_consent`;--> statement-breakpoint
+CREATE TABLE `oauth_consents` (
+	`id` text PRIMARY KEY NOT NULL,
+	`client_id` text NOT NULL,
+	`user_id` text,
+	`reference_id` text,
+	`scopes` text NOT NULL,
+	`created_at` integer DEFAULT (unixepoch()),
+	`updated_at` integer DEFAULT (unixepoch()),
+	FOREIGN KEY (`user_id`) REFERENCES `users`(`id`) ON UPDATE no action ON DELETE no action
+);
+--> statement-breakpoint
+CREATE INDEX `idx_oauth_consents_client_id` ON `oauth_consents` (`client_id`);--> statement-breakpoint
+CREATE INDEX `idx_oauth_consents_user_id` ON `oauth_consents` (`user_id`);--> statement-breakpoint
+CREATE TABLE `jwks` (
+	`id` text PRIMARY KEY NOT NULL,
+	`public_key` text NOT NULL,
+	`private_key` text NOT NULL,
+	`created_at` integer DEFAULT (unixepoch()) NOT NULL,
+	`expires_at` integer
+);

drizzle/0013_slim_galactus.sql

@@ -0,0 +1,35 @@
+PRAGMA foreign_keys=OFF;--> statement-breakpoint
+CREATE TABLE `__new_organizations` (
+	`id` text PRIMARY KEY NOT NULL,
+	`user_id` text NOT NULL,
+	`config_id` text NOT NULL,
+	`name` text NOT NULL,
+	`normalized_name` text NOT NULL,
+	`avatar_url` text NOT NULL,
+	`membership_role` text DEFAULT 'member' NOT NULL,
+	`is_included` integer DEFAULT true NOT NULL,
+	`destination_org` text,
+	`status` text DEFAULT 'imported' NOT NULL,
+	`last_mirrored` integer,
+	`error_message` text,
+	`repository_count` integer DEFAULT 0 NOT NULL,
+	`public_repository_count` integer,
+	`private_repository_count` integer,
+	`fork_repository_count` integer,
+	`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_organizations`("id", "user_id", "config_id", "name", "normalized_name", "avatar_url", "membership_role", "is_included", "destination_org", "status", "last_mirrored", "error_message", "repository_count", "public_repository_count", "private_repository_count", "fork_repository_count", "created_at", "updated_at") SELECT "id", "user_id", "config_id", "name", "normalized_name", "avatar_url", "membership_role", "is_included", "destination_org", "status", "last_mirrored", "error_message", "repository_count", "public_repository_count", "private_repository_count", "fork_repository_count", "created_at", "updated_at" FROM `organizations`;--> statement-breakpoint
+DROP TABLE `organizations`;--> statement-breakpoint
+ALTER TABLE `__new_organizations` RENAME TO `organizations`;--> statement-breakpoint
+PRAGMA foreign_keys=ON;--> statement-breakpoint
+CREATE INDEX `idx_organizations_user_id` ON `organizations` (`user_id`);--> statement-breakpoint
+CREATE INDEX `idx_organizations_config_id` ON `organizations` (`config_id`);--> statement-breakpoint
+CREATE INDEX `idx_organizations_status` ON `organizations` (`status`);--> statement-breakpoint
+CREATE INDEX `idx_organizations_is_included` ON `organizations` (`is_included`);--> statement-breakpoint
+CREATE UNIQUE INDEX `uniq_organizations_user_normalized_name` ON `organizations` (`user_id`,`normalized_name`);--> statement-breakpoint
+ALTER TABLE `sso_providers` ADD `saml_config` text;--> statement-breakpoint
+ALTER TABLE `sso_providers` ADD `domain_verified` integer DEFAULT true NOT NULL;

drizzle/meta/_journal.json

@@ -43,6 +43,62 @@
       "when": 1757786449446,
       "tag": "0005_polite_preak",
       "breakpoints": true
+    },
+    {
+      "idx": 6,
+      "version": "6",
+      "when": 1761483928546,
+      "tag": "0006_military_la_nuit",
+      "breakpoints": true
+    },
+    {
+      "idx": 7,
+      "version": "6",
+      "when": 1761534391115,
+      "tag": "0007_whole_hellion",
+      "breakpoints": true
+    },
+    {
+      "idx": 8,
+      "version": "6",
+      "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
+    },
+    {
+      "idx": 12,
+      "version": "6",
+      "when": 1774062000000,
+      "tag": "0012_oauth_provider_migration",
+      "breakpoints": true
+    },
+    {
+      "idx": 13,
+      "version": "6",
+      "when": 1780377747526,
+      "tag": "0013_slim_galactus",
+      "breakpoints": true
     }
   ]
 }

flake.lock

@@ -0,0 +1,170 @@
+{
+  "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_2"
+      },
+      "locked": {
+        "lastModified": 1731533236,
+        "narHash": "sha256-l0KFg5HjrsfsO/JpG+r7fRrqm12kzFHyUHqHCVpMMbI=",
+        "owner": "numtide",
+        "repo": "flake-utils",
+        "rev": "11707dc2f618dd54ca8739b309ec4fc024de578b",
+        "type": "github"
+      },
+      "original": {
+        "owner": "numtide",
+        "repo": "flake-utils",
+        "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,
+        "narHash": "sha256-o9KF3DJL7g7iYMZq9SWgfS1BFlNbsm6xplRjVlOCkXI=",
+        "owner": "NixOS",
+        "repo": "nixpkgs",
+        "rev": "08dacfca559e1d7da38f3cf05f1f45ee9bfd213c",
+        "type": "github"
+      },
+      "original": {
+        "owner": "NixOS",
+        "ref": "nixos-unstable",
+        "repo": "nixpkgs",
+        "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"
+      }
+    },
+    "systems": {
+      "locked": {
+        "lastModified": 1681028828,
+        "narHash": "sha256-Vy1rq5AaRuLzOxct8nz4T6wlgyUR7zLU309k9mBC768=",
+        "owner": "nix-systems",
+        "repo": "default",
+        "rev": "da67096a3b9bf56a91d16901293e51ba5b49a27e",
+        "type": "github"
+      },
+      "original": {
+        "owner": "nix-systems",
+        "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",
+  "version": 7
+}

flake.nix

@@ -0,0 +1,468 @@
+{
+  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, 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.14.1";
+
+          src = ./.;
+
+          nativeBuildInputs = [
+            pkgs.bun
+            b2n.hook
+          ];
+
+          buildInputs = with pkgs; [
+            sqlite
+            openssl
+          ];
+
+          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 = ''
+            runHook preBuild
+            export HOME=$TMPDIR
+
+            # 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
+
+            # Copy the built application
+            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'
+#!${pkgs.bash}/bin/bash
+set -e
+
+# === DEFAULT CONFIGURATION ===
+# These match docker-compose.alt.yml defaults
+export DATA_DIR=''${DATA_DIR:-"$HOME/.local/share/gitea-mirror"}
+export DATABASE_URL=''${DATABASE_URL:-"file:$DATA_DIR/gitea-mirror.db"}
+export HOST=''${HOST:-"0.0.0.0"}
+export PORT=''${PORT:-"4321"}
+export NODE_ENV=''${NODE_ENV:-"production"}
+
+# Better Auth configuration
+export BETTER_AUTH_URL=''${BETTER_AUTH_URL:-"http://localhost:4321"}
+export BETTER_AUTH_TRUSTED_ORIGINS=''${BETTER_AUTH_TRUSTED_ORIGINS:-"http://localhost:4321"}
+export PUBLIC_BETTER_AUTH_URL=''${PUBLIC_BETTER_AUTH_URL:-"http://localhost:4321"}
+
+# Concurrency settings (match docker-compose.alt.yml)
+export MIRROR_ISSUE_CONCURRENCY=''${MIRROR_ISSUE_CONCURRENCY:-3}
+export MIRROR_PULL_REQUEST_CONCURRENCY=''${MIRROR_PULL_REQUEST_CONCURRENCY:-5}
+
+# Create data directory
+mkdir -p "$DATA_DIR"
+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"
+ENCRYPTION_SECRET_FILE="$DATA_DIR/.encryption_secret"
+
+# Generate BETTER_AUTH_SECRET if not provided
+if [ -z "$BETTER_AUTH_SECRET" ]; then
+  if [ -f "$BETTER_AUTH_SECRET_FILE" ]; then
+    echo "Using previously generated BETTER_AUTH_SECRET"
+    export BETTER_AUTH_SECRET=$(cat "$BETTER_AUTH_SECRET_FILE")
+  else
+    echo "Generating a secure random BETTER_AUTH_SECRET"
+    GENERATED_SECRET=$(${pkgs.openssl}/bin/openssl rand -hex 32)
+    export BETTER_AUTH_SECRET="$GENERATED_SECRET"
+    echo "$GENERATED_SECRET" > "$BETTER_AUTH_SECRET_FILE"
+    chmod 600 "$BETTER_AUTH_SECRET_FILE"
+    echo "✅ BETTER_AUTH_SECRET generated and saved to $BETTER_AUTH_SECRET_FILE"
+  fi
+fi
+
+# Generate ENCRYPTION_SECRET if not provided
+if [ -z "$ENCRYPTION_SECRET" ]; then
+  if [ -f "$ENCRYPTION_SECRET_FILE" ]; then
+    echo "Using previously generated ENCRYPTION_SECRET"
+    export ENCRYPTION_SECRET=$(cat "$ENCRYPTION_SECRET_FILE")
+  else
+    echo "Generating a secure random ENCRYPTION_SECRET"
+    GENERATED_ENCRYPTION_SECRET=$(${pkgs.openssl}/bin/openssl rand -base64 36)
+    export ENCRYPTION_SECRET="$GENERATED_ENCRYPTION_SECRET"
+    echo "$GENERATED_ENCRYPTION_SECRET" > "$ENCRYPTION_SECRET_FILE"
+    chmod 600 "$ENCRYPTION_SECRET_FILE"
+    echo "✅ ENCRYPTION_SECRET generated and saved to $ENCRYPTION_SECRET_FILE"
+  fi
+fi
+
+# === DATABASE INITIALIZATION ===
+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"
+else
+  echo "Database already exists, Drizzle will check for pending migrations on startup..."
+fi
+
+# === STARTUP SCRIPTS ===
+# Initialize configuration from environment variables
+echo "Checking for environment configuration..."
+if [ -f "scripts/startup-env-config.ts" ]; then
+  echo "Loading configuration from environment variables..."
+  ${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 "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 "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
+
+# === SIGNAL HANDLING ===
+shutdown_handler() {
+  echo "🛑 Received shutdown signal, forwarding to application..."
+  if [ ! -z "$APP_PID" ]; then
+    kill -TERM "$APP_PID" 2>/dev/null || true
+    wait "$APP_PID" 2>/dev/null || true
+  fi
+  exit 0
+}
+
+trap 'shutdown_handler' TERM INT HUP
+
+# === START APPLICATION ===
+echo "Starting Gitea Mirror..."
+echo "Access the web interface at $BETTER_AUTH_URL"
+${pkgs.bun}/bin/bun dist/server/entry.mjs &
+APP_PID=$!
+
+wait "$APP_PID"
+EOF
+            chmod +x $out/bin/gitea-mirror
+
+            # Create database management helper
+            cat > $out/bin/gitea-mirror-db <<'EOF'
+#!${pkgs.bash}/bin/bash
+export DATA_DIR=''${DATA_DIR:-"$HOME/.local/share/gitea-mirror"}
+mkdir -p "$DATA_DIR"
+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; {
+            description = "Self-hosted GitHub to Gitea mirroring service";
+            homepage = "https://github.com/RayLabsHQ/gitea-mirror";
+            license = licenses.mit;
+            maintainers = [ ];
+            platforms = platforms.linux ++ platforms.darwin;
+          };
+        };
+
+      in
+      {
+        packages = {
+          default = gitea-mirror;
+          gitea-mirror = gitea-mirror;
+        };
+
+        # Development shell
+        devShells.default = pkgs.mkShell {
+          buildInputs = with pkgs; [
+            bun
+            sqlite
+            openssl
+            b2n
+          ];
+
+          shellHook = ''
+            echo "🚀 Gitea Mirror development environment"
+            echo ""
+            echo "Quick start:"
+            echo "  bun install       # Install dependencies"
+            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"
+          '';
+        };
+
+      }
+    )) // {
+      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.${pkgs.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";
+            };
+          };
+
+          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;
+      };
+    };
+}

helm/gitea-mirror/Chart.yaml

@@ -2,8 +2,8 @@ apiVersion: v2
 name: gitea-mirror
 description: Kubernetes helm chart for gitea-mirror
 type: application
-version: 0.0.1
-appVersion: 3.7.2
+version: 0.0.2
+appVersion: "3.24.0"
 icon: https://github.com/RayLabsHQ/gitea-mirror/blob/main/.github/assets/logo.png
 keywords:
   - git

helm/gitea-mirror/README.md

@@ -29,7 +29,7 @@ kubectl create namespace gitea-mirror
 helm upgrade --install gitea-mirror ./helm/gitea-mirror   --namespace gitea-mirror   --set "gitea-mirror.github.username=<your-gh-username>"   --set "gitea-mirror.github.token=<your-gh-token>"   --set "gitea-mirror.gitea.url=https://gitea.example.com"   --set "gitea-mirror.gitea.token=<your-gitea-token>"
 ```
 
-The default Service is `ClusterIP` on port `8080`. You can expose it via Ingress or Gateway API; see below.
+The default Service is `ClusterIP` on port `4321`. You can expose it via Ingress or Gateway API; see below.
 
 ---
 
@@ -78,7 +78,7 @@ If you enabled persistence with a PVC the data may persist; delete the PVC manua
 
 | Key | Type | Default | Description |
 | --- | --- | --- | --- |
-| `deployment.port` | int | `8080` | Container port & named `http` port. |
+| `deployment.port` | int | `4321` | Container port & named `http` port. |
 | `deployment.strategy.type` | string | `Recreate` | Update strategy (`Recreate` or `RollingUpdate`). |
 | `deployment.strategy.rollingUpdate.maxUnavailable/maxSurge` | string/int | — | Used when `type=RollingUpdate`. |
 | `deployment.env` | list | `[]` | Extra environment variables. |
@@ -95,7 +95,7 @@ If you enabled persistence with a PVC the data may persist; delete the PVC manua
 | Key | Type | Default | Description |
 | --- | --- | --- | --- |
 | `service.type` | string | `ClusterIP` | Service type. |
-| `service.port` | int | `8080` | Service port. |
+| `service.port` | int | `4321` | Service port. |
 | `service.clusterIP` | string | `None` | ClusterIP (only when `type=ClusterIP`). |
 | `service.externalTrafficPolicy` | string | `""` | External traffic policy (LB). |
 | `service.loadBalancerIP` | string | `""` | LoadBalancer IP. |
@@ -228,7 +228,7 @@ ingress:
         - mirror.example.com
 ```
 
-This creates an Ingress routing `/` to the service on port `8080`.
+This creates an Ingress routing `/` to the service on port `4321`.
 
 ### Using Gateway API (HTTPRoute)
 
@@ -257,7 +257,7 @@ By default, the chart provisions a PVC named `gitea-mirror-storage` with `1Gi` a
 
 ## Environment & health endpoints
 
-The container listens on `PORT` (defaults to `deployment.port` = `8080`) and exposes `GET /api/health` for liveness/readiness/startup probes.
+The container listens on `PORT` (defaults to `deployment.port` = `4321`) and exposes `GET /api/health` for liveness/readiness/startup probes.
 
 ---
 

helm/gitea-mirror/values.yaml

@@ -46,7 +46,7 @@ route:
 
 service:
   type: ClusterIP
-  port: 8080
+  port: 4321
   clusterIP: None
   annotations: {}
   externalTrafficPolicy:
@@ -55,7 +55,7 @@ service:
   loadBalancerClass:
 
 deployment:
-  port: 8080
+  port: 4321
   strategy:
     type: Recreate
   env: []

package.json

@@ -1,7 +1,7 @@
 {
   "name": "gitea-mirror",
   "type": "module",
-  "version": "3.8.6",
+  "version": "3.26.0",
   "engines": {
     "bun": ">=1.2.9"
   },
@@ -16,6 +16,7 @@
     "check-db": "bun scripts/manage-db.ts check",
     "fix-db": "bun scripts/manage-db.ts fix",
     "reset-users": "bun scripts/manage-db.ts reset-users",
+    "reset-password": "bun scripts/manage-db.ts reset-password",
     "db:generate": "bun drizzle-kit generate",
     "db:migrate": "bun drizzle-kit migrate",
     "db:push": "bun drizzle-kit push",
@@ -30,85 +31,102 @@
     "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.20.5",
-    "devalue": "^5.3.2"
+    "@esbuild-kit/esm-loader": "npm:tsx@^4.21.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.5",
-    "@astrojs/mdx": "4.3.7",
-    "@astrojs/node": "9.5.0",
-    "@astrojs/react": "^4.4.0",
-    "@better-auth/sso": "^1.3.28",
-    "@octokit/plugin-throttling": "^11.0.2",
-    "@octokit/rest": "^22.0.0",
-    "@radix-ui/react-accordion": "^1.2.12",
-    "@radix-ui/react-avatar": "^1.1.10",
-    "@radix-ui/react-checkbox": "^1.3.3",
-    "@radix-ui/react-collapsible": "^1.1.12",
-    "@radix-ui/react-dialog": "^1.1.15",
-    "@radix-ui/react-dropdown-menu": "^2.1.16",
-    "@radix-ui/react-hover-card": "^1.1.15",
-    "@radix-ui/react-label": "^2.1.7",
-    "@radix-ui/react-popover": "^1.1.15",
-    "@radix-ui/react-progress": "^1.1.7",
-    "@radix-ui/react-radio-group": "^1.3.8",
-    "@radix-ui/react-scroll-area": "^1.2.10",
-    "@radix-ui/react-select": "^2.2.6",
-    "@radix-ui/react-separator": "^1.1.7",
-    "@radix-ui/react-slot": "^1.2.3",
-    "@radix-ui/react-switch": "^1.2.6",
-    "@radix-ui/react-tabs": "^1.1.13",
-    "@radix-ui/react-tooltip": "^1.2.8",
-    "@tailwindcss/vite": "^4.1.15",
-    "@tanstack/react-virtual": "^3.13.12",
+    "@astrojs/check": "^0.9.9",
+    "@astrojs/mdx": "^7.0.3",
+    "@astrojs/node": "^11.0.2",
+    "@astrojs/react": "^6.0.1",
+    "@better-auth/oauth-provider": "1.6.23",
+    "@better-auth/sso": "1.6.23",
+    "@octokit/plugin-throttling": "^11.0.3",
+    "@octokit/rest": "^22.0.1",
+    "@radix-ui/react-accordion": "^1.2.16",
+    "@radix-ui/react-avatar": "^1.2.2",
+    "@radix-ui/react-checkbox": "^1.3.7",
+    "@radix-ui/react-collapsible": "^1.1.16",
+    "@radix-ui/react-dialog": "^1.1.19",
+    "@radix-ui/react-dropdown-menu": "^2.1.20",
+    "@radix-ui/react-hover-card": "^1.1.19",
+    "@radix-ui/react-label": "^2.1.11",
+    "@radix-ui/react-popover": "^1.1.19",
+    "@radix-ui/react-progress": "^1.1.12",
+    "@radix-ui/react-radio-group": "^1.4.3",
+    "@radix-ui/react-scroll-area": "^1.2.14",
+    "@radix-ui/react-select": "^2.3.3",
+    "@radix-ui/react-separator": "^1.1.11",
+    "@radix-ui/react-slot": "^1.3.0",
+    "@radix-ui/react-switch": "^1.3.3",
+    "@radix-ui/react-tabs": "^1.1.17",
+    "@radix-ui/react-tooltip": "^1.2.12",
+    "@tailwindcss/vite": "^4.3.3",
+    "@tanstack/react-table": "^8.21.3",
+    "@tanstack/react-virtual": "^3.14.6",
     "@types/canvas-confetti": "^1.9.0",
-    "@types/react": "^19.2.2",
-    "@types/react-dom": "^19.2.2",
-    "astro": "^5.14.8",
-    "bcryptjs": "^3.0.2",
-    "better-auth": "^1.3.28",
-    "canvas-confetti": "^1.9.3",
+    "@types/react": "^19.2.17",
+    "@types/react-dom": "^19.2.3",
+    "astro": "^7.1.0",
+    "bcryptjs": "^3.0.3",
+    "better-auth": "1.6.23",
+    "buffer": "^6.0.3",
+    "canvas-confetti": "^1.9.4",
     "class-variance-authority": "^0.7.1",
     "clsx": "^2.1.1",
     "cmdk": "^1.1.1",
-    "dotenv": "^17.2.3",
-    "drizzle-orm": "^0.44.6",
-    "fuse.js": "^7.1.0",
-    "jsonwebtoken": "^9.0.2",
-    "lucide-react": "^0.546.0",
+    "dotenv": "^17.4.2",
+    "drizzle-orm": "^0.45.2",
+    "fuse.js": "^7.5.0",
+    "jsonwebtoken": "^9.0.3",
+    "lucide-react": "^1.24.0",
+    "nanoid": "^6.0.0",
     "next-themes": "^0.4.6",
-    "react": "^19.2.0",
-    "react-dom": "^19.2.0",
-    "react-icons": "^5.5.0",
+    "react": "^19.2.7",
+    "react-dom": "^19.2.7",
+    "react-icons": "^5.7.0",
     "sonner": "^2.0.7",
-    "tailwind-merge": "^3.3.1",
-    "tailwindcss": "^4.1.15",
+    "tailwind-merge": "^3.6.0",
+    "tailwindcss": "^4.3.3",
     "tw-animate-css": "^1.4.0",
-    "typescript": "^5.9.3",
-    "uuid": "^13.0.0",
+    "typescript": "^7.0.2",
+    "uuid": "^14.0.1",
     "vaul": "^1.1.2",
-    "zod": "^4.1.12"
+    "zod": "^4.4.3"
   },
   "devDependencies": {
+    "@playwright/test": "^1.61.1",
     "@testing-library/jest-dom": "^6.9.1",
-    "@testing-library/react": "^16.3.0",
+    "@testing-library/react": "^16.3.2",
     "@types/bcryptjs": "^3.0.0",
-    "@types/bun": "^1.3.0",
+    "@types/bun": "^1.3.14",
     "@types/jsonwebtoken": "^9.0.10",
-    "@types/uuid": "^10.0.0",
-    "@vitejs/plugin-react": "^5.0.4",
-    "drizzle-kit": "^0.31.5",
-    "jsdom": "^26.1.0",
-    "tsx": "^4.20.6",
-    "vitest": "^3.2.4"
+    "@types/node": "^26.1.1",
+    "@types/uuid": "^11.0.0",
+    "@vitejs/plugin-react": "^6.0.3",
+    "drizzle-kit": "^0.31.10",
+    "jsdom": "^29.1.1",
+    "tsx": "^4.23.1",
+    "vitest": "^4.1.10"
   },
-  "packageManager": "bun@1.2.23"
+  "packageManager": "bun@1.3.10"
 }

public/favicon.svg

@@ -0,0 +1,3 @@
+<svg xmlns="http://www.w3.org/2000/svg" version="1.1" xmlns:xlink="http://www.w3.org/1999/xlink" width="512" height="512" viewBox="0 0 512 512"><image width="512" height="512" xlink:href="data:image/png;base64,iVBORw0KGgoAAAANSUhEUgAAAgAAAAIACAYAAAD0eNT6AAAACXBIWXMAAAsTAAALEwEAmpwYAAAAAXNSR0IArs4c6QAAAARnQU1BAACxjwv8YQUAAoeVSURBVHgB7P0HlKXXdR6InnP+eFPFruqcgUZoBAJgADMpUaRIWTZHY3LsGVvWrJlHjjyPsqWxPQ7rLUHLeUbLM09+szyi5zk8pzHpJAclyhSULIomSAokGJFz5wo3/PGct7+9z3+rutFIBCSiybMbhaq69d97/3TP3vvb3/62UsGCBQsWLFiwYMGCBQsWLFiwYMGCBQsWLFiwYMGCBQsWLFiwYMGCBQsWLFiwYMGCBQsWLFiwYMGCBQsWLFiwYMGCBQsWLFiwYMGCBQsWLFiwYMGCBQsWLFiwYMGCBQsWLFiwYMGCBQsWLFiwYMGCBQsWLFiwYMGCBQsWLFiwYMGCBQsWLFiwYMGCBQsWLFiwYMGCBQsWLFiwYMGCBQsWLFiwYMGCBQsWLFiwYMGCBQsWLFiwYMGCBQsWLFiwYMGCBQsWLFiwYMGCBQsWLFiwYMGCBQsWLFiwYMGCBQsWLFiwYMGCBQsWLFiwYMGCBQsWLFiwYMGCBQsWLFiwYMGCBQsWLFiwYMGCBQsWLFiwYMGCBQsWLFiwYMGCBQsWLFiwYMGCBQsWLFiwYMGCBQsWLFiwYMGCBQsWLFiwYMGCBQsWLFiwYMGCBQsWLFiwYMGCBQsWLFiwYMGCBQsWLFiwYMGCBQsWLFiwYMGCBQsWLFiwYMGCBQsWLFiwYMGCBQsWLFiwYMGCBQsWLFiwYMGCBQsWLFiwYMGCBQsWLFiwYMGCBQsWLFiwYMGCBQsWLFiwYMGCBQsWLFiwYMGCBQsWLFiwYMGCBQsWLFiwYMGCBQsWLFiwYMGCBQsWLFiwYMGCBQsWLFiwYMGCBQsWLFiwYMGCBQt2bZtWwYIF+/00/sw55/iXn/qpn7r8M/iTSj3wyQcue+z0h067e3/qXrP977a1ukup9FIaH1rLonPn6Oc8dYvFYv3w8sOuuFTofDl3P/izP9he7TXUT+16m5/8STffIT3f1O3aR6eCBQv2HW0hAAgW7PfZ7rnnHkPfTLmnXNy3vG+l39+z4HSznOh4eXmwsD7q93tt21qnnbOWNkyUshOry3FpFD0zTk0U6Yg+u5YCCe3qmrZFREHbxnnsksXE2lreyxh28Ka2trk03tygBy48/uxXLzx54bFzqR6dX9pcKigYqGgbq4IFC/ZdZSEACBbsVbJ33fOu+C2Lb1lbHC5GNrZxPVOrxbnZSrG5uffUjdctH7/hxGDQG/VXR6uDyWyauLgd7l3ZtzjoLS1Y1Y6SJF1YGA5XKCHP6OVa9fyfz93O+sqsXV/xvO4xV5b1uK7rjacvPH7x0vjchUT3tpuyrgbZwrSopuXG5CL9uZ2lafLs/b/7wLlnts9fWNq3crFqmvH2pbPV9je2Nz/+8Y/XKliwYN8RFgKAYMFeplGyrT/8Ux8erPWPDReXBgv27Pa+ns0OvOlNd6+cuu70db3ecEib9SgbX+sPesuz7emxtqqXRqOFuDfomV2Q+64XVZd9Gi3943R/5z0v+zt+1/inX/wjbB29ljbP+15dOQLWlI2lbZ+qInt+PJlsUoBwjh67cGH8zNZn7/+tZ373vge+plV8du3UgaaaTM58035z6xM//omC9mMeaKhgwYJdExYCgGDBnsc+8rMfSS597VKsFlWkHthKT568aeGNb7t72B8O15rYnti3cuTYsfXDN+dZdksxK9ajOFJZnvXyPI/p6eJxyUETkM9ukXB6+kagvpv7YAL5Xds2bds5cnLWTWvbBkEGP51egMoBTWMbS7A/b8NoPxUHkijJ+v3+ICa7WiBAz0OUQFvSO1vXaqNj+uLAgV/HOtWQ0dPJ52uD33mv6VmRibrgwtH+0HZtNdmeVBS9PJFl2fmmbtpnzp77zW88+5VvzIrtZwZ6cWsymbhP/utPPlvG5VZ2y8lGbS22pymmoJJHKC8EC/YatBAABPtut+eQ8u69915z6k2nBt/z7u85ubZw8GRRz1byOFtKo/j2A2vrt67t3btET0hjwuzzNM/IUQKyZ4dPjhnOlrw6ivjk7MkB1+QtAdrTezTk7Osul6fnad6ubWs43W5v4JQJi2/Y+/vdu2KfHTLu4XC4RLaqXwQG8McGR+78+yo49bbmQKMC2kDvY+i7ta1tsE1s4tRQXECPRxQM0H8cIxjPFcAuOtrHCT2jKmv6R1HAxsbmhXPjzc9OivGjcZxcmE7HTz7x2AMP/ct/9AsX3/Wud1VXIR4GtCBYsG+jhQAgWDCyn/n5n8k2n9k8tnfx6LEV1T++d//6nUcOH75hcWF1OU6iYUJpPXnrFfKAGfnDOQTvtHWUHbfI5OGvqV5etXVdkZXk22tDRt8VHDr5/oae4F290/RAg0zaajt3hJHi19YcFTR1BRfZ+Xd5P2ccvdtoNOrt3btv/8LCaPmlHqP1SMQuoN4iSLEMETCq4Gh/aqAQHBB4i8j/w/kTwoEgB3CBoeCA/ovBROT/GNto6fUjs0EHtVVXdTGbTi8++cwTzzz28KNbhXZfuVhf+I0Hn/raV5/afGr6iZ/8RO3LBsGCBfs2WQgAgn1X2o//nR8/uJ4duCGf6ZXT199y8MjxI6eyQX5iZWHv2sKgv582OfA8T7VFWVZI0imlhgMlR02emvJgctrwoZacX1WWZc35NH0RNqDJsVL+3RKMb+AtOZcuK0qdKwoKImUMO2ZQ9pUhtN+iDADo3+2CBjhrJx89pCLEcdrh/QcO7KOXidWrYFb54KBV2M9WceUC9YiGOwy4I4HqEHRojGbEKdU7EJLQDtLBpFmW0iMxYoXoassKYSFbFzbO3X/m3JOPbG+Oz9dt9fUHnnz4aw8/9o2v/vSf/emzKliwYL/vFgKAYN8Npj/04x/KF/ccWGgf2zp46qaTN/zAH/wDbz26fv2bh/1enxL2o1QH75H3uuxJSNCRpduWs/EadXT63pIzr+Aby6KsAfyTY2wL+qWpS4sKfwX4HsV+Cg+ABDjyqlpHPoVHTd6hxU/jlS09WXUEPSv8AGT/VVM15EvZv+JPIASiXDArq+rokUOHbrn59K0LC4sj9ftgHSER+0T/VQh0cHwNfqMghQAKAB0GpwrtieAkJEmSxUmcJgSf0DEgtDAdERFoA52Bs5NZ+dBjTz70n7/w5c/95teeeuzrVT1+djgZbtxzzz2VCnY103/8z/zx/nB1mJambI7MjkwCvyLYK7EQALzGDbnXj/3Yj6W9Q710PBy79XPrBX3oGxXsRe1Dn/hQVP98PTp6YP+Rd37f99x8bP2Gm9aX9vzBhdHwekL0E0+eg5NVyGwJWgeUr+gbofUtJefs0dGOp8j/oy5fzWazCqw9OOaKnDHAc9oUrrwGkN9UVU3O3ZLDBPRvqTpecdOeESdOSTQCBNpmp/5N/lMDnqfnVrQzjdNMDgTyvxsipwoEJ+TNdSdPnLjt1tteR2WABfX7bUxg5OgGuACHSOA40I5RdGBrHD/9reEqQRylJjIxVhkqF8RZlsV0aCmhBzH9zmsPHXJbFNUlY90DFza3fuPBx7/2+f/46V/4xlcffejpZJJMP/nJT4ZggK79+z/2/tGKWzn6gR983+laTfZH+XD6tfse+8KnP/kfvvTbv/3bhQp8imDfgoUA4LVpXKWFE/gTf/GHVt5wy/e8/s2ve9edl7YuFA8/8aVf+Wc//y+/ee/fv7fcdfXCh98bztlHP/rR+D1/9D1Z2qTH9y4fePfa0tL7RksLtywtriykcTIiZxv5DB1Qe4tMnxxrCQdPXt7C89LPdVFQVt/S7/S65KQqgeApOafNDGX05OvqoppVjh5GVkzF/wb+0VmG+PlB1AbokXkXHrB0VOORD1MBoME2EOqRXXecLINjYEGyI9+6+yPqJPNWN9x06tQdt7/udcPhtyEAuMI4YOJKh0QEQDzIprPpbAImBAIBXBNy/imhAiARxnkvHxAykETegB7QS9HJaGYbG5ubWxubD569dPbX7n/q/l8sx+VXLz54cUxBL5+e7ybegASBWv3wj3/owFu+93t/yKZr78nX41O679Zt/2S0OB78evzI/f/n49/84m9+7GM/uR04FcFeroUA4LVn7PyhFncu/ep1Nxw98ieO3vK2P7B87MYD5BNmT12wX/vGfb/79bW6+OVFN/lPvd76xoc//OFWBWP7y3/3b950eHTgXXfecscb962tn9yzuucoodKH6E+mY8OjRF+U1bStmGkPSjs7e87kqQJO/r1FmstBAG1pmdFPmH/N1QAk4RQ0gC1vHYEAFRf3Ge4vS6zZ5M7YpyMSIEzBwpHj72be6kdOk14bmABq61VRNU5We27ZQyWAfqRKvLO7HseuU6ih9R2vv/X2N73p7je9FgKAK412F0GVpfNb1GVRALWYTCbTFlUNqpzQ74oKA2k/73MTRZ9KMBQQ9HHCQDyUWIBf59knnnnsm5ubmxceP/f05x46++Svfu3BL3z17/yFv3NJfZfYj/zZD+1bXr3xe47eePQH1m46cLfqDY8QXgIoRal8Sa0kqVqfTn9n/OjWP/j4//fj/+KfffyfnVfBgr0MCwHAa9Q+9MN/4I173nbrXzh684H3pevrvWywpPb0l5Q1+1SuIrW3bb42PXPpdx58+PH7Zxcf//zZS9944K//2N8+d5WX+o4XZ/mL//tf3BtNo+tuOHb9G978PW9/59H1I28iH7x/3ltPzpPcakVZKLine truncated
+@media (prefers-color-scheme: dark) { :root { filter: none; } }
+</style></svg>

scripts/manage-db.ts

@@ -4,9 +4,9 @@ import { Database } from "bun:sqlite";
 import { drizzle } from "drizzle-orm/bun-sqlite";
 import { migrate } from "drizzle-orm/bun-sqlite/migrator";
 import { v4 as uuidv4 } from "uuid";
-import { users, configs, repositories, organizations, mirrorJobs, events } from "../src/lib/db/schema";
-import bcrypt from "bcryptjs";
-import { eq } from "drizzle-orm";
+import { users, configs, repositories, organizations, mirrorJobs, events, accounts, sessions } from "../src/lib/db/schema";
+import { and, eq } from "drizzle-orm";
+import { hashPassword } from "better-auth/crypto";
 
 // Command line arguments
 const args = process.argv.slice(2);
@@ -194,6 +194,92 @@ async function fixDatabase() {
   console.log("✅ Database location fixed");
 }
 
+/**
+ * Reset a single user's password (admin recovery flow)
+ */
+async function resetPassword() {
+  const emailArg = args.find((arg) => arg.startsWith("--email="));
+  const passwordArg = args.find((arg) => arg.startsWith("--new-password="));
+  const email = emailArg?.split("=")[1]?.trim().toLowerCase();
+  const newPassword = passwordArg?.split("=")[1];
+
+  if (!email || !newPassword) {
+    console.log("❌ Missing required arguments");
+    console.log("Usage:");
+    console.log("  bun run manage-db reset-password --email=user@example.com --new-password='new-secure-password'");
+    process.exit(1);
+  }
+
+  if (newPassword.length < 8) {
+    console.log("❌ Password must be at least 8 characters");
+    process.exit(1);
+  }
+
+  if (!fs.existsSync(dbPath)) {
+    console.log("❌ Database does not exist");
+    process.exit(1);
+  }
+
+  const sqlite = new Database(dbPath);
+  const db = drizzle({ client: sqlite });
+
+  try {
+    const user = await db.query.users.findFirst({
+      where: eq(users.email, email),
+    });
+
+    if (!user) {
+      console.log(`❌ No user found for email: ${email}`);
+      sqlite.close();
+      process.exit(1);
+    }
+
+    const hashedPassword = await hashPassword(newPassword);
+    const now = new Date();
+
+    const credentialAccount = await db.query.accounts.findFirst({
+      where: and(
+        eq(accounts.userId, user.id),
+        eq(accounts.providerId, "credential"),
+      ),
+    });
+
+    if (credentialAccount) {
+      await db
+        .update(accounts)
+        .set({
+          password: hashedPassword,
+          updatedAt: now,
+        })
+        .where(eq(accounts.id, credentialAccount.id));
+    } else {
+      await db.insert(accounts).values({
+        id: uuidv4(),
+        accountId: user.id,
+        userId: user.id,
+        providerId: "credential",
+        password: hashedPassword,
+        createdAt: now,
+        updatedAt: now,
+      });
+    }
+
+    const deletedSessions = await db
+      .delete(sessions)
+      .where(eq(sessions.userId, user.id))
+      .returning({ id: sessions.id });
+
+    console.log(`✅ Password reset for ${email}`);
+    console.log(`🔒 Cleared ${deletedSessions.length} active session(s)`);
+
+    sqlite.close();
+  } catch (error) {
+    console.error("❌ Error resetting password:", error);
+    sqlite.close();
+    process.exit(1);
+  }
+}
+
 /**
  * Auto mode - check and initialize if needed
  */
@@ -224,6 +310,9 @@ switch (command) {
   case "cleanup":
     await cleanupDatabase();
     break;
+  case "reset-password":
+    await resetPassword();
+    break;
   case "auto":
     await autoMode();
     break;
@@ -233,7 +322,8 @@ switch (command) {
     console.log("  check        - Check database status");
     console.log("  fix          - Fix database location issues");
     console.log("  reset-users  - Remove all users and related data");
+    console.log("  reset-password - Reset one user's password and clear sessions");
     console.log("  cleanup      - Remove all database files");
     console.log("  auto         - Auto initialize if needed");
     process.exit(1);
-}
+}

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/setup-authentik-test.sh

@@ -114,10 +114,10 @@ EOF
         echo "======================================"
         echo "1. Access Authentik at http://localhost:9000"
         echo "2. Login with akadmin / admin-password"
-        echo "3. Create OAuth2 Provider for Gitea Mirror:"
+        echo "3. Create an Authentik OIDC Provider for Gitea Mirror:"
         echo "   - Name: gitea-mirror"
-        echo "   - Redirect URIs:"
-        echo "     http://localhost:4321/api/auth/callback/sso-provider"
+        echo "   - Redirect URI:"
+        echo "     http://localhost:4321/api/auth/sso/callback/authentik"
         echo "   - Scopes: openid, profile, email"
         echo ""
         echo "4. Create Application:"
@@ -131,10 +131,14 @@ EOF
         echo "6. Configure SSO in Gitea Mirror:"
         echo "   - Go to Settings → Authentication & SSO"
         echo "   - Add provider with:"
+        echo "     - Provider ID: authentik"
         echo "     - Issuer URL: http://localhost:9000/application/o/gitea-mirror/"
+        echo "     - Click Discover to pull Authentik endpoints"
         echo "     - Client ID: (from Authentik provider)"
         echo "     - Client Secret: (from Authentik provider)"
         echo ""
+        echo "If you previously registered this provider on a version earlier than v3.8.10, delete it and re-add it after upgrading to avoid missing endpoint data."
+        echo ""
         ;;
         
     stop)
@@ -177,4 +181,4 @@ EOF
         echo "  status - Show service status"
         exit 1
         ;;
-esac
+esac

scripts/startup-recovery.ts

@@ -13,6 +13,7 @@
  */
 
 import { initializeRecovery, hasJobsNeedingRecovery, getRecoveryStatus } from "../src/lib/recovery";
+import { resetStuckMirrorStatuses } from "../src/lib/stuck-status-recovery";
 
 // Parse command line arguments
 const args = process.argv.slice(2);
@@ -41,10 +42,29 @@ async function runStartupRecovery() {
       }, timeout);
     });
 
+    // Reset repositories/organizations stuck in an in-flight status
+    // ("mirroring"/"syncing") from a previous run (issue #339). This must
+    // happen BEFORE the needsRecovery early-exit below: scheduler-driven
+    // syncs create no resilient job records, so a crash mid-scheduled-sync
+    // leaves stuck repo rows but NO interrupted jobs — the early exit would
+    // skip them forever. The app is not running while this script executes,
+    // so every in-flight row is an orphan by definition (this script's own
+    // process start is the cutoff). Never throws.
+    console.log('Checking for repositories stuck in an in-flight status...');
+    const stuckReset = await resetStuckMirrorStatuses();
+    if (stuckReset.repositories > 0 || stuckReset.organizations > 0) {
+      console.log(
+        `✅ Reset ${stuckReset.repositories} stuck repositor${stuckReset.repositories === 1 ? 'y' : 'ies'} ` +
+        `and ${stuckReset.organizations} stuck organization(s) to "failed" for retry.`
+      );
+    } else {
+      console.log('✅ No stuck repository/organization statuses found.');
+    }
+
     // Check if recovery is needed first
     console.log('Checking if recovery is needed...');
     const needsRecovery = await hasJobsNeedingRecovery();
-    
+
     if (!needsRecovery) {
       console.log('✅ No jobs need recovery. Startup can proceed.');
       process.exit(0);

scripts/validate-migrations.ts

@@ -0,0 +1,476 @@
+#!/usr/bin/env bun
+
+import { Database } from "bun:sqlite";
+import { readFileSync } from "fs";
+import path from "path";
+import {
+  repairDuplicateSsoColumns,
+  restoreSsoDataAfter0013,
+} from "../src/lib/db/migration-repairs";
+
+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'");
+}
+
+function seedPre0012Database(db: any) {
+  // The harness has already run migrations 0000-0011, so the legacy
+  // oidc-provider tables exist. Seed a registered client (with the legacy
+  // comma-separated redirect_urls format) plus the related token/consent rows
+  // to exercise the create/transform/drop paths in 0012.
+  db.run("INSERT INTO users (id, email, username, name) VALUES ('u1', 'u1@example.com', 'user1', 'User One')");
+  db.run("INSERT INTO oauth_applications (id, client_id, client_secret, name, redirect_urls, type, disabled, user_id) VALUES ('app1', 'client-1', 'secret-1', 'Example App', 'https://example.com/callback,https://example.com/cb2', 'web', false, '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', 'tok', 'rtok', 7000, 8000, 'client-1', 'u1', '[\"repo\"]')");
+  db.run("INSERT INTO oauth_consent (id, user_id, client_id, scopes, consent_given) VALUES ('cons1', 'u1', 'client-1', '[\"repo\"]', true)");
+}
+
+function verify0012Migration(db: any) {
+  // Old provider tables are dropped.
+  for (const table of ["oauth_applications", "oauth_consent"]) {
+    const row = db
+      .query("SELECT name FROM sqlite_master WHERE type='table' AND name = ?")
+      .get(table) as { name: string } | null;
+    assert(!row, `Expected ${table} table to be dropped after migration`);
+  }
+
+  // New provider tables exist.
+  for (const table of ["oauth_clients", "oauth_access_tokens", "oauth_refresh_tokens", "oauth_consents", "jwks"]) {
+    const row = db
+      .query("SELECT name FROM sqlite_master WHERE type='table' AND name = ?")
+      .get(table) as { name: string } | null;
+    assert(row, `Expected ${table} table to exist after migration`);
+  }
+
+  // The registered client is preserved and its redirect URIs converted from
+  // the legacy comma-separated string into a JSON string[].
+  const client = db
+    .query("SELECT client_id, client_secret, name, redirect_uris, type, user_id FROM oauth_clients WHERE id = 'app1'")
+    .get() as { client_id: string; client_secret: string; name: string; redirect_uris: string; type: string; user_id: string } | null;
+  assert(client, "Expected migrated oauth_clients row for app1");
+  assert(client.client_id === "client-1", "Expected client_id to be preserved");
+  assert(client.name === "Example App", "Expected client name to be preserved");
+  assert(client.user_id === "u1", "Expected owner user_id to be preserved");
+
+  const uris = JSON.parse(client.redirect_uris);
+  assert(
+    Array.isArray(uris) && uris.length === 2 && uris[0] === "https://example.com/callback" && uris[1] === "https://example.com/cb2",
+    `Expected redirect_uris to be a JSON array of the two callbacks, got ${client.redirect_uris}`,
+  );
+
+  // The reshaped tables accept the new column layout.
+  db.run("INSERT INTO oauth_clients (id, client_id, redirect_uris) VALUES ('app2', 'client-2', '[\"https://example.com/cb\"]')");
+  db.run("INSERT INTO oauth_refresh_tokens (id, token, client_id, user_id, scopes) VALUES ('rt1', 'refresh-1', 'client-2', 'u1', '[\"openid\"]')");
+  db.run("INSERT INTO oauth_access_tokens (id, token, client_id, user_id, scopes) VALUES ('at1', 'access-1', 'client-2', 'u1', '[\"openid\"]')");
+  db.run("INSERT INTO oauth_consents (id, client_id, user_id, scopes) VALUES ('co1', 'client-2', 'u1', '[\"openid\"]')");
+  db.run("INSERT INTO jwks (id, public_key, private_key) VALUES ('jwk1', 'public', 'private')");
+}
+
+function seedPre0013Database(db: any) {
+  // Migrations 0000-0012 have run, so sso_providers lacks samlConfig /
+  // domainVerified and the organizations table still carries the inherited
+  // DEFAULT '' on normalized_name from 0007. Seed both so the table-rebuild
+  // and the column-adds can be verified end-to-end.
+  db.run("INSERT INTO users (id, email, username, name) VALUES ('u-sso', 'sso@example.com', 'sso', 'SSO User')");
+  db.run("INSERT INTO configs (id, user_id, name, is_active, github_config, gitea_config, schedule_config, cleanup_config) VALUES ('cfg-pre13', 'u-sso', 'Default', 1, '{}', '{}', '{}', '{}')");
+  db.run("INSERT INTO sso_providers (id, issuer, domain, oidc_config, user_id, provider_id) VALUES ('sso-pre13', 'https://idp.example.com', 'example.com', '{\"clientId\":\"x\"}', 'u-sso', 'idp-pre13')");
+  db.run("INSERT INTO organizations (id, user_id, config_id, name, avatar_url, normalized_name) VALUES ('org-pre13', 'u-sso', 'cfg-pre13', 'Example', 'https://example.com/a.png', 'example')");
+}
+
+function verify0013Migration(db: any) {
+  // New columns on sso_providers.
+  const ssoCols = db
+    .query("PRAGMA table_info(sso_providers)")
+    .all() as Array<{ name: string; notnull: number; dflt_value: string | null }>;
+  const saml = ssoCols.find((c) => c.name === "saml_config");
+  const domainVerified = ssoCols.find((c) => c.name === "domain_verified");
+  assert(saml, "Expected sso_providers.saml_config column to exist");
+  assert(saml.notnull === 0, "Expected saml_config to be nullable");
+  assert(domainVerified, "Expected sso_providers.domain_verified column to exist");
+  assert(domainVerified.notnull === 1, "Expected domain_verified to be NOT NULL");
+  assert(
+    domainVerified.dflt_value === "true",
+    `Expected domain_verified DEFAULT true, got ${domainVerified.dflt_value}`,
+  );
+
+  // Pre-existing SSO row picked up the default (1 = true) on domain_verified.
+  const ssoRow = db
+    .query("SELECT provider_id, saml_config, domain_verified FROM sso_providers WHERE id = 'sso-pre13'")
+    .get() as { provider_id: string; saml_config: string | null; domain_verified: number } | null;
+  assert(ssoRow, "Expected pre-existing OIDC provider row to survive migration");
+  assert(ssoRow.saml_config === null, `Expected saml_config NULL, got ${ssoRow.saml_config}`);
+  assert(ssoRow.domain_verified === 1, `Expected domain_verified=1, got ${ssoRow.domain_verified}`);
+
+  // Organizations rebuild preserved the seeded row and dropped the inherited
+  // DEFAULT '' on normalized_name (drizzle reconciles to schema.ts).
+  const orgRow = db
+    .query("SELECT id, normalized_name FROM organizations WHERE id = 'org-pre13'")
+    .get() as { id: string; normalized_name: string } | null;
+  assert(orgRow, "Expected pre-existing organization row to survive table rebuild");
+  assert(orgRow.normalized_name === "example", `Expected organization normalized_name preserved, got ${orgRow.normalized_name}`);
+  const orgCols = db
+    .query("PRAGMA table_info(organizations)")
+    .all() as Array<{ name: string; dflt_value: string | null }>;
+  const normName = orgCols.find((c) => c.name === "normalized_name");
+  assert(normName, "Expected organizations.normalized_name column to exist");
+  assert(normName.dflt_value === null, `Expected normalized_name to have no default, got ${normName.dflt_value}`);
+}
+
+const MIGRATION_0012_TIMESTAMP = 1774062000000;
+const MIGRATION_0013_TIMESTAMP = 1780377747526;
+
+/**
+ * Reproduce the issue #312 crash state — sso_providers already carries
+ * saml_config / domain_verified before migration 0013 runs (stranded on an
+ * intermediate build), with __drizzle_migrations recorded only through 0012 —
+ * and verify repairDuplicateSsoColumns()/restoreSsoDataAfter0013() let the
+ * canonical 0013 run while preserving real SAML provider data.
+ */
+function validateBroken0013Repair() {
+  const migration0013 = migrations.find((m) => m.entry.tag === "0013_slim_galactus");
+  if (!migration0013) return; // 0013 not present (shouldn't happen) — nothing to test.
+
+  const db = new Database(":memory:");
+  try {
+    runMigrations(db, migrations.slice(0, 13)); // 0000-0012
+
+    // A real upgraded instance has a __drizzle_migrations table recorded
+    // through 0012 but not 0013.
+    db.run(
+      "CREATE TABLE IF NOT EXISTS `__drizzle_migrations` (id INTEGER PRIMARY KEY AUTOINCREMENT, hash text NOT NULL, created_at numeric)",
+    );
+    db.run("INSERT INTO `__drizzle_migrations` (hash, created_at) VALUES ('through-0012', ?)", [
+      MIGRATION_0012_TIMESTAMP,
+    ]);
+
+    // Stranded columns from the intermediate build.
+    db.run("ALTER TABLE sso_providers ADD saml_config text");
+    db.run("ALTER TABLE sso_providers ADD domain_verified integer DEFAULT true NOT NULL");
+
+    db.run("INSERT INTO users (id, email, username, name) VALUES ('u1', 'u1@example.com', 'u1', 'User One')");
+    const samlJson = '{"entryPoint":"https://idp.example.com/sso","cert":"ABC123"}';
+    db.run(
+      "INSERT INTO sso_providers (id, issuer, domain, oidc_config, user_id, provider_id, saml_config, domain_verified) VALUES ('oidc1', 'https://idp', 'a.com', '{}', 'u1', 'p-oidc', NULL, 1)",
+    );
+    db.run(
+      "INSERT INTO sso_providers (id, issuer, domain, oidc_config, user_id, provider_id, saml_config, domain_verified) VALUES ('saml1', 'https://idp', 'b.com', '{}', 'u1', 'p-saml', ?, 1)",
+      [samlJson],
+    );
+    db.run(
+      "INSERT INTO sso_providers (id, issuer, domain, oidc_config, user_id, provider_id, saml_config, domain_verified) VALUES ('unv1', 'https://idp', 'c.com', '{}', 'u1', 'p-unv', NULL, 0)",
+    );
+
+    const preserved = repairDuplicateSsoColumns(db);
+
+    const colsAfterRepair = (db.query("PRAGMA table_info(sso_providers)").all() as TableInfoRow[]).map(
+      (c) => c.name,
+    );
+    assert(!colsAfterRepair.includes("saml_config"), "Expected repair to drop stranded saml_config column");
+    assert(
+      !colsAfterRepair.includes("domain_verified"),
+      "Expected repair to drop stranded domain_verified column",
+    );
+    const preservedIds = preserved.map((r) => r.id).sort();
+    assert(
+      preservedIds.length === 2 && preservedIds[0] === "saml1" && preservedIds[1] === "unv1",
+      `Expected SAML + unverified rows to be preserved, got ${JSON.stringify(preservedIds)}`,
+    );
+
+    // The canonical 0013 must now run without a duplicate-column error.
+    runMigration(db, migration0013);
+    restoreSsoDataAfter0013(db, preserved);
+
+    const rows = db
+      .query("SELECT id, saml_config, domain_verified FROM sso_providers ORDER BY id")
+      .all() as Array<{ id: string; saml_config: string | null; domain_verified: number }>;
+    const byId = Object.fromEntries(rows.map((r) => [r.id, r]));
+
+    assert(byId.oidc1.saml_config === null, "Expected OIDC provider saml_config to remain NULL");
+    assert(byId.oidc1.domain_verified === 1, "Expected OIDC provider domain_verified default 1");
+    assert(byId.saml1.saml_config === samlJson, "Expected SAML provider config to be preserved");
+    assert(byId.saml1.domain_verified === 1, "Expected SAML provider domain_verified preserved as 1");
+    assert(byId.unv1.saml_config === null, "Expected unverified provider saml_config NULL");
+    assert(byId.unv1.domain_verified === 0, "Expected explicit domain_verified=0 to be preserved");
+
+    // Idempotency: 0013 is now applied, so a re-run of the repair is a no-op.
+    db.run("INSERT INTO `__drizzle_migrations` (hash, created_at) VALUES ('through-0013', ?)", [
+      MIGRATION_0013_TIMESTAMP,
+    ]);
+    const secondPass = repairDuplicateSsoColumns(db);
+    assert(secondPass.length === 0, "Expected repair to no-op once migration 0013 is recorded");
+    const colsAfterSecondPass = (
+      db.query("PRAGMA table_info(sso_providers)").all() as TableInfoRow[]
+    ).map((c) => c.name);
+    assert(
+      colsAfterSecondPass.includes("saml_config") && colsAfterSecondPass.includes("domain_verified"),
+      "Expected columns to remain intact on the no-op second pass",
+    );
+  } finally {
+    db.close();
+  }
+}
+
+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,
+  },
+  "0012_oauth_provider_migration": {
+    seed: seedPre0012Database,
+    verify: verify0012Migration,
+  },
+  "0013_slim_galactus": {
+    seed: seedPre0013Database,
+    verify: verify0013Migration,
+  },
+};
+
+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();
+  }
+
+  // Exercise the runtime repair for the issue #312 duplicate-column crash.
+  validateBroken0013Repair();
+
+  console.log(
+    `Validated ${migrations.length} migrations from scratch and upgrade path for ${latestMigration.entry.tag}, plus the #312 SSO-column repair.`,
+  );
+}
+
+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="https://gitea-mirror.raylabs.io/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/ActivityList.tsx

@@ -6,6 +6,7 @@ import { Button } from '../ui/button';
 import { RefreshCw, Check, X, Loader2, Import } from 'lucide-react';
 import { Card } from '../ui/card';
 import { formatDate, getStatusColor } from '@/lib/utils';
+import { useTimeFormat } from '@/hooks/useTimeFormat';
 import { Skeleton } from '../ui/skeleton';
 import type { FilterParams } from '@/types/filter';
 import {
@@ -32,6 +33,9 @@ export default function ActivityList({
   filter,
   setFilter,
 }: ActivityListProps) {
+  // Re-render timestamps when the user changes the 12h/24h preference.
+  useTimeFormat();
+
   const [expandedItems, setExpandedItems] = useState<Set<string>>(
     () => new Set(),
   );

src/components/activity/ActivityLog.tsx

@@ -1,6 +1,6 @@
 import { useCallback, useEffect, useState, useRef } from 'react';
 import { Button } from '@/components/ui/button';
-import { ChevronDown, Download, RefreshCw, Search, Trash2, Filter } from 'lucide-react';
+import { ChevronDown, Download, RefreshCw, Search, Trash2, Filter, StopCircle } from 'lucide-react';
 import {
   DropdownMenu,
   DropdownMenuContent,
@@ -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,
@@ -84,6 +85,8 @@ export function ActivityLog() {
   const [activities, setActivities] = useState<MirrorJobWithKey[]>([]);
   const [isInitialLoading, setIsInitialLoading] = useState(false);
   const [showCleanupDialog, setShowCleanupDialog] = useState(false);
+  const [showCancelPendingDialog, setShowCancelPendingDialog] = useState(false);
+  const [isCancelPendingLoading, setIsCancelPendingLoading] = useState(false);
 
   // Ref to track if component is mounted to prevent state updates after unmount
   const isMountedRef = useRef(true);
@@ -321,7 +324,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 }),
@@ -353,6 +356,40 @@ export function ActivityLog() {
     setShowCleanupDialog(false);
   };
 
+  const confirmCancelPending = async () => {
+    if (!user?.id) return;
+
+    try {
+      setIsCancelPendingLoading(true);
+      setShowCancelPendingDialog(false);
+
+      const response = await fetch(withBase('/api/job/cancel-pending'), {
+        method: 'POST',
+        headers: { 'Content-Type': 'application/json' },
+      });
+
+      if (!response.ok) {
+        const errorData = await response.json().catch(() => ({ error: 'Unknown error occurred' }));
+        throw new Error(errorData.error || `HTTP ${response.status}: ${response.statusText}`);
+      }
+
+      const res = await response.json();
+
+      if (res.success) {
+        toast.success(res.message);
+        // Refresh to show the new activity log entry
+        await fetchActivities(false);
+      } else {
+        showErrorToast(res.error || 'Failed to cancel pending mirrors.', toast);
+      }
+    } catch (error) {
+      console.error('Error cancelling pending mirrors:', error);
+      showErrorToast(error, toast);
+    } finally {
+      setIsCancelPendingLoading(false);
+    }
+  };
+
   // Check if any filters are active
   const hasActiveFilters = !!(filter.status || filter.type || filter.name);
   const activeFilterCount = [filter.status, filter.type, filter.name].filter(Boolean).length;
@@ -551,11 +588,22 @@ export function ActivityLog() {
             <RefreshCw className="h-4 w-4" />
           </Button>
           
+          <Button
+            variant="outline"
+            size="icon"
+            onClick={() => setShowCancelPendingDialog(true)}
+            title="Stop pending mirrors"
+            className="text-amber-600 hover:text-amber-600 h-10 w-10 shrink-0"
+            disabled={isCancelPendingLoading}
+          >
+            <StopCircle className="h-4 w-4" />
+          </Button>
+
           <Button
             variant="outline"
             size="icon"
             onClick={handleCleanupClick}
-            title="Delete all activities"
+            title="Clear activity history"
             className="text-destructive hover:text-destructive h-10 w-10 shrink-0"
           >
             <Trash2 className="h-4 w-4" />
@@ -682,12 +730,24 @@ export function ActivityLog() {
             <RefreshCw className="h-4 w-4" />
           </Button>
 
-          {/* cleanup all activities */}
+          {/* stop pending mirrors */}
+          <Button
+            variant="outline"
+            size="icon"
+            onClick={() => setShowCancelPendingDialog(true)}
+            title="Stop pending mirrors"
+            className="text-amber-600 hover:text-amber-600 h-10 w-10"
+            disabled={isCancelPendingLoading}
+          >
+            <StopCircle className="h-4 w-4" />
+          </Button>
+
+          {/* clear activity history */}
           <Button
             variant="outline"
             size="icon"
             onClick={handleCleanupClick}
-            title="Delete all activities"
+            title="Clear activity history"
             className="text-destructive hover:text-destructive h-10 w-10"
           >
             <Trash2 className="h-4 w-4" />
@@ -708,9 +768,12 @@ export function ActivityLog() {
       <Dialog open={showCleanupDialog} onOpenChange={setShowCleanupDialog}>
         <DialogContent>
           <DialogHeader>
-            <DialogTitle>Delete All Activities</DialogTitle>
+            <DialogTitle>Clear Activity History</DialogTitle>
             <DialogDescription>
-              Are you sure you want to delete ALL activities? This action cannot be undone and will remove all mirror jobs and events from the database.
+              This clears the activity <strong>history log</strong> (mirror job records and events) — it does not stop
+              any pending or in-progress mirrors. Repositories keep their current status and the scheduler
+              will continue to pick up pending work. To stop pending mirrors, use the
+              &ldquo;Stop Pending Mirrors&rdquo; button instead.
             </DialogDescription>
           </DialogHeader>
           <DialogFooter>
@@ -722,7 +785,35 @@ export function ActivityLog() {
               onClick={confirmCleanup}
               disabled={isInitialLoading}
             >
-              {isInitialLoading ? 'Deleting...' : 'Delete All Activities'}
+              {isInitialLoading ? 'Clearing...' : 'Clear History'}
+            </Button>
+          </DialogFooter>
+        </DialogContent>
+      </Dialog>
+
+      {/* cancel pending mirrors confirmation dialog */}
+      <Dialog open={showCancelPendingDialog} onOpenChange={setShowCancelPendingDialog}>
+        <DialogContent>
+          <DialogHeader>
+            <DialogTitle>Stop Pending Mirrors</DialogTitle>
+            <DialogDescription>
+              This sets all repositories with status <strong>Imported</strong> or <strong>Failed</strong> to{' '}
+              <strong>Ignored</strong>, preventing the scheduler from mirroring them automatically.
+              Repositories that are currently mirroring are not affected.{' '}
+              You can re-enable individual repositories from the Repositories page.
+            </DialogDescription>
+          </DialogHeader>
+          <DialogFooter>
+            <Button variant="outline" onClick={() => setShowCancelPendingDialog(false)}>
+              Cancel
+            </Button>
+            <Button
+              variant="default"
+              className="bg-amber-600 hover:bg-amber-700"
+              onClick={confirmCancelPending}
+              disabled={isCancelPendingLoading}
+            >
+              {isCancelPendingLoading ? 'Stopping...' : 'Stop Pending Mirrors'}
             </Button>
           </DialogFooter>
         </DialogContent>

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"
             />