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.254dahil), belirtilmemiş ve multicast adresleri, ve ayrılmış240.0.0.0/4bloğ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-localfec0::/10,100.64.0.0/10ve198.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ğer1048576’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_KEYayarlanmış 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:
- Henüz bir checkout yoksa, klonlar: shallow (
depth=1), tek dal, tag yok. - Aksi hâlde dalın ucunu çeker. Hareket ettiyse, local dalı ona işaret ettirir ve checkout eder.
- Bir şey ters giderse, taze bir klona döner.
- 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
gitikili 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.