GitHub Actions Kod İmzalama

GitHub Actions ile derlenen bir Windows uygulamasını imzalamak, yayın hattını tamamen otomatik hale getirir; ancak kod imzalama sertifikasının özel anahtarını nerede tuttuğunuz işin en kritik kısmıdır. Güncel CA/B Forum kurallarına göre yeni düzenlenen kod imzalama anahtarları donanım tabanlı (token veya HSM) korunmak zorundadır, dolayısıyla eski alışkanlık olan "PFX dosyasını repository secret olarak saklamak" artık yeni sertifikalarda çalışmaz.

Anahtar nerede duracak?

• Self-hosted runner: Sertifikanın USB token'ı veya akıllı kartı bir imzalama makinesine takılır, o makine runner olarak kaydedilir. İş akışı yalnızca bu runner'da çalışır.
• Bulut HSM: Bulut tabanlı kod imzalama seçeneğinde USB token ve kargo gerekmez; anahtar bulut HSM'de kalır ve imzalama uzaktan yapılır. Hangi imzalama istemcisinin CI ortamında kullanılacağı sağlayıcının dokümantasyonuna bağlıdır.

Örnek iş akışı

Aşağıdaki örnek, sertifikanın imzalama makinesinin Windows mağazasında kurulu olduğunu varsayar ve parmak izi ile imzalar:

name: release
on:
  push:
    tags: ['v*']
jobs:
  build-sign:
    runs-on: [self-hosted, windows, signing]
    steps:
      - uses: actions/checkout@v4
      - name: Build
        run: dotnet publish -c Release -o out
      - name: Sign
        env:
          CERT_SHA1: ${{ secrets.CODESIGN_THUMBPRINT }}
        run: |
          signtool sign /sha1 $env:CERT_SHA1 /fd SHA256 `
            /tr http://time.certum.pl /td SHA256 out\app.exe
      - name: Verify
        run: signtool verify /pa /v out\app.exe

Burada secret olarak yalnızca sertifika parmak izi tutulur; özel anahtar runner'dan çıkmaz. Zaman damgası sunucusu, sertifika sağlayıcınızın önerdiği adres olmalıdır.

Dikkat edilecekler

• Fork'lardan gelen pull request'lerin imzalama runner'ını tetiklememesi için iş akışını yalnızca etiket veya korumalı dal ile çalıştırın.
• İmzalama işini ayrı bir environment altına alıp onay (required reviewers) ekleyin.
• Her imzadan sonra signtool verify /pa ile doğrulayın.
• OV ve EV farkı ile SmartScreen itibarı için kod imzalama sertifikaları sayfasına bakabilirsiniz.

Özetle: anahtarı hattın dışında koruyun, iş akışına yalnızca imzalama yetkisi verin ve her sürümde zaman damgası ekleyin.

Yaygın tuzaklar

Windows runner'ında signtool yolunun PATH'te olmaması sık görülen hatadır; Windows SDK'nın bin dizinini iş akışında açıkça belirtin. Ayrıca imzalama sırasında zaman damgası sunucusuna erişilemezse adım başarısız olur; bu durumda ikinci bir zaman damgası adresiyle yeniden deneme eklemek işe yarar. Günlüklerde parmak izi ve PIN değerlerinin görünmediğinden emin olun.

• Yayın öncesi dosyayı temiz bir makinede indirip imzayı doğrulayın.
• Sertifika yenilendiğinde secret'taki parmak izini güncelleyin.