From 12ee06583316b6fdd9e52238278b6ddabc84fd4e Mon Sep 17 00:00:00 2001 From: Arunavo Ray Date: Wed, 27 Aug 2025 21:43:36 +0530 Subject: [PATCH] Docs updated | added some options --- CHANGELOG.md | 48 +++++++++++++++++++++ CLAUDE.md | 16 +++++++ README.md | 30 ++++++++++++- docs/ENVIRONMENT_VARIABLES.md | 3 +- src/components/config/ConfigTabs.tsx | 13 ++++-- src/components/config/MirrorOptionsForm.tsx | 26 +++++++++++ src/lib/gitea.ts | 2 + src/lib/utils/config-mapper.ts | 3 +- src/types/config.ts | 1 + 9 files changed, 135 insertions(+), 7 deletions(-) diff --git a/CHANGELOG.md b/CHANGELOG.md index d5e19cd..21181e0 100644 --- a/CHANGELOG.md +++ b/CHANGELOG.md @@ -7,6 +7,54 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0 ## [Unreleased] +### Added +- Git LFS (Large File Storage) support for mirroring (#74) + - New UI checkbox "Mirror LFS" in Mirror Options + - Automatic LFS object transfer when enabled + - Documentation for Gitea server LFS requirements +- Repository "ignored" status to skip specific repos from mirroring (#75) + - Repositories can be marked as ignored to exclude from all operations + - Scheduler automatically skips ignored repositories +- Enhanced error handling for all metadata mirroring operations + - Individual try-catch blocks for issues, PRs, labels, milestones + - Operations continue even if individual components fail +- Support for BETTER_AUTH_TRUSTED_ORIGINS environment variable +- Comprehensive fix report documentation + +### Fixed +- Fixed metadata mirroring authentication errors (#68) + - Changed field checking from `username` to `defaultOwner` in metadata functions + - Added proper field validation for all metadata operations +- Fixed automatic mirroring scheduler issues (#72) + - Improved interval parsing and error handling +- Fixed OIDC authentication 500 errors with Authentik (#73) + - Added URL validation in Better Auth configuration + - Prevented undefined URL errors in auth callback +- Fixed SSL certificate handling in Docker (#48) + - NODE_EXTRA_CA_CERTS no longer gets overridden + - Proper preservation of custom CA certificates +- Fixed reverse proxy base domain issues (#63) + - Better handling of custom subdomains + - Support for trusted origins configuration +- Fixed configuration persistence bugs (#49) + - Config merging now preserves all fields + - Retention period settings no longer reset +- Fixed sync failures with improved error handling (#51) + - Comprehensive error wrapping for all operations + - Better error messages and logging + +### Improved +- Enhanced logging throughout metadata mirroring operations + - Detailed success/failure messages for each component + - Configuration details logged for debugging +- Better configuration state management + - Proper merging of loaded configs with defaults + - Preservation of user settings on refresh +- Updated documentation + - Added LFS feature documentation + - Updated README with new features + - Enhanced CLAUDE.md with repository status definitions + ## [3.2.6] - 2025-08-09 ### Fixed diff --git a/CLAUDE.md b/CLAUDE.md index 6322937..f352b35 100644 --- a/CLAUDE.md +++ b/CLAUDE.md @@ -180,6 +180,9 @@ export async function POST({ request }: APIContext) { ### 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 @@ -192,6 +195,19 @@ export async function POST({ request }: APIContext) { - **skipForks**: Skip forked repositories (default: false) - **skipStarredIssues**: 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 + ### Authentication Configuration #### SSO Provider Configuration diff --git a/README.md b/README.md index c0f980d..d1c7cf7 100644 --- a/README.md +++ b/README.md @@ -35,9 +35,13 @@ First user signup becomes admin. Configure GitHub and Gitea through the web inte - 🔁 Mirror public, private, and starred GitHub repos to Gitea - 🏢 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, PRs, labels, milestones, wiki +- 🚫 **Repository ignore** - Mark specific repos to skip - 🔐 Secure authentication with Better Auth (email/password, SSO, OIDC) - 📊 Real-time dashboard with activity logs -- ⏱️ Scheduled automatic mirroring +- ⏱️ Scheduled automatic mirroring with flexible intervals +- 🗑️ Automatic database cleanup with configurable retention - 🐳 Dockerized with multi-arch support (AMD64/ARM64) ## 📸 Screenshots @@ -176,6 +180,30 @@ bun run dev - Override individual repository destinations in the table view - Starred repositories automatically go to a dedicated organization +## 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 Git v2.1.2+ on the server + +### Metadata Mirroring +Transfer complete repository metadata from GitHub to Gitea: +- **Issues** - Mirror all issues with comments and labels +- **Pull Requests** - Transfer PR discussions to Gitea +- **Labels** - Preserve repository labels +- **Milestones** - Keep project milestones +- **Wiki** - Mirror wiki content +- **Releases** - Transfer GitHub releases with assets + +Enable in Settings → Mirror Options → Mirror metadata + +### Repository Management +- **Ignore Status** - Mark repositories to skip from mirroring +- **Automatic Cleanup** - Configure retention period for activity logs +- **Scheduled Sync** - Set custom intervals for automatic mirroring + ## Troubleshooting ### Reverse Proxy Configuration diff --git a/docs/ENVIRONMENT_VARIABLES.md b/docs/ENVIRONMENT_VARIABLES.md index 52ac8dc..08608f4 100644 --- a/docs/ENVIRONMENT_VARIABLES.md +++ b/docs/ENVIRONMENT_VARIABLES.md @@ -25,6 +25,7 @@ Essential application settings required for running Gitea Mirror. | `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` | Base URL for authentication | `http://localhost:4321` | No | +| `BETTER_AUTH_TRUSTED_ORIGINS` | Comma-separated list of trusted origins for OIDC | - | No | | `ENCRYPTION_SECRET` | Optional encryption key for tokens (generate with: `openssl rand -base64 48`) | - | No | ## GitHub Configuration @@ -84,7 +85,7 @@ Settings for the destination Gitea instance. |----------|-------------|---------|---------| | `GITEA_ORG_VISIBILITY` | Default organization visibility | `public` | `public`, `private`, `limited`, `default` | | `GITEA_MIRROR_INTERVAL` | Mirror sync interval (automatically enables scheduler) | `8h` | Duration string (e.g., `30m`, `1h`, `8h`, `24h`) | -| `GITEA_LFS` | Enable LFS support | `false` | `true`, `false` | +| `GITEA_LFS` | Enable LFS support (requires LFS on Gitea server) | `false` | `true`, `false` | | `GITEA_CREATE_ORG` | Auto-create organizations | `true` | `true`, `false` | | `GITEA_PRESERVE_VISIBILITY` | Preserve GitHub repo visibility in Gitea | `false` | `true`, `false` | diff --git a/src/components/config/ConfigTabs.tsx b/src/components/config/ConfigTabs.tsx index 90674a7..535b071 100644 --- a/src/components/config/ConfigTabs.tsx +++ b/src/components/config/ConfigTabs.tsx @@ -59,6 +59,7 @@ export function ConfigTabs() { }, mirrorOptions: { mirrorReleases: false, + mirrorLFS: false, mirrorMetadata: false, metadataComponents: { issues: false, @@ -470,10 +471,14 @@ export function ConfigTabs() { response.giteaConfig || config.giteaConfig, scheduleConfig: response.scheduleConfig || config.scheduleConfig, - cleanupConfig: - response.cleanupConfig || config.cleanupConfig, - mirrorOptions: - response.mirrorOptions || config.mirrorOptions, + cleanupConfig: { + ...config.cleanupConfig, + ...response.cleanupConfig, // Merge to preserve all fields + }, + mirrorOptions: { + ...config.mirrorOptions, + ...response.mirrorOptions, // Merge to preserve all fields including new mirrorLFS + }, advancedOptions: response.advancedOptions || config.advancedOptions, }); diff --git a/src/components/config/MirrorOptionsForm.tsx b/src/components/config/MirrorOptionsForm.tsx index 8fb01b2..c676de0 100644 --- a/src/components/config/MirrorOptionsForm.tsx +++ b/src/components/config/MirrorOptionsForm.tsx @@ -97,6 +97,32 @@ export function MirrorOptionsForm({ + +
+ + handleChange("mirrorLFS", Boolean(checked)) + } + /> + +