저장소를 망가뜨리지 않고 Gitea에서 Forgejo로 이전하는 방법

Gitea를 중지하고, Forgejo를 설치하고, app.ini와 데이터 디렉터리를 복사한 후, 모든 마이그레이션 가이드가 설명하는 방식대로 서비스를 시작합니다. 웹 UI는 뜹니다. 그런데 데이터베이스 마이그레이션이 실패하거나, 더 심하게는 스키마 버전이 너무 최신이라 이해할 수 없다며 Forgejo가 시작을 거부합니다. Gitea 1.23 이상을 사용 중이라면, 모두가 문서화하는 단순한 즉시 적용 업그레이드는 더 이상 적용되지 않습니다.

Forgejo는 2024년 초 Gitea의 하드 포크가 되었고, 이후 두 프로젝트는 데이터베이스 스키마 수준에서 갈라졌습니다. 이제 Gitea를 Forgejo로 이전하는 방법은 전적으로 여러분의 Gitea 버전에 달려 있습니다. 이 가이드는 여러분의 버전에 맞는 정확한 경로, 네이티브 설치와 Docker 설치 모두를 위한 전체 명령어, Gitea 1.23 이상을 위한 우회 방법, 그리고 검증 체크리스트를 제공하여 저장소, 이슈, 사용자를 잃지 않고 이전할 수 있도록 돕습니다.

요약

• 버전 단절은 실제로 존재합니다. Forgejo v10.0은 Gitea로부터의 매끄러운 직접 업그레이드를 지원하는 마지막 릴리스였습니다. Gitea v1.22는 지원되는 직접 경로를 이용할 수 있는 가장 높은 버전입니다.
• Gitea v1.22 이하에서는: 먼저 Forgejo v10.0.x로 마이그레이션한 다음, Forgejo v10을 현재 릴리스(v15)로 업그레이드하세요. 두 단계 모두 지원됩니다.
• Gitea v1.23 이상에서는: 공식적으로 지원되는 직접 경로가 없습니다. SQL/스키마 다운그레이드, 커뮤니티 마이그레이션 스크립트, 저장소/API 마이그레이션, 또는 이 방법들 중 하나를 사용한 새 서버 스테이징 마이그레이션 중에서 선택해야 합니다. 각 방법마다 데이터 손실 트레이드오프가 다릅니다.
• 무엇이든 손대기 전에 데이터 디렉터리와 데이터베이스를 백업하세요. 아래의 모든 경로는 복원 가능한 백업이 있다는 것을 전제로 합니다. 지원되지 않는 경로는 그 전제를 두 배로 요구합니다.
• 다음 항목들은 마이그레이션 후 항상 확인이 필요합니다. 개인 액세스 토큰을 재생성하거나 감사하고, Actions 러너를 다시 등록하고, Bleve 검색 인덱스를 삭제한 후 다시 구축할 계획을 세우세요. 어떤 경로를 택하든 이 작업들은 반드시 계획에 포함하세요.
• 이전이 필수는 아닙니다. Gitea는 활발하게 유지 관리되고 있습니다. 여러분의 상황에서 이전에 따르는 위험이 이점보다 크다면 "Gitea에 남는다"는 결정도 충분히 타당합니다.

여기서 다루지 않는 범위: Gogs, GitHub, GitLab에서 Forgejo로 마이그레이션하는 것과 Forgejo Actions를 처음부터 설정하는 것입니다.

사전 준비 사항 / 필요한 것

명령을 단 하나라도 실행하기 전에 두 가지, 즉 Gitea 데이터 디렉터리(기본 네이티브 설치의 경우 /var/lib/gitea)와 데이터베이스를 완전히 복원 가능한 형태로 백업했는지 확인하세요. 데이터베이스가 SQLite라면 해당 파일은 데이터 디렉터리 안에 있습니다. PostgreSQL이나 MySQL이라면 pg_dump나 mysqldump로 별도로 덤프하세요. 검증되지 않은 백업으로 진행하는 마이그레이션은 마이그레이션이 아니라 도박입니다.

