Gitea Senkronizasyonu

Bu özellik ayaka-notes/ayakaleaf-pro tarafından geliştirilmiştir. v6.3.2 sürümünde erken önizleme olarak sunulmuştur ve v6.4.0 sürümünde resmi olarak yayınlanacaktır; bu nedenle yapılandırması ve davranışı hâlâ değişebilir. Herhangi bir sorun yaşarsanız geri bildiriminize ihtiyacımız var.

Gitea Senkronizasyonu, GitHub Senkronizasyonu ve GitLab Senkronizasyonu gibi çalışır: kullanıcılar Gitea hesaplarını bağlar, projeleri yeni Gitea depolarına dışa aktarır, Gitea depolarını içe aktarır ve değişiklikleri her iki yönde senkronize eder. gitea.com üzerinde veya kendi örneğinizde Gitea 1.23 veya sonraki sürümlerle çalışır.

​

Gitea Senkronizasyonunu Kurma

Gitea Senkronizasyonunu kullanmadan önce git-bridge özelliğini etkinleştirmeniz gerekir.

config/overleaf.rc

GIT_BRIDGE_ENABLED=true

Gitea örneğinizde Settings → Applications → Manage OAuth2 applications altında (örnek genelinde bir uygulama için Site Administration → Integrations → Applications altında) bir OAuth2 uygulaması oluşturun:

• Application name: ör. Overleaf; kullanıcılar uygulamayı yetkilendirirken bu adı görür
• Redirect URIs: ${OVERLEAF_SITE_URL}/user/gitea-sync/oauth2/callback
• Confidential client: işaretli

Client ID ve Client Secret değerlerini kopyalayın, ardından aşağıdaki ayarları Overleaf ortam değişkeni dosyalarınıza ekleyin.

config/variables.env

# used to encrypt the user's Gitea access and refresh tokens.
# How to generate: `openssl rand -hex 32`
GITEA_TOKEN_CIPHER_PASSWORD=0123456789ABCDEFG # changed to yours

# Gitea Sync Settings
GITEA_SYNC_ENABLED=true
GITEA_SYNC_CLIENT_ID=
GITEA_SYNC_CLIENT_SECRET=

# Web address of your Gitea (its ROOT_URL), defaults to https://gitea.com
# GITEA_SYNC_URL=https://gitea.example.com

# OAuth callback is: ${OVERLEAF_SITE_URL}/user/gitea-sync/oauth2/callback
# (Optional) GITEA_SYNC_PROXY_URL=http://10.0.0.1:10808

Gitea yönlendirme URI’sini yapılandırmadan önce OVERLEAF_SITE_URL değerinin doğru ayarlandığından emin olun.

Overleaf, kullanıcı hesabını bağlarken bir senkronizasyonun ihtiyaç duyduğu her şeyi ister; böylece kullanıcılar eksik bir izin nedeniyle hesaplarını asla yeniden bağlamak zorunda kalmaz:

Kapsam	Kullanım amacı
write:repository	Depolar, dosyaları (.gitea/workflows altındaki CI iş akışları dahil), dallar ve pull request’ler
write:user	Dışa aktarırken kullanıcıya ait bir depo oluşturma (Gitea bunu POST /user/repos için ister)
write:organization	Kullanıcının organizasyonlarını listeleme ve dışa aktarırken bunlardan birine ait bir depo oluşturma

Gitea, kullanıcı uygulamayı yetkilendirirken bu kapsamları gösterir ve belirteci bunlarla sınırlar.

Gitea erişim belirteçlerinin süresi bir saat sonra dolar ([oauth2] ACCESS_TOKEN_EXPIRATION_TIME). Overleaf bunları, Gitea’nın erişim belirteçleriyle birlikte verdiği yenileme belirteciyle yeniler; Gitea yenileme belirteçlerini kullanımda tükettiğinde de (INVALIDATE_REFRESH_TOKENS = true) bu böyledir. Böylece kullanıcılar, bağlantıyı kaldırana veya uygulamayı Gitea’da iptal edene kadar bağlı kalır.

​

Gitea örneğiniz

GITEA_SYNC_URL değerini örneğinizin web adresine, yani ROOT_URL değerine, depoları tarayıcıda açtığınız adrese ayarlayın. REST API adresi bundan türetilir:

Değişken	Varsayılan
GITEA_SYNC_URL	https://gitea.com
GITEA_SYNC_API_URL	${GITEA_SYNC_URL}/api/v1

Bir alt yol altında sunulan Gitea da çalışır, ör. GITEA_SYNC_URL=https://example.com/gitea. GITEA_SYNC_API_URL değerini yalnızca örneğiniz API’yi başka bir yerde sunuyorsa (örneğin bir API ağ geçidinin arkasında) ayarlayın.

• OAuth2 uygulamasını GITEA_SYNC_URL içinde ayarladığınız örnekte oluşturun; başka bir örnekten alınan bir uygulama çalışmaz.
• GITEA_SYNC_URL yalnızca web adresidir. /api/v1 veya bir kullanıcı ya da organizasyon yolu eklemeyin.
• Overleaf, web editörünü gerektiren Gitea dosya API’si ile commit yapar: [repository.editor] ayarını etkin tutun (varsayılan).

Örneğiniz özel bir CA’dan alınmış bir sertifika kullanıyorsa, CA sertifikasını konteynere bağlayın ve NODE_EXTRA_CA_CERTS değişkenini bu dosyayı gösterecek şekilde ayarlayın, ör. NODE_EXTRA_CA_CERTS=/var/lib/overleaf/certs/gitea-ca.pem.

