npm stage-only belirteci: Dağıtım otomasyonu ile nihai onayı ayırırken bırakılması gereken kanıtlar
CI'ın bir paket oluşturma yetkisi ile bu paketi kullanıcılara yayınlama yetkisini birbirinden ayırmak, sürümün nihai sorumluluğunu daha net hale getirir. Ancak tek bir onay düğmesi eklemek, tedarik zinciri risklerini ortadan kaldırmaz. İşe, onaylayıcının tam olarak neyi kontrol edeceğini belirleyerek başlamak gerekir.
GitHub, 18 Eylül'de npm ayrıntılı erişim belirteçlerinde (granular access token) stage-only yazma izninin seçilebileceğini duyurdu. Bu akışta otomasyon, sürümü inceleme bekleyen durumda gönderir ve bakımcı 2FA ile yayınlamayı onaylar. Aşağıda, resmi değişiklikler ile bunları operasyona dahil etmeye yönelik editör önerileri birbirinden ayrılarak açıklanmıştır.
Doğrudan yayınlamayı engellemek ile yazma iznini kaldırmak farklıdır
Resmi duyuruya göre, bu belirteçle npm stage publish çalıştırılabilir ancak npm publish aracılığıyla doğrudan yayınlama reddedilir. Otomasyon için 2FA atlama yapılandırması olsa bile bu kısıtlama geçerlidir. Bu özellik, mevcut belirteçlerin davranışını otomatik olarak değiştiren bir yenilik değildir; isteğe bağlı olarak devreye alınır.
Dikkat edilmesi gereken nokta, dist-tag taşıma ve sürüm kullanımdan kaldırma (deprecation) gibi diğer paket yazma izinlerinin devam etmesidir. stage-only adı, salt okunur veya tamamen zararsız bir belirteç olarak yorumlanmamalıdır. İzin verilen paket kapsamı, gizli anahtarın saklandığı konum, belirteci kullanan aktörler ve iptal süreçleri yine de yönetilmelidir.
Onaylayıcının karşılaştıracağı sürüm paketini belirleyin
Aşağıdaki içerik, npm'in zorunlu bir yapılandırması olmayıp küçük ekipler için operasyonel bir öneridir. Tek bir onay talebine kaynak commit'i, hedef paketi ve sürümü, test sonuçlarını, pakete dahil edilecek dosyaların listesini ve değişiklik özetini ekleyin. Onaylayıcının kanıtları CI günlüklerinin farklı yerlerinden toplaması gerekiyorsa inceleme süreci yüzeysel bir tıklamaya dönüşebilir.
Özellikle kaynak kod incelemesi ile dağıtılan dosyaların incelemesi birbirinden ayrı konulardır. Depoda bulunmayan bir dosya derleme sürecinde pakete dahil edilebilir veya gerekli bir dosya dışarıda kalabilir. Ekipler, inceleme materyallerini fiilen gönderilen çıktıyı temel alarak oluşturma ve incelemeden sonra çıktı değiştirildiyse bunu yeni bir inceleme konusu olarak ele alma ilkesini benimseyebilir.
Başarılı (yeşil) CI'dan sonra bile bir bekleme durumu vardır
Mevcut otomasyon komutun başarılı olmasını sürümün tamamlandığı şeklinde bildiriyorsa öncelikle durum ifadelerini değiştirmek gerekir. Gönderim tamamlandı, onay bekliyor ve yayınlama tamamlandı şeklinde aşamaları ayırmak ve her birinin doğrulama dayanağını kaydetmek gerekir. Bildirimlerde sadece "başarılı" demek yerine mevcut aşamayı ve sorumlu kişiyi belirtmek operatörler için daha yararlıdır.
Örnek bir senaryoda, gece çalışan CI yeni bir sürüm gönderir ancak yetkili bunu ertesi gün incelerse gönderim anında kullanıcılara yönelik sürüm duyurusu yapılmamalıdır. Dokümantasyonu veya duyuruları, ekibin belirlediği yayınlama doğrulamasından sonra devreye girecek şekilde bağlayın. Kuyruk biriktiğinde kimin inceleme yapacağı ve önceki gönderimlerin ne zaman temizleneceği konusunda da önceden anlaşılmalıdır.
Geçişi tek bir küçük paketle doğrulayın
Mevcut resmi kılavuzdaki başlangıç gereksinimleri arasında var olan bir npm paketi, paket yayınlama yetkisi, hesap 2FA'sı, npm CLI 11.15.0 veya üzeri ile Node.js 22.14.0 veya üzeri yer almaktadır. Fiili geçişten önce en güncel dokümantasyon tekrar kontrol edilmeli ve kullanılan runner sürümleri gözden geçirilmelidir.
Öncelikle etkisi düşük tek bir pakette belirteç kapsamını sınırlandırmanızı; staging gönderimi, bakımcı incelemesi ve yayınlama sonucunun doğrulanmasına kadar olan süreci denemenizi öneririz. Bir hata durumunda hemen geniş yetkili eski belirtece geçilmesini sağlarsanız oluşturulan sınırlar anlamsız hale gelir. Onay gecikmeleri de normal bir durum olarak ele alınabilmelidir.
trusted publishing ile karşılaştırılacak sorular
npm, OIDC kullanan trusted publishing seçeneğini de sunmaktadır. Öncelikle desteklenen CI ortamlarına ve ekibin onay yöntemine uygun olup olmadığını değerlendirmek gerekir; stage-only belirteçlerini tüm ekipler için nihai çözüm olarak genellemeye gerek yoktur. Belirteç kullanmaya devam etmek zorunda olan bir otomasyonsa bunu kademeli bir geçiş seçeneği olarak değerlendirebilirsiniz.
Resmi duyuru, bypass-2FA belirteçlerinin doğrudan yayınlama yetkisinin kaldırılması için hedef tarihi Ocak 2027 olarak belirtmektedir. Kesinleşmiş tüm uygulama ayrıntılarını tahmin etmeye çalışmaktansa etkilenen iş akışlarının listesini ve geçişten sorumlu kişileri şimdiden belirlemek daha pratiktir. Takvim değişiklikleri için ilerleyen süreçteki resmi duyurular takip edilmelidir.
Geçiş kararı verirken
Bu yazı, topluluk genelinde varılmış geniş bir mutabakatı veya gerçek kaza azalma oranlarını iddia etmemektedir; yeni özelliğin resmi işleyişini temel alarak denetlenebilir bir operasyonel süreç önermektedir. Otomasyonun üstleneceği görevler ile insanların doğrulayacağı adımların net şekilde açıklanabilmesi, geçiş kararının başlangıç noktasıdır.
Bugün yapabileceğiniz şeyler; mevcut sürüm belirteçlerinin nerede kullanıldığını tespit etmek, yayınlamanın tamamlandığını belirleyen koşulları yazmak ve tek bir onay için gereken kanıtları tanımlamaktır. Yetki kısıtlaması ile inceleme kalitesi birlikte ele alındığında staging adımı gerçekten fayda sağlayacaktır.