다음도 필요합니다.

• 현재 사용 중인 Gitea 버전. 다음을 실행하세요 gitea --version (또는 docker exec <container> gitea --version). 이 버전 번호가 전체 경로를 결정합니다.
• 사용 중인 데이터베이스 유형: SQLite, PostgreSQL, MySQL. 일부 우회 방법은 데이터베이스에 따라 다릅니다.
• 서버에 대한 root 또는 sudo 접근 권한.
• 지원되는 경로는 중간 단계로 Forgejo v10.0을 설치한다는 점을 알아두세요. Forgejo v10.0은 2025년 4월 16일부로 EOL 상태입니다. 이전 작업이 진행되는 동안만 설치하고, 즉시 그 버전에서 벗어나 업그레이드해야 합니다.

직접 업그레이드 경로가 깨진 이유

2024년 12월, Forgejo 프로젝트는 다음을 발표했습니다 호환성 명시 사항 명확한 선을 그었습니다. "향후 Forgejo 버전은 v1.23 이상 버전을 실행 중인 Gitea 인스턴스로부터의 업그레이드를 지원하지 않습니다." 이 한 문장이 문제의 전부를 담고 있습니다.

2024년 초 Forgejo가 Gitea에서 포크된 이후 두 코드베이스는 계속 갈라졌고, 데이터베이스 스키마도 점점 달라졌습니다. Forgejo는 기존 Gitea 운영자들이 이전할 수 있도록 호환성 기간을 유지했지만, 그 기간에도 끝이 있었습니다. 2025년 1월 16일에 출시된 Forgejo v10.0은 "the last version to allow a transparent upgrade from Gitea v1.22 or lower." v10.0보다 새로운 버전은 Gitea 데이터베이스를 직접 읽을 수 없습니다.

사람들을 놀라게 하는 것은 시점입니다. Gitea v1.23은 2024년 말에 출시되었으며, 2026년 6월 기준 현재 Gitea 릴리스는 v1.26.4입니다. Gitea 인스턴스를 어느 정도 최신 상태로 유지해 왔다면 이미 그 분기점을 지난 것이며, 표준 튜토리얼은 더 이상 여러분의 상황을 설명하지 못합니다.

섹션 요약: 지원되는 직접 경로는 Gitea v1.22까지만 적용됩니다. 그보다 최신 버전은 모두 추가 단계가 필요합니다.

Gitea 버전별로 이전 경로 찾기

실행 gitea --version, 해당하는 행을 찾은 다음 세 번째 열에 있는 경로를 따르세요. 이 가이드의 나머지 내용은 모두 이 행들 뒤에 있는 세부 사항입니다.

버전 호환성에 대한 명시 사항은 공식 Forgejo 호환성 발표: Gitea v1.21까지는 Forgejo v7.0부터 v10.0까지 이전할 수 있고, Gitea v1.22는 Forgejo v8.0부터 v10.0까지 이전할 수 있습니다. 두 경우 모두 지원되는 마지막 직접 대상 버전은 v10.0입니다.

버전 문제 아래에는 세 가지 마이그레이션 전략이 자리 잡고 있으며, 단계별 절차를 보기 전에 먼저 살펴보는 것이 도움이 됩니다.

• 제자리에서, 동일 서버에서. 기존 서버에서 바이너리나 컨테이너 이미지를 교체하세요. 사용 중인 버전이 지원한다면 가장 적은 노력이 들지만, v10.0 중간 단계를 거쳐야 합니다.
• 새 서버에서의 스테이징. 새 서버를 프로비저닝하여 사용 중인 Gitea 버전에 맞는 마이그레이션 방식의 안전한 대상으로 사용하세요. 이렇게 하면 기존 Gitea 서버가 보호되고 롤백이 쉬워지지만, Gitea 1.23+의 데이터베이스 스키마 문제를 우회할 수는 없습니다.
• 저장소/API 마이그레이션. Forgejo의 마이그레이션 도구를 사용하여 기존 Gitea 인스턴스에서 저장소를 가져오세요. Git 히스토리는 신뢰할 수 있는 부분이며, 이슈, PR, 레이블, 릴리스, 위키 데이터, 댓글과 같은 메타데이터는 최선의 노력 수준으로 간주하고 저장소별로 확인해야 합니다.

