Contextator
ENTR

Kaynaklar

Git Deposu Kaynağı

Bir git deposundan doğrudan dokümantasyon indekslemek — özel depolar, sağlayıcı token'ları, senkronizasyonun ve push tetiklemeli yeniden indekslemenin nasıl çalıştığı.

Güncelleme:

Bir git deposundan doğrudan dokümantasyon indekleyin. Contextator, sunucuda shallow ve tek dallı bir checkout tutar ve her indeksleme çalıştırmasının başında dalın ucunu çeker — ya da bir webhook eklerseniz, biri push ettiği anda.

Herhangi bir HTTPS git sunucusuyla çalışır: GitHub, GitLab, Bitbucket, Gitea, Forgejo, Codeberg ve self-hosted örnekler.

Bir tane eklemek

Add source → Git repository

Alan Örnek Notlar
Name api-docs Mount öneki. Değiştirilemez
Repository URL https://github.com/org/repo.git Yalnızca HTTP(S), HTTPS şiddetle önerilir — SSH remote’ları desteklenmez
Branch main Checkout edilen tek dal
Subdirectory docs Opsiyonel. Yalnızca deponun bu klasörünü indeksle
Access token – Yalnızca özel depolar için. Şifreli saklanır, bir daha gösterilmez
Username – Yalnızca bir GitLab deploy token’ı (gitlab+deploy-token-N) ya da bir Bitbucket Cloud API token’ı için gerekir (Bitbucket kullanıcı adınız ya da x-bitbucket-api-token-auth)
File types .md, .mdx .txt, .html/.htm, .csv, .docx ve .pdf de seçilebilir

Kaynak kaydedildikten sonra satırındaki Test’e (ya da Edit diyaloğundaki Test connection’a) basın: klonlamadan remote’un ref’lerini listeler ve dalın güncel commit’iyle yanıtlar, bu yüzden yanlış bir URL, dal ya da token belli olur. Kaydedilmemiş formu değil, kaynağı kaydedildiği haliyle test eder: Edit’te token’ı ya da dalı değiştirdikten sonra önce kaydedin, sonra test edin.

Bir subdirectory ayarlandığında, depodaki docs/guides/install.md dosyası api-docs/guides/install.md olarak indekslenir — subdirectory’nin kendisi yolda görünmez.

İç ağdaki bir git sunucusu

Repository URL’sini bir editör yazar ve sunucu ona bağlanır, bu yüzden bir git kaynağının nereye bağlanabileceği sınırlıdır. Kaynağın yaptığı her istek — Test’in okuduğu ref listesi, klon, her güncelleme ve her yönlendirme — bir Confluence kaynağıyla aynı adres kontrolünden geçer; kontrol, bağlantının gerçekte kullandığı adres üzerinde, DNS’ten sonra çalışır:

  • Her zaman reddedilir: loopback ve link-local adresleri (bulut metadata adresi 169.254.169.254 dahil), belirtilmemiş ve multicast adresleri, ve ayrılmış 240.0.0.0/4 bloğu. Hiçbir ayar bunları kaldırmaz. Bir IPv4 adresi taşıyan IPv6 adresi (IPv4-eşlenmiş, çevrilmiş, uyumlu ve NAT64 biçimleri) o IPv4 adresi gibi değerlendirilir.
  • İzin verilmedikçe reddedilir: özel adresler — 10.0.0.0/8, 172.16.0.0/12, 192.168.0.0/16, fc00::/7, kullanımdan kaldırılmış site-local fec0::/10, 100.64.0.0/10 ve 198.18.0.0/15.

En fazla 5 yönlendirme izlenir ve bir yönlendirme başka bir origin’e (şema, host ya da port) giderse erişim token’ı gönderilmez.

0.3.1’e yükseltme. 0.3.1’den önce bir git kaynağı her adresten klonlayabilirdi. İç bir adresteki git sunucusu — örneğin self-host bir Gitea — yükseltmeden sonra, host’u GIT_ALLOWED_HOSTS’ta listelenene kadar çalışmaz (virgülle ayrılmış host adları; şema, port ya da yol yok). Değer .env içinde ayarlanır ve instance yeniden başlatılır:

GIT_ALLOWED_HOSTS=git.corp.example

Bir ret, kuralı kaynağın satırında ve Test mesajında adlandırır, örneğin:

refused: `git.corp.example` resolves to a private address; list `git.corp.example` in GIT_ALLOWED_HOSTS to allow it

Bu durumda hiçbir istek gönderilmez, dolayısıyla hiçbir token çıkmaz. Liste yalnızca özel adres kuralını ve yalnızca git kaynakları için kaldırır; SOURCE_ALLOWED_HOSTS ve WEB_ALLOWED_HOSTS ayrı listelerdir ve burada bir host’u kabul ettirmez. Helm’de key config.gitAllowedHosts’tur (bkz. Kubernetes Üzerinde Çalıştırma).

