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 HTTPS — 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 |
Kaydetmeden önce 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 hemen belli olur.
Bir subdirectory ayarlandığında, depodaki docs/guides/install.md dosyası
api-docs/guides/install.md olarak indekslenir — subdirectory’nin kendisi yolda görünmez.
Ö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 |
URL’nin kendisine yapıştırılan kimlik bilgileri (https://user:token@host/…) URL saklanmadan önce
temizlenir — bunun yerine token alanını kullanın.
Ö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) |
Yalnızca SSH üzerinden erişilebilen bir depoya ulaşmak
Git yalnızca HTTPS üzerinden okunur. SSH remote’ları (ssh://…, git@host:path) kabul edilmez ve
hiçbir SSH anahtarı saklanamaz (ADR-0086). 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 connection’da Authentication failed | Token eksik, 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 |
| Branch “…” was not found on the remote | 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 |
| SSH URL reddedildi | Yalnızca HTTPS 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.