지원되는 경로: Gitea v1.22 이하

Gitea v1.22 이하를 사용 중이라면, 공식 마이그레이션 문서 2단계 경로를 설명합니다. 먼저 Forgejo v10.0.x로 마이그레이션한 다음, Forgejo v10을 현재 릴리스로 업그레이드하는 것입니다. Forgejo v10.x가 Gitea v1.22 데이터베이스를 그대로 읽을 수 있으므로 첫 단계는 드롭인 교체이며, 두 번째 단계는 일반적인 Forgejo 업그레이드입니다.

이를 수행하는 방법은 서버에서 Gitea가 어떻게 실행되는지에 따라 두 가지가 있습니다. 기존 설정에 맞는 방법을 선택하세요. Gitea가 시스템 서비스로 실행 중이라면 네이티브 경로를 사용하고, 컨테이너에서 실행 중이라면 Docker 경로를 사용하세요. Forgejo v10.x는 Gitea v1.22.x의 드롭인 대체품 역할을 합니다.

네이티브(systemd) 경로

먼저 백업하세요. 그런 다음 배포판 패키지나 v10.0으로 고정된 릴리스 바이너리를 사용해 Forgejo v10.0.x를 설치하세요. 무엇이든 복사하기 전에 Gitea를 중지하세요. 서비스가 실행 중인 상태에서 데이터 디렉터리에 쓰기 작업이 이루어지면 복사본이 손상됩니다.

# Stop the running Gitea service before touching its data
systemctl stop gitea

설정 파일과 데이터 디렉터리를 Forgejo의 위치로 복사한 다음 소유권을 수정하세요. 설정 파일은 forgejo 그룹이 읽을 수 있어야 하며, 데이터는 forgejo 사용자가 소유해야 합니다.

# Copy the existing Gitea config to Forgejo's config path
cp /etc/gitea/app.ini /etc/forgejo/app.ini

# Back up the copied config before rewriting paths
cp /etc/forgejo/app.ini /etc/forgejo/app.ini.bak

# Update old Gitea data paths to Forgejo data paths
sed -i 's#/var/lib/gitea#/var/lib/forgejo#g' /etc/forgejo/app.ini

# Forgejo reads its config as the forgejo group; grant group write
chown root:forgejo /etc/forgejo/app.ini && chmod g+w /etc/forgejo/app.ini

# Copy the data directory and hand ownership to the forgejo user
rsync -aHAX --numeric-ids /var/lib/gitea/ /var/lib/forgejo/
chown -R forgejo:forgejo /var/lib/forgejo

Forgejo를 시작하고 부팅 시 자동 실행되도록 설정하세요.

# Start Forgejo and enable it at boot
systemctl start forgejo && systemctl enable forgejo

v10.0에서 업그레이드하기 전에 큐를 비워서 버전 전환 중에 진행 중이던 작업이 유실되지 않도록 하세요.

# Flush pending queue items before the version upgrade
forgejo manager flush-queues

이제 바이너리를 v15로 교체하고 서비스를 재시작하여 Forgejo v10.0.x를 현재 릴리스로 업그레이드하세요. 표준 Forgejo 업그레이드 가이드. 두 단계를 모두 거친 후, doctor를 실행하여 데이터베이스를 점검하고 고칠 수 있는 부분을 수정하세요.

# Check everything; write a log you can read if something is wrong
forgejo doctor check --all --log-file /tmp/doctor.log

읽기 /tmp/doctor.log 자동 수정을 적용하기 전에. 다음을 사용하세요 --fix doctor 출력이 이해하고 있는 특정 복구 작업을 지목하거나 공식 문제 해결 경로를 따르는 경우에만 사용하세요.

doctor가 치명적인 오류를 보고하지 않고 웹 UI에 저장소 목록이 나타난다면, 첫 번째 이전 단계는 완료된 것입니다.

