Markdown Formatındaki Altyapı Notları ve Ağ Topolojilerini GitHub Actions CI/CD ile Otomatik Derleyip Dahili Portala Basma

Geleneksel şirketlerde Bilgi İşlem departmanının altyapı dokümantasyonu genellikle şöyledir: Masaüstünde duran Yeni_Ag_Semasi_v2_son.docx, network switch şifrelerinin yazılı olduğu sarı bir defter ve kimsenin güncellemediği bir Excel tablosu. Yeni bir mühendis işe başladığında sistemleri öğrenmesi aylar sürer; bir kriz çıktığında ise güncel topoloji bulunamaz. Dokümantasyonu yazılım geliştirme disipliniyle ele alan Docs-as-Code yaklaşımı ve GitHub Actions CI/CD hattı ile bu süreci nasıl otomatize ettiğimin hikayesi.

1. Docs-as-Code Felsefesi Nedir?

• Dokümantasyon kapalı Word dosyalarında değil; hafif, sade ve versiyonlanabilir Markdown (.md) formatında yazılır.
• Kodlar gibi özel bir Git Reposunda (GitHub / GitLab) saklanır.
• Bir sistem mühendisi altyapıda değişiklik yaptığında (örneğin yeni bir VLAN eklediğinde), yerel VS Code editöründe markdown dosyasını günceller ve git push der.
• Arka planda GitHub Actions devreye girer; markdown dosyalarını derler ve şirketin dahili teknik wiki portalına saniyeler içinde basar!

2. GitHub Actions İş Akışı (.github/workflows/deploy-docs.yml)

Aşağıdaki CI/CD boru hattı, repoya her commit atıldığında statik site üreteciyle (MkDocs / Next.js) dokümanları derler ve şirket içi web sunucusuna SCP/Rsync ile fırlatır:

name: Altyapi Dokumantasyonu CI/CD

on:
  push:
    branches:
      - main

jobs:
  build-and-deploy:
    runs-on: ubuntu-latest
    steps:
      - name: 1. Repoyu Klonla
        uses: actions/checkout@v3

      - name: 2. Python ve MkDocs Ortamını Hazırla
        uses: actions/setup-python@v4
        with:
          python-version: '3.10'

      - name: 3. Bağımlılıkları Kur ve Siteyi Derle
        run: |
          pip install mkdocs-material
          mkdocs build --clean

      - name: 4. Dahili Bilgi İşlem Portalı Sunucusuna Dağıt (SCP)
        uses: appleboy/scp-action@master
        with:
          host: "portal.holding.local"
          username: "deployer"
          key: ${{ secrets.SSH_PRIVATE_KEY }}
          source: "site/*"
          target: "/var/www/internal-infra-docs"
          strip_components: 1

3. Mermaid.js ile Kod Tabanlı Ağ Diyagramları

Görsel çizim araçlarıyla (Visio) uğraşmak yerine ağ topolojilerini markdown içinde doğrudan metin olarak çiziyoruz:

```mermaid
graph TD
    Firewall[Sophos XGS 2300 HA] --> CoreSwitch[Cisco Catalyst 3850 Core]
    CoreSwitch --> Vlan10[VLAN 10: Sunucular]
    CoreSwitch --> Vlan20[VLAN 20: Kullanıcılar]
    CoreSwitch --> Vlan30[VLAN 30: Wi-Fi]
    Vlan10 --> ESXi[VMware vSphere 8 Cluster]

Git üzerinden bir switch IP'si değiştiğinde tek satırlık metin düzenlenir; diyagram otomatik olarak web sayfasında güncellenir!

## Karşılaşılan Kritik Hatalar ve Çözüm İpuçları

- **Hassas Şifrelerin Repoya Kazara Push Edilmesi (Secret Leaks):** Sistem şifreleri asla markdown dokümanlarına yazılmamalıdır! GitHub pre-commit hook'ları (`git-secrets` veya `trufflehog`) kurularak parola veya API token içeren commit'lerin repoya girmesi engellenmelidir. Şifreler parola kasasında (Vaultwarden/Bitwarden) saklanır, dokümanda yalnızca kasanın referans linki verilir.

## Mühendis Notu
Bir kurumun en değerli sermayesi sistem mühendisinin kafasındaki bilgi değil; şirketin yaşayan kurumsal hafızasıdır. Dokümantasyonu kod gibi versiyonlamak, ekibinizi kişilere bağımlı olmaktan kurtarır ve gerçek bir kurumsal mühendislik kültürü inşa eder.