# 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: 2026-10-30
- Kaynak: https://contextator.com/tr/docs/git-repository-source/
- Dil: tr-TR
- Yazar: Muhammet Şafak

---
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](/tr/docs/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](/tr/docs/kubernetes/)).

## 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](/tr/docs/kubernetes/)). 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](/tr/docs/configuration/).

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ğı](/tr/docs/local-directory-source/) 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](/tr/docs/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](#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.