Docker / 컨테이너 경로

Gitea를 컨테이너로 운영했다면 Forgejo도 같은 방식으로 운영하세요. Forgejo v10.x 이미지를 Gitea v1.22.x 이미지의 드롭인 대체품으로 사용하고, 동일한 데이터 볼륨과 데이터베이스를 가리키게 하세요. 먼저 Docker 버전이 최소 20.10.6인지 확인하세요. 그보다 이전 버전은 Forgejo 컨테이너에서 정의되지 않은 동작을 일으킵니다.

컨테이너 환경에서 특히 사람들을 헷갈리게 하는 세부 사항이 하나 있습니다. 바로 환경 변수입니다. Forgejo는 호환성을 위해 GITEA_ 접두사를 그대로 유지하지만, 향후 Forgejo 버전에서 기존 이름이 제거되더라도 설정이 유지되도록 두 접두사를 모두 전달할 것을 문서에서 권장합니다.

# docker-compose.yml (excerpt): pass both prefixes for forward compatibility
environment:
  - GITEA__database__DB_TYPE=postgres
  - FORGEJO__database__DB_TYPE=postgres
  # ...repeat the dual-prefix pattern for every config override you pass

루트리스 컨테이너의 경우 데이터는 루트리스 이미지의 런타임 사용자와 일치하도록 사용자 1000, 그룹 1000이 소유해야 합니다. 컨테이너가 v10.x에서 시작된 후 동일한 forgejo doctor check --all 컨테이너 내부에서, 그런 다음 이미지 태그를 현재 v15 릴리스로 업그레이드하고 재시작하세요.

Gitea v1.23 이상을 사용 중이라면

표준 가이드가 끝나는 지점이자, 실제로 현재 설치의 대부분이 위치한 지점이 바로 여기입니다. Gitea v1.23+에서는 공식적으로 지원되는 직접 경로가 없으므로, 아래 옵션들은 모두 커뮤니티 제공이거나 데이터 손실을 동반합니다. 어느 것을 실행하기 전이든 데이터 디렉터리와 데이터베이스의 전체 백업을 만들고 복원이 가능한지 확인하세요. 이 방법들은 운영 데이터를 변경하며, 백업만이 유일한 되돌리기 수단입니다.

세 가지 옵션은 위험도와 보존되는 데이터의 양에서 차이가 있습니다. 감수할 수 있는 트레이드오프를 가진 옵션을 선택하세요.

옵션 A: SQL 스키마 다운그레이드 / 버전 패치

가장 제한적인 우회 방법은 데이터베이스 스키마 버전을 다운그레이드하여 Forgejo v10이 이를 v1.22 데이터베이스로 인식하게 만드는 것입니다.

참고: 버전 업데이트 자체를 완전한 다운그레이드로 취급하지 마세요. 기록된 마이그레이션 버전과 실제 스키마가 일치해야 합니다. Gitea 1.23.x에서는 먼저 복사본으로 전체 다운그레이드를 테스트하고 스키마를 비교한 후에 Forgejo가 그것을 가리키도록 하세요.

Forgejo의 한 메인테이너는 해당 SQL을 다음에서 설명했습니다 Codeberg 이슈 #7638:

-- Downgrade the recorded schema version to the v1.22 baseline (PostgreSQL/MySQL)
UPDATE version SET version=305 WHERE id=1;

이 작업 이후에는 마치 v1.22에 있는 것처럼 지원되는 경로를 따르면 됩니다. 다만 중요한 주의 사항이 있습니다. 관리자는 이를 Gitea v1.23.1에 대해서만 구체적으로 확인했으며, v1.23.x 전체에 대해 확인한 것은 아닙니다. 스키마 버전 번호는 정확해야 하며, 잘못된 대상 값을 잘못된 Gitea 릴리스에 적용하면 어떤 마이그레이션으로도 복구할 수 없는 상태로 데이터베이스가 남을 수 있습니다. 이는 PostgreSQL/MySQL에 해당하며, 공식적으로 지원되지 않고 일반적인 절차로 테스트되지도 않았습니다.