Bağlanan hesaplar ve projeler, bağlandıkları örneğe aittir. GITEA_SYNC_URL değerini başka bir örneğe geçirmeden önce kullanıcılardan Gitea hesaplarının ve projelerinin bağlantısını kaldırmalarını isteyin.

Ağ erişiminin kısıtlı olduğu bir bölgede bulunuyorsanız, Gitea’ya erişmek için bir proxy yapılandırmanız gerekebilir. Şu ortam değişkenini ayarlayın: GITEA_SYNC_PROXY_URL=http://10.0.0.1:10808. Bu, standart bir HTTP/HTTPS ileri proxy’si olmalı ve 127.0.0.1 kullanmamalıdır.

​

Kimler bağlayabilir ve senkronize edebilir

Overleaf Cloud’da olduğu gibi, bir projeyi bir Gitea deposuna yalnızca proje sahibi bağlayabilir. Bağlandıktan sonra, düzenleme erişimine sahip her ortak çalışan projeyi senkronize edebilir.

İşlem	Kimler yapabilir
Bir projeyi yeni bir Gitea deposuna dışa aktarma	Proje sahibi
Bir Gitea deposunu yeni bir projeye içe aktarma	Herhangi bir kullanıcı; bu kullanıcı yeni projenin sahibi olur
Bağlı bir projeyi çekme, gönderme ve birleştirme	Proje sahibi ve düzenleme erişimine sahip ortak çalışanlar
Bir projenin deposuyla bağlantısını kaldırma	Proje sahibi

• Overleaf, Gitea ile senkronizasyonu yapan kullanıcının Gitea hesabı üzerinden iletişim kurar; bu nedenle senkronizasyon yapan her ortak çalışan kendi Gitea hesabını bağlar ve deponun varsayılan dalına gönderme (push) izni olması gerekir.
• Yalnızca görüntüleme erişimine sahip ortak çalışanlar, proje için Gitea Senkronizasyonunu kullanamaz.
• Overleaf’te hesabın bağlantısını kaldırmak, belirtecini unutur; Gitea’da bunu iptal etmeye yarayan bir API yoktur. Bu nedenle isterseniz Gitea’da Settings → Applications altından izni de iptal edin.

​

Gitea ile senkronizasyon nasıl çalışır

• İzinler: kullanıcıların bağlı deponun varsayılan dalına gönderme izni olmalıdır. Bir dal koruma kuralı kullanıcının bu dala gönderme yapmasına izin vermediğinde, Overleaf erişimini kaybettikleri bir depoda olduğu gibi kullanıcıdan proje sahibiyle iletişime geçmesini ister.
• Birleştirme: bir proje hem Overleaf’te hem de Gitea’da değiştiğinde, Overleaf değişikliklerini overleaf-YYYY-MM-DD-HHMMSS adlı geçici bir dala işler ve bunu deponun varsayılan birleştirme stiliyle bir pull request aracılığıyla birleştirir; çünkü Gitea’da pull request olmadan dalları birleştirmeye yarayan bir API yoktur. Birleştirmeden sonra Overleaf geçici dalı siler; birleştirilmiş pull request bir kayıt olarak depoda kalır.
• Birleştirme kuralları: Overleaf, deponun dal korumasını asla atlamaz. Pull request’te bir çakışma olduğunda veya onaylar ya da başarılı durum denetimleri gerektiğinde, pull request açık kalır ve Overleaf kullanıcıdan bunu Gitea’da birleştirmesini, ardından senkronizasyona devam etmesini ister.
• CI iş akışları: Overleaf, .gitea/workflows/ gibi nokta dosyalarını göstermez ve bunları depoda oldukları gibi bırakır. Overleaf’ten gelen commit’ler, diğer tüm commit’ler gibi Gitea Actions’ı başlatır.

​

Q&A

Varsayılan dala zorla gönderme (force push) yapabilir miyim?

Yanıt: Lütfen varsayılan dala zorla gönderimleri, örneğin bir dal koruma kuralıyla, devre dışı bırakılmış olarak tutun. Overleaf yeniden yazılmış bir dalı devralabilir, ancak Gitea Senkronizasyonu geçmişi yalnızca büyüyen bir varsayılan dal için tasarlanmıştır.

Bağlı bir projenin varsayılan dalını yeniden adlandırabilir miyim?

Yanıt: Hayır. Overleaf, projenin bağlandığı dalla senkronize olmaya devam eder; bu nedenle o dal yeniden adlandırıldığında veya kaldırıldığında senkronizasyonlar başarısız olur. Başka bir dalla senkronize etmek için projenin bağlantısını kaldırın, ardından depoyu yeni bir projeye içe aktarın; yeni proje mevcut varsayılan dalı kullanır.

Gitea Senkronizasyonu Git LFS'yi destekliyor mu?

Yanıt: Hayır. Overleaf projeleri Git Large File Storage’ı desteklemez. Git LFS tarafından izlenen dosyalar Overleaf’te içerikleriyle değil, LFS işaretçi dosyaları olarak görünür. Bunun yerine görselleri ve PDF’leri doğrudan depoya commit edin.

SHA-256 depolarıyla çalışıyor mu?

Yanıt: Henüz değil. Overleaf dosyaları SHA-1 kimliklerine göre karşılaştırır; bu nedenle SHA-256 nesne biçimiyle oluşturulmuş bir depoda her çekme işlemi, değişmemiş olanlar dahil tüm dosyaları yeniden yazar. Hiçbir şey kaybolmaz, ancak lütfen varsayılan SHA-1 biçimini kullanın.

Forgejo ile çalışıyor mu?

Yanıt: Gitea Senkronizasyonu yalnızca Gitea için geliştirilmiş ve yalnızca Gitea üzerinde test edilmiştir.