RayLabsHQ/gitea-mirror v3.0.0

on GitHub

🚀 Major Release: Security & Authentication Overhaul

We're excited to announce Gitea Mirror v3.0.0, our biggest release yet! This major version brings enterprise-grade authentication options, enhanced security with token encryption, and a complete authentication system overhaul.

🔴 Breaking Changes

Important: This is a major release with breaking changes. Please read the Migration Guide before upgrading.

Authentication Changes

• Login Method: Users now log in with email instead of username
• Sessions: All existing sessions will be invalidated - users must re-authenticate
• API Endpoints: Authentication endpoints moved from /api/auth/login to /api/auth/[...all]

Environment Variables

• JWT_SECRET → BETTER_AUTH_SECRET (backward compatible)
• New required: BETTER_AUTH_URL
• New optional: ENCRYPTION_SECRET (auto-generated if not provided)

✨ New Features

🔐 Token Encryption

• All GitHub and Gitea API tokens are now encrypted at rest using AES-256-GCM
• Automatic migration encrypts existing tokens during upgrade
• Enhanced security for sensitive credentials

🏢 Enterprise Authentication

SSO/OIDC Support

• Sign in with Google, Azure AD, Okta, Authentik, or any OIDC provider
• Easy configuration through web UI
• Multiple providers supported simultaneously

Header Authentication

• Perfect for reverse proxy setups (Authentik, Authelia, Traefik Forward Auth)
• Auto-provision new users
• Domain restrictions for enhanced security

OAuth Provider

• Gitea Mirror can now act as an OIDC provider
• Enable other applications to authenticate using Gitea Mirror accounts

🛡️ Security Enhancements

• Session-based authentication with Better Auth
• Improved password hashing with bcrypt
• Enhanced error handling and security practices
• Comprehensive audit logging

🔧 Technical Improvements

• Database migration system with Drizzle Kit
• Zod v4 for improved schema validation
• Better database schema with optimized indexes
• Automated migration for Docker deployments

📦 Upgrade Instructions

Docker Users (Recommended)

# Pull the new image
docker pull ghcr.io/raylabshq/gitea-mirror:v3.0.0

# Stop current container
docker compose down

# Update docker-compose.yml to use v3.0.0
# Start with automatic migration
docker compose up -d

That's it! The container automatically:

• Generates required secrets
• Migrates users to new auth system
• Encrypts existing tokens
• Updates database schema

Manual Installation

1. Backup your database:

   cp data/gitea-mirror.db data/gitea-mirror.db.backup

2. Update environment:

   # Add to .env
   BETTER_AUTH_URL=http://localhost:4321  # Your application URL

3. Upgrade and migrate:

   git pull origin v3.0.0
   bun install
   bun run build
   bun run start  # Migrations run automatically

📝 Post-Upgrade Notes

1. All users must log in again with their email address
2. Verify GitHub/Gitea connections still work after token encryption
3. Configure SSO/OIDC if desired through Settings → Authentication & SSO
4. Update any API integrations to use new auth endpoints

🐛 Bug Fixes

• Fixed mirroring issues for starred repositories
• Resolved various authentication vulnerabilities
• Improved error handling across all API endpoints

📚 Documentation

• Comprehensive Migration Guide
• Updated authentication documentation in README
• New SSO/OIDC configuration guides

🙏 Acknowledgments

Thank you to all contributors and users who provided feedback for this release!

📊 Full Changelog

See the CHANGELOG.md for a complete list of changes.

Docker Image: ghcr.io/raylabshq/gitea-mirror:v3.0.0

Questions? Check our Discussions or report Issues.