프로 팁: version=305를 직접 설정하면 TOTP 비밀 값의 인코딩 방식을 변경한 304→305 마이그레이션 단계를 건너뛰게 됩니다. Codeberg 이슈 #8210 영향을 받는 사용자의 2단계 인증(2FA)이 손상된다고 문서화되어 있습니다. 해결 방법은 버전을 304로 설정하고 마이그레이션을 실행하거나, two_factor 테이블의 행을 삭제하여 사용자가 다시 등록하도록 하는 것입니다. TOTP를 사용하는 계정이 하나라도 있다면 이 단계를 건너뛰지 마세요.

옵션 B: 순차적 SQL 다운그레이드 스크립트 (Gitea 1.24–1.25.2)

1.24와 1.25.2 사이 버전의 경우 단일 버전 패치만으로는 충분하지 않습니다. 스키마가 여러 중간 상태를 거쳐 변경되었기 때문입니다. 다음 커뮤니티 스크립트는 xlrl/prepare-gitea-migration-to-forgejo 중간 버전들을 거쳐 스키마를 v1.22까지 되돌린 후, 지원되는 경로를 따르게 됩니다. 이 스크립트들은 공식 절차가 아니라 커뮤니티 작업물이며, 주로 SQLite를 대상으로 합니다. 이미 백업해 둔 데이터베이스에 대해서만 실행하세요.

옵션 C: 저장소별 API 마이그레이션 (Gitea 1.26+ 또는 모든 버전)

저장소/API 경로는 Git 데이터를 가장 안정적으로 보존합니다. 소스, 권한, 마이그레이션 방식에 따라 이슈, 풀 리퀘스트, 레이블, 마일스톤, 릴리스, 위키 데이터, 댓글과 같은 선택적 메타데이터도 이전될 수 있지만, 이는 어디까지나 최선의 노력 수준으로 간주하고 저장소별로 직접 확인해야 합니다. 코드만 보관하는 아카이브라면 대체로 문제없지만, 이슈 트래커가 팀의 기록 저장소 역할을 하는 서버라면 이 경로를 확정하기 전에 메타데이터 전송을 테스트하세요.

두 가지 실험적 도구가 1.23+ 버전에서 더 완전한 마이그레이션을 시도하지만, 각각 나름의 한계를 가지고 있습니다. pacnpal/gitea2forgejo (GitHub) 전체 덤프와 API 동기화를 수행하며, 암호화된 필드를 이전하려면 일치하는 SECRET_KEY가 필요합니다. 다만 Personal Access Tokens, Actions 러너, 웹훅 콜백 URL, 2FA는 이전하지 않습니다. nicoverbruggen/gitea-to-forgejo (GitHub) 는 Podman 기반의 실험적 도구로, 사용자, 키, 조직, 저장소, 이슈, PR, 릴리스, 미러를 이전하지만 2FA 토큰, Actions 런타임 데이터, 참조가 끊긴 OCI 패키지 매니페스트는 이전하지 않습니다. 두 도구 모두 실험적인 것으로 간주하고, 아래 이전 매트릭스와 대조하여 결과를 검증하세요.

섹션 요약: Gitea 1.23+에서는 공식적으로 지원되는 직접 경로가 없습니다. 감수할 수 있는 데이터 손실 트레이드오프를 기준으로 옵션을 선택하고, 시작하기 전에 반드시 백업하세요.

새 서버에서 이전하는 것이 더 안전하지만, 버전 분기점을 건너뛸 수는 없습니다

새 서버는 이전 작업을 준비하고 검증하기에 가장 안전한 장소이지만, 별도의 스키마 호환 경로가 되는 것은 아닙니다. 소스가 Gitea v1.22 이하라면 먼저 대상 서버에 Forgejo v10.0.x를 설치하고, Gitea 데이터를 그곳으로 복원하거나 복사한 다음, Forgejo가 지원되는 데이터베이스 마이그레이션을 실행하도록 하고, 마지막으로 그 Forgejo v10 인스턴스를 현재 Forgejo 릴리스로 업그레이드하세요.