Bir yanıt ne kadar büyük olabilir

Git istemcisinin okuduğu her yanıt gövdesi sınırlıdır; böylece beklenenden çok daha fazlasıyla yanıt veren bir remote instance’ın belleğini tüketemez. Sınır ref listesine ve klon ya da güncellemenin pack’ine ayrı ayrı uygulanır, bir sync’in tamamına birlikte uygulanmaz. Sınırı GIT_MAX_PACK_BYTES belirler; değer bayt cinsinden bir tam sayıdır:

  • Varsayılan: 268435456 (256 MiB). Kabul edilen en küçük değer 1048576’dır (1 MiB); daha küçük bir değer başlangıçta yapılandırma hatasıdır.
  • Bellek: git kütüphanesi pack’i bellekte tutar ve iki kez kopyalar; bu yüzden bir fetch, instance’ın zaten kullandığının üstüne sınırın yaklaşık iki katı bellek (varsayılanda kabaca 512 MiB) kullanabilir. Sınır yanıtı kısıtlar, belleği değil.
  • Aşılırsa: yanıt kesilir, sync hata verir ve kaynağın satırındaki hata ayarın adını anar:
git remote response is larger than GIT_MAX_PACK_BYTES (268435456 bytes); raise GIT_MAX_PACK_BYTES or point the source at a smaller repository

Büyük bir depo daha yüksek bir değer ister ve konteynerin memory limiti de onunla birlikte yükselmelidir: limiti yeni değerin iki katının ve instance’ın kendi kullanımının rahatça üstünde tutun; iki kat bir alt sınırdır, çünkü pack’in ayrıştırılması buna ekleme yapar. Değer .env içinde ayarlanır ve instance yeniden başlatılır:

GIT_MAX_PACK_BYTES=536870912

Helm’de key config.gitMaxPackBytes’tır; null bırakmak varsayılanı korur (bkz. Kubernetes Üzerinde Çalıştırma). 0.3.2 ile geldi.

Özel depolar

Access token alanına bir erişim token’ı yapıştırın. Saklanmadan önce SECRET_KEY (AES-256-GCM) ile şifrelenir, API tarafından asla döndürülmez ve bir daha gösterilmez — diyalog yalnızca bir token’ın var olduğunu söyler. Değiştirmek için yenisini yapıştırın; kaldırmak için Remove the stored token’ı işaretleyin.

Bir kaynak token saklayabilmeden önce SECRET_KEY ayarlanmış olmalı (32+ karakter, örn. openssl rand -hex 32). Bkz. Yapılandırma.

Token ile birlikte gönderilen kullanıcı adı sağlayıcıya bağlıdır ve URL’den tespit edilir:

Sağlayıcı Kullanılan kullanıcı adı Token türleri
GitHub x-access-token Classic PAT, fine-grained PAT, App installation token
GitLab oauth2 OAuth token’ları, personal ve project access token’ları
Bitbucket Cloud x-token-auth Repository ve workspace access token’ları
Bitbucket Cloud (API token) Bitbucket kullanıcı adınız, ya da x-bitbucket-api-token-auth Username alanına girin — varsayılan x-token-auth yalnızca repository/workspace access token’ları içindir
Gitea / Forgejo / Codeberg / diğer token, ya da Username’e ne yazdıysanız

