From 985c7e061cfec771bf7be6ac689ea51535dd8639 Mon Sep 17 00:00:00 2001 From: Arunavo Ray Date: Fri, 24 Oct 2025 07:43:13 +0530 Subject: [PATCH] updated README --- .claude/agents/qa-testing-specialist.md | 76 ------- .claude/agents/senior-code-architect.md | 68 ------ .claude/agents/strategic-task-planner.md | 61 ------ .claude/commands/new_release.md | 5 - .claude/commands/release_notes.md | 3 - .claude/settings.local.json | 8 - AGENTS.md | 46 ---- CLAUDE.md | 256 ----------------------- README.md | 4 - UPGRADE.md | 74 ------- 10 files changed, 601 deletions(-) delete mode 100644 .claude/agents/qa-testing-specialist.md delete mode 100644 .claude/agents/senior-code-architect.md delete mode 100644 .claude/agents/strategic-task-planner.md delete mode 100644 .claude/commands/new_release.md delete mode 100644 .claude/commands/release_notes.md delete mode 100644 .claude/settings.local.json delete mode 100644 AGENTS.md delete mode 100644 CLAUDE.md delete mode 100644 UPGRADE.md diff --git a/.claude/agents/qa-testing-specialist.md b/.claude/agents/qa-testing-specialist.md deleted file mode 100644 index 8d69259..0000000 --- a/.claude/agents/qa-testing-specialist.md +++ /dev/null @@ -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. \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\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\n\n\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\nThe user is asking about test coverage improvement, which is a core QA task, so use the qa-testing-specialist agent.\n\n -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. diff --git a/.claude/agents/senior-code-architect.md b/.claude/agents/senior-code-architect.md deleted file mode 100644 index 6887da4..0000000 --- a/.claude/agents/senior-code-architect.md +++ /dev/null @@ -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\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\nSince this requires creating new code with the project's tech stack, the senior-code-architect agent is appropriate.\n\n\n\n\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\nThis requires deep understanding of Better Auth and clean code principles, making the senior-code-architect agent the right choice.\n\n\n\n\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\nThe senior-code-architect can review recently written code for best practices and design patterns.\n\n -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. diff --git a/.claude/agents/strategic-task-planner.md b/.claude/agents/strategic-task-planner.md deleted file mode 100644 index a504334..0000000 --- a/.claude/agents/strategic-task-planner.md +++ /dev/null @@ -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. 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." 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. 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." Since this is a complex migration requiring careful planning, use the strategic-task-planner agent to create a structured approach. -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. diff --git a/.claude/commands/new_release.md b/.claude/commands/new_release.md deleted file mode 100644 index 654dfb9..0000000 --- a/.claude/commands/new_release.md +++ /dev/null @@ -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. diff --git a/.claude/commands/release_notes.md b/.claude/commands/release_notes.md deleted file mode 100644 index 777b30e..0000000 --- a/.claude/commands/release_notes.md +++ /dev/null @@ -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. diff --git a/.claude/settings.local.json b/.claude/settings.local.json deleted file mode 100644 index 5ee97bd..0000000 --- a/.claude/settings.local.json +++ /dev/null @@ -1,8 +0,0 @@ -{ - "permissions": { - "allow": [ - "Bash(docker build:*)" - ], - "deny": [] - } -} \ No newline at end of file diff --git a/AGENTS.md b/AGENTS.md deleted file mode 100644 index 6c051e7..0000000 --- a/AGENTS.md +++ /dev/null @@ -1,46 +0,0 @@ -# Repository Guidelines - -## Project Structure & Module Organization -- `src/` – app code - - `components/` (React, PascalCase files), `pages/` (Astro/API routes), `lib/` (domain + utilities, kebab-case), `hooks/`, `layouts/`, `styles/`, `tests/`, `types/`, `data/`, `content/`. -- `scripts/` – operational TS scripts (DB init, recovery): e.g., `scripts/manage-db.ts`. -- `drizzle/` – SQL migrations; `data/` – runtime SQLite (`gitea-mirror.db`). -- `public/` – static assets; `dist/` – build output. -- Key config: `astro.config.mjs`, `tsconfig.json` (alias `@/* → src/*`), `bunfig.toml` (test preload), `.env(.example)`. - -## Build, Test, and Development Commands -- Prereq: Bun `>= 1.2.9` (see `package.json`). -- Setup: `bun run setup` – install deps and init DB. -- Dev: `bun run dev` – start Astro dev server. -- Build: `bun run build` – produce `dist/`. -- Preview/Start: `bun run preview` (static preview) or `bun run start` (SSR entry). -- Database: `bun run db:generate|migrate|push|studio` and `bun run manage-db init|check|fix|reset-users`. -- Tests: `bun test` | `bun run test:watch` | `bun run test:coverage`. -- Docker: see `docker-compose.yml` and variants in repo root. - -## Coding Style & Naming Conventions -- Language: TypeScript, Astro, React. -- Indentation: 2 spaces; keep existing semicolon/quote style in touched files. -- Components: PascalCase `.tsx` in `src/components/` (e.g., `MainLayout.tsx`). -- Modules/utils: kebab-case in `src/lib/` (e.g., `gitea-enhanced.ts`). -- Imports: prefer alias `@/…` (configured in `tsconfig.json`). -- Do not introduce new lint/format configs; follow current patterns. - -## Testing Guidelines -- Runner: Bun test (`bun:test`) with preload `src/tests/setup.bun.ts` (see `bunfig.toml`). -- Location/Names: `**/*.test.ts(x)` under `src/**` (examples in `src/lib/**`). -- Scope: add unit tests for new logic and API route tests for handlers. -- Aim for meaningful coverage on DB, auth, and mirroring paths. - -## Commit & Pull Request Guidelines -- Commits: short, imperative, scoped when helpful (e.g., `lib: fix token parsing`, `ui: align buttons`). -- PRs must include: - - Summary, rationale, and testing steps/commands. - - Linked issues (e.g., `Closes #123`). - - Screenshots/gifs for UI changes. - - Notes on DB/migration or .env impacts; update `docs/`/CHANGELOG if applicable. - -## Security & Configuration Tips -- Never commit secrets. Copy `.env.example` → `.env` and fill values; prefer `bun run startup-env-config` to validate. -- SQLite files live in `data/`; avoid committing generated DBs. -- Certificates (if used) reside in `certs/`; manage locally or via Docker secrets. diff --git a/CLAUDE.md b/CLAUDE.md deleted file mode 100644 index 040a816..0000000 --- a/CLAUDE.md +++ /dev/null @@ -1,256 +0,0 @@ -# CLAUDE.md - -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. - -## Essential Commands - -### Development -```bash -bun run dev # Start development server (port 3000) -bun run build # Build for production -bun run preview # Preview production build -``` - -### Testing -```bash -bun test # Run all tests -bun test:watch # Run tests in watch mode -bun test:coverage # Run tests with coverage -``` - -### Database Management -```bash -bun run init-db # Initialize database -bun run reset-users # Reset user accounts (development) -bun run cleanup-db # Remove database files -``` - -### Production -```bash -bun run start # Start production server -``` - -## Architecture & Key Concepts - -### 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 - -### 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 - -### 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'; - -export async function POST({ request }: APIContext) { - try { - // Implementation - } catch (error) { - return createSecureErrorResponse(error); - } -} -``` - -2. **Database Queries**: Located in `/src/lib/db/queries/` organized by domain (users, repositories, etc.) - -3. **Real-time Updates**: Server-Sent Events (SSE) endpoint at `/api/events` for live dashboard updates - -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 - -5. **Mirror Process**: - - Discovers repos from GitHub (user/org) - - Creates/updates mirror in Gitea - - Tracks status in database - - Supports scheduled automatic mirroring - -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 - -### 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 - -### 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. - -### 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 - -### 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 - -### Common Tasks - -**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 - -**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`) - -**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/` - -## Configuration Options - -### GitHub Configuration (UI Fields) - -#### 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 - -### 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 - -### 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) - -### Database Cleanup Configuration (`cleanupConfig`) -- **enabled**: Enable automatic cleanup (default: false) -- **retentionDays**: Days to keep events (stored as seconds internally) - -### 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 - -### Advanced Options (UI Fields) -- **skipForks**: Skip forked repositories (default: false) -- **starredCodeOnly**: Skip issues for starred repositories (default: false) - enables "Lightweight mode" for starred repos - -### 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 - -### Scheduling and Synchronization (Issue #72 Fixes) - -#### 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) - -#### Environment Variables for Auto-Import -- **AUTO_IMPORT_REPOS**: Set to `false` to disable automatic repository discovery (default: enabled) - -#### 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 - -### Authentication Configuration - -#### 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 \ No newline at end of file diff --git a/README.md b/README.md index 81ac1ce..b280d9f 100644 --- a/README.md +++ b/README.md @@ -10,10 +10,6 @@

-> [!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 diff --git a/UPGRADE.md b/UPGRADE.md deleted file mode 100644 index a08df45..0000000 --- a/UPGRADE.md +++ /dev/null @@ -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 \ No newline at end of file