소스가 Gitea v1.23 이상이라면 Gitea 데이터베이스를 현재 Forgejo에 곧바로 복원해서 정상 작동하기를 기대해서는 안 됩니다. 위에서 설명한 지원되지 않는 1.23 이상 대응 방법 중 하나, 즉 단계적 SQL 다운그레이드 또는 되돌리기, 커뮤니티 마이그레이션 도구, 저장소/API 이전 중 하나가 여전히 필요합니다. 새 서버는 원래 Gitea 서버가 그대로 유지되므로 롤백 위험을 줄여주지만, 데이터베이스 버전 불일치를 처리해야 할 필요성 자체를 없애주지는 않습니다.

바로 여기서 Cloudzy의 원클릭 Forgejo 앱이 도움이 될 수 있습니다. 이를 깨끗한 대상 인스턴스로 사용한 다음, 사용 중인 Gitea 버전에 맞는 마이그레이션 방법을 실행하세요. Cloudzy의 마켓플레이스 이미지는 저희 고성능 VPS, 그래서 초기 설치 대신 복원, 검증, 전환 단계에 집중할 수 있습니다. 이전 계획은 여전히 Gitea 1.22 분기점 이전인지 이후인지에 따라 달라집니다.

무엇이 이전되고 무엇을 다시 해야 하는가

데이터 중 일부는 자동으로 이전되고, 일부는 특정 조건이 충족될 때만 이전되며, 일부는 절대 이전되지 않아 수동으로 다시 만들어야 합니다. 시작하기 전에 어느 것이 어디에 해당하는지 파악해 두면 깔끔한 전환과 일주일 동안 혼란에 빠진 사용자들 사이의 차이를 만듭니다.

네 가지 항목이 가장 큰 영향을 미치는데, 조용히 깨지거나 모든 사용자에게 영향을 주기 때문입니다. 그러니 신중하게 처리하세요. 사용자는 Personal Access Tokens를 재생성하거나 점검해야 하고, 새 호스트명에 맞춰 Actions 러너를 다시 등록해야 하며, Forgejo가 깨끗하게 재구축하도록 Bleve 검색 인덱스를 삭제해야 하고, 다음과 같은 항목을 다시 작성해야 합니다 uses: Actions 워크플로 내의 짧은 참조를 전체 GitHub URL로 바꾸세요. Forgejo와 Gitea는 서로 다른 미러에서 액션을 가져오기 때문에 상대 참조는 잘못된 위치를 가리키게 됩니다.

프로 팁: 마이그레이션 중 Gitea와 Forgejo를 동시에 실행하고 두 서비스가 같은 Redis 인스턴스를 가리키는 경우, 시작하기 전에 Forgejo를 Redis db=1로 변경하세요. 둘 다 기본값이 db=0이며, 이를 공유하면 Gitea가 Forgejo의 마이그레이션 이벤트를 소비하여 마이그레이션 큐를 망가뜨립니다. (blog.mei-home.net documents this exact failure.)

섹션 요약: 개인 액세스 토큰, Actions 러너, 저장소별 배포 키, Bleve 검색 인덱스는 항상 수동으로 처리해야 합니다. 이를 나중에 떠올릴 일이 아니라 마이그레이션 작업 항목으로 미리 계획하세요.

마이그레이션 성공 여부 확인

먼저 doctor 명령으로 시작한 다음 수치를 확인하고, 마지막으로 사용자가 실제로 수행하는 작업을 테스트하세요. doctor는 데이터베이스 수준의 문제를 잡아내며, 수동 점검은 doctor가 발견할 수 없는 데이터 손실 및 접근 권한 문제를 잡아냅니다.