Kimlik bilgilerini URL’nin kendisine (https://user:token@host/…) asla yapıştırmayın. Kimlik doğrulamada kullanılmazlar — token’ı yalnızca URL’de olan özel bir depo, hiç token verilmemiş bir depo gibi klonlanamaz. 0.3.1’den beri user:token@ kısmı URL saklanmadan önce silinir; kaynak görünümünden ve dışa aktarımlardan da çıkarılır, daha önce saklanmış satırları ise 0020 migration’ı temizler. Token’ı token alanına girin; yalnızca oradan okunur. Bir token bir URL’ye yapıştırıldıysa shell geçmişinde ya da bir log’da kalmış olabilir; iptal edip yenisini üretin.

Önerilen token kapsamları

Deponun içeriğine okuma erişimi yeterlidir — her sağlayıcının sunduğu en dar kimlik bilgisi:

Sağlayıcı En dar token Kullanıcı adı
GitHub Contents: read ile depoya sınırlı bir fine-grained PAT, ya da bir GitHub App installation token’ı boş bırakın (x-access-token)
GitLab read_repository kapsamlı bir proje deploy token’ı token’ın ürettiği kullanıcı adı, ör. gitlab+deploy-token-42 — varsayılan oauth2, bir deploy token için reddedilir
Bitbucket Cloud Repositories: read olan bir repository access token’ı boş bırakın (x-token-auth)
Gitea / Forgejo Depo üzerinde okuma kapsamlı bir access token kullanıcı adınız, ya da boş bırakın (token)

Bir GitHub wiki’si

Bir GitHub wiki’si kendi başına bir git deposudur, bu yüzden bir kaynak olabilir. Clone URL’si, deponunkine .wiki eklenmiş hâlidir:

https://github.com/YOUR-USERNAME/YOUR-REPOSITORY.wiki.git

Bunu Repository URL’ye koyun. GitHub wiki deposunu ilk sayfa oluşturulduğunda yaratır, bu yüzden o zamana kadar kaynağın okuyacak bir şeyi yoktur. Branch’i wiki deposunun varsayılan dalına ayarlayın — varsaymak yerine orada kontrol edin. Özel bir deponun wiki’sini yalnızca depoya erişimi olanlar görür, bu yüzden aynı Access token geçerlidir; herkese açık olanın buna ihtiyacı yoktur.

Yalnızca SSH üzerinden erişilebilen bir depoya ulaşmak

Git yalnızca HTTP(S) üzerinden okunur. SSH remote’ları (ssh://…, git@host:path) kabul edilmez ve hiçbir SSH anahtarı saklanamaz. Yalnızca SSH üzerinden erişilebilen bir depo için, onu kendiniz mirror’layın: ALLOWED_DOC_ROOTS içinde, host üzerinde onu klonlayın ya da mirror’layın, kendi takviminizde güncel tutun (bir git pull çalıştıran bir cron işi, ya da CI’nız), ve o dizini bunun yerine bir Yerel Klasör Kaynağı olarak ekleyin. O zaman diğerleri gibi salt bir klasördür — push webhook’u yok, branch ya da alt dizin ayarı yok, Test connection yok — ve tam olarak takviminizin onu tuttuğu kadar tazedir.

Senkronizasyon nasıl çalışır

Her indeksleme çalıştırmasının başında:

  1. Henüz bir checkout yoksa, klonlar: shallow (depth=1), tek dal, tag yok.
  2. Aksi hâlde dalın ucunu çeker. Hareket ettiyse, local dalı ona işaret ettirir ve checkout eder.
  3. Bir şey ters giderse, taze bir klona döner.
  4. Subdirectory’nin o dalda hâlâ var olduğunu doğrular.

O anda checkout edilmiş commit, kaynak satırında gösterilir (main @ a1b2c3d). Checkout’lar DATA_DIR altında yaşar, bu yüzden yeniden başlatmalara dayanır ve kaynakla birlikte silinir.

Push’ta otomatik yeniden indeksleme

Her git kaynağı kendi webhook URL’sini ve secret’ını alır, kaynağı düzenlerken gösterilir:

POST http://<your-host>/api/webhooks/git/<source-id>

Bunu depo ayarlarına o secret ile bir push webhook’u olarak ekleyin, ve dala her push, bir yeniden indekslemeyi kuyruğa alır. Alanların tam talimatları ve sağlayıcı başına ekran görüntüleri: Push Webhooks.

Yaygın sorunlar

Belirti Neden ve çözüm
Test’te, ya da bir senkronizasyondan sonra kaynağın satırında, bir token ayarlıyken The operation was canceled., hiçbiri yokken HTTP Error: 401 … Git host’u 401 yanıtladı: token eksik, reddedilmiş, süresi dolmuş, ya da okuma erişimi yok. Bir Bitbucket repository ya da workspace access token’ı için Username’i boş bırakın (varsayılan x-token-auth yalnızca bunlar içindir); bir Bitbucket Cloud API token’ı Bitbucket kullanıcı adınızı ya da x-bitbucket-api-token-auth’u, bir GitLab deploy token’ı ise onun ürettiği gitlab+deploy-token-N kullanıcı adını ister
Connected, but branch “…” was not found on the remote (Test’te) Dal adı yanlış, ya da varsayılan dal main değil master
Subdirectory “…” does not exist in the repository Yol, depo köküne görecelidir ve yapılandırdığınız dala karşı kontrol edilir
Başarısız bir senkronizasyondan sonra dokümanlar kayboldu Kaybolmazlar — okunamayan bir kaynak dokümanlarını korur. Nedeni düzeltin ve Sync’e basın
git remote response is larger than GIT_MAX_PACK_BYTES … Deponun pack’i yanıt sınırını aşıyor. GIT_MAX_PACK_BYTES’ı konteynerin memory limitiyle birlikte yükseltin — bkz. Bir yanıt ne kadar büyük olabilir
SSH URL reddedildi Yalnızca HTTP(S) desteklenir. Bir token ile HTTPS URL’yi kullanın

Notlar ve sınırlar

  • Kaynak başına yalnızca bir dal. İki dalı indekslemek için, farklı adlarla iki kaynak ekleyin.
  • Çok büyük depolar, native git ikili dosyasının klonlayacağından daha yavaş klonlanır; depth=1, tek bir dal ve bir subdirectory, dokümantasyon için bunu rahat tutar.
  • Submodule’ler çekilmez.
  • Depoya asla yazılmaz; Contextator yalnızca çeker.

Gezinmek için ok tuşları, açmak için Enter.