1. 실행 forgejo doctor check --all --log-file /tmp/doctor.log, 그런 다음 변경을 적용하기 전에 로그를 확인하세요. 다음을 사용하세요 --fix 이해하고 있는 특정 복구 작업에 대해서만 사용하세요.
2. 저장소 개수, 이슈 및 PR 개수, LFS 객체 개수와 총 용량이 모두 이전 작업 전의 수치와 일치하는지 확인하세요. 여기서 불일치가 발견되면 무언가 제대로 넘어오지 않았다는 뜻입니다.
3. SSH push와 pull을 테스트하세요. 클라이언트가 호스트 키 불일치 오류를 받는다면 /etc/ssh/ssh_host_*를 새 서버로 복사하지 않은 것입니다.
4. 로그인하여 2FA를 사용하는 계정에서 2FA가 정상 작동하는지 확인하세요. TOTP가 깨졌다면 위의 옵션 A 관련 주의 사항을 참고하세요.
5. 개인 액세스 토큰을 재생성하고, Actions 러너를 다시 등록한 후 테스트 워크플로를 실행하세요.

이전 후 나타나는 몇 가지 증상은 원인이 알려져 있습니다. 파비콘이나 로고가 사라졌다면 브랜딩 자산이 Forgejo가 이제 기대하는 custom/이 아니라 여전히 public/assets/img/에 있다는 뜻입니다. 패키지 경로에서 404 오류가 발생한다면 스토리지 경로 설정이 잘못된 것입니다. Actions가 "repository not found" 오류로 실패하는 것은 uses: 미러 문제입니다. 전체 URL로 전환하세요. SQLite 데이터베이스에서 로그인 후 빈 화면이나 500 오류 페이지가 나타난다면 최소 요구 사양에 미달한다는 뜻이며, 이는 업그레이드 문서 Forgejo v1.19.3-0으로 지정했습니다.

Gitea를 계속 사용하는 것이 합리적인 경우

이전은 선택이지 의무가 아닙니다. 이미 그 분기점을 지났고 이전의 복잡성이 여러분 상황에서의 거버넌스나 기능상 이점보다 크다면, Gitea에 남는 것도 타당한 선택입니다. Gitea는 활발히 유지 관리되고 있으며(매달 여러 차례 릴리스, 현재 v1.26.4), CommitGo는 다음을 포함한 상용 옵션을 제공합니다 Gitea Enterprise, Gitea Cloud, SOC 2 Type 2 인증 필요한 팀을 위해서요.

솔직히 짚고 넘어가야 할 EOL 중간 단계 문제도 있습니다. 지원되는 직접 경로는 2025년 4월부터 EOL(지원 종료) 상태인 Forgejo v10.0을 잠시 설치해야 합니다. 즉시 업그레이드하여 벗어나는 일시적인 마이그레이션 단계로는 받아들일 수 있지만, 정책상 이를 반대하는 운영자도 있을 것입니다. 그런 경우 새 Forgejo 인스턴스로의 저장소/API 마이그레이션을 이용하면 EOL 단계를 완전히 피할 수 있지만, 새 서버 스테이징 방식은 여전히 선택한 마이그레이션 방법에 좌우됩니다.

이전하려는 이유가 개발 활동량이라면, 데이터는 Forgejo가 더 활발한 프로젝트임을 뒷받침합니다. 다음 분석에 따르면 honeypot.net 2024년 7월부터 2025년 5월까지 Forgejo 커밋 3,039건과 Gitea 커밋 1,228건을 집계했고, 2025년 5월까지 1년간 Forgejo 기여자 232명과 Gitea 기여자 153명을 집계했습니다. 이는 여러 신호 중 하나일 뿐이므로, 결정적인 요소로 취급하기보다 마이그레이션 위험과 함께 저울질해야 합니다.

섹션 요약: 마이그레이션은 필수가 아닙니다. 이 결정은 거버넌스 및 활동성에 대한 선호도를 마이그레이션 위험과 저울질하는 문제이며, 어느 쪽을 선택해도 타당합니다.

경로를 선택하고 먼저 백업하세요

마이그레이션 경로는 결국 하나의 숫자, 즉 Gitea 버전으로 결정됩니다. v1.22 이하라면 Forgejo v10을 거치는 지원되는 2단계 경로를 사용합니다. v1.23 이상이라면 감수할 수 있는 데이터 손실 정도에 따라 SQL/스키마 다운그레이드, 커뮤니티 스크립트, 저장소/API 마이그레이션, 새 서버 스테이징 마이그레이션 중에서 우회 방법을 선택합니다. 어느 경로를 택하든 먼저 데이터 디렉터리와 데이터베이스를 백업한 후 다음을 실행하세요 forgejo doctor 이후 저장소, 이슈, LFS 개수가 시작할 때와 일치하는지 확인하세요.

버전을 확인하고, 백업을 받은 다음, 해당하는 행을 따라가세요. 그 경로는 예전 튜토리얼이 약속했던 것보다 더 복잡하지만, 버전 분기점에서 자신의 위치를 알고 나면 명확하게 정의되어 있습니다.

자주 묻는 질문

Gitea에서 Forgejo로 직접 업그레이드할 수 있나요?

Gitea v1.22 이하를 실행 중이라면 가능합니다. Forgejo v10.0으로 직접 업그레이드한 후 Forgejo v10을 현재 릴리스로 업그레이드하세요. Gitea v1.23 이상을 실행 중이라면 불가능합니다. Forgejo v10.0이 투명한 직접 업그레이드를 지원하는 마지막 릴리스였으므로, 더 최신 Gitea 버전은 대신 우회 방법이 필요합니다.

Forgejo와 호환되는 Gitea 버전은 무엇인가요?

Gitea v1.22 이하는 Forgejo로의 지원되는 직접 업그레이드 경로가 있습니다(Forgejo v10.0까지, 이후 현재 버전으로 이어짐). Gitea v1.23 이상은 공식적으로 지원되는 직접 경로가 없는데, Forgejo가 v10.0 이후 릴리스부터 Gitea v1.23 이상으로부터의 매끄러운 업그레이드 지원을 중단했기 때문입니다.

Gitea 1.26에서 Forgejo로 이전할 수 있나요?

가능하지만 지원되는 직접 업그레이드 방식으로는 안 됩니다. 선택할 수 있는 방법은 Git 히스토리는 신뢰할 수 있지만 메타데이터는 저장소별로 테스트해야 하는 저장소/API 마이그레이션, 실험적 마이그레이션 스크립트, 또는 위에서 다룬 지원되지 않는 1.23+ 방법 중 하나를 사용한 새 서버 스테이징 마이그레이션입니다. Gitea 1.26에서 공식적으로 지원되는 즉시 적용 경로는 없습니다.

Personal Access Tokens는 이전되나요?

마이그레이션 후 개인 액세스 토큰을 재생성하거나 교체할 계획을 세우세요. 일부 마이그레이션 경로는 토큰을 보존하지 않으며, 토큰이 남아 있더라도 사용자는 다시 사용하기 전에 범위(scope)를 감사해야 합니다. 이전 토큰을 사용하는 모든 스크립트나 통합은 전환 후 테스트하고 업데이트해야 합니다.

Gitea Actions 워크플로가 Forgejo에서도 작동하나요?

대체로 그렇지만, 두 가지 필수 수정이 필요합니다. 워크플로 uses: 짧은 참조는 Forgejo와 Gitea가 서로 다른 미러에서 액션을 가져오기 때문에 깨집니다. 이를 전체 GitHub URL로 전환하세요(예를 들어, uses: https://github.com/sammcj/dotenv-output-action@main). 또한 Actions 러너를 다시 등록해야 합니다. 등록 토큰이 이전 호스트명에 묶여 있기 때문입니다.

Gogs에서 Forgejo로의 마이그레이션은 어떨까요?

이는 다른 경로를 거치는 별개의 마이그레이션이며 여기서 다루는 범위를 벗어납니다. 이 가이드는 구체적으로 Gitea에서 Forgejo로의 마이그레이션을 다루며, Gogs가 소스인 경우에는 Gogs 전용 절차에 대해 Forgejo의 공식 마이그레이션 문서를 참고하세요.