AI CodeOps

Hata durumunda açık mı, kapalı mı: kalite kapıları hataları nasıl ele almalı

Son güncelleme

CI ve yayın kapıları için hata durumunda açık ve kapalı kalmanın anlamı, hatada geçiş veren bir kapının neden en gerekli anda kapalı olduğu ve takılmadan nasıl kapalı kalınacağı.

Bir hata değişikliğin geçmesine izin verdiğinde kapı hata durumunda açık kalır (fail open), bir hata değişikliği durdurduğunda ise hata durumunda kapalı kalır (fail closed). Kalite kapıları hata durumunda kapalı kalmalıdır: test çalıştırıcısı çökerse, inceleme zaman aşımına uğrarsa, kanıt eksikse veya kapı servisine ulaşılamazsa, gerçek bir karar oluşana kadar değişiklik reddedilir. Hata durumunda açık kalan bir kapı normal günlerde sorunsuz görünür ve bir şeylerin yanlış olduğu günlerde, yani var olma nedeni olan günlerde, sessizce kapanır.

Bu sayfa, Kalite kapıları nedir? rehberindeki bir özelliği genişletir.

Terimler nereden gelir

Terimler, bir tasarımcının bir cihazın güç veya denetim kaybında hangi duruma geçeceğine karar verdiği fiziksel sistemlerden gelir. Bir vana açık veya kapalı konumda kalabilir; elektrikli bir kapı kilidi, insanlar yanan bir binadan çıkabilsin diye açık veya bir kasa kapalı kalsın diye kilitli konumda kalabilir. Genel olarak hiçbiri doğru değildir. Seçim, hangi başarısızlığın daha kötü olduğuna bağlıdır.

Bir kalite kapısı için karşılaştırma, geciken bir merge ile canlı ortama ulaşan kontrol edilmemiş bir değişiklik arasındadır. Neredeyse her durumda gecikme daha küçük maliyettir; bu yüzden kapılar hata durumunda kapalı kalır.

Kapılar nasıl hata durumunda açık kalır hâle gelir

Çok az ekip hata durumunda geçiş veren bir kapı kurmaya karar verir. Bu, küçük ve makul görünen tercihlerle olur:

  • Hataların geçmesine izin verilmesi. Kararsız bir araç build'leri engellemeyi bıraksın diye "continue on error" veya "allow failure" olarak işaretlenen bir CI adımı. Araç sonra gerçekten başarısız olur ve hiçbir şey fark etmez.
  • Çıkış kodlarını gizleyen shell script'leri. Ardından || true gelen bir komut veya çıkış durumu başarısız olan komuttan değil son komuttan gelen bir pipeline.
  • Nötr sayılan zaman aşımları. Zaman aşımına uğrayan bir güvenlik taraması "neutral" veya "skipped" olarak raporlanır ve branch koruması onu zorunlu tutmaz.
  • Başarılı sayılan atlanmış işler. Bazı CI sistemlerinde bir koşul nedeniyle atlanan bir iş başarılı bildirir. Bu durumda zorunlu bir kontrol çalışmadan geçebilir.
  • Temiz okunan boş çıktı. Çöken bir inceleme aracı hiçbir bulgu dosyası yazmaz. Kapı "sıfır bulgu" okur ve geçer.
  • Yok sayılan ayrıştırılamayan yanıtlar. Bir yapay zekâ inceleyicisi kapının beklediği yapılandırılmış sonuç yerine düzyazı döndürür ve kapı bulguların yokluğunu onay olarak ele alır.
  • Yok sayılan HTTP hataları. Bir CI adımı bir kapı servisini çağırır, 500 veya zaman aşımı alır ve yalnızca yanıt açıkça "denied" diyorsa başarısız olur.

Bunların her biri "kontrol edemedik" ifadesini "kontrol ettik ve sorun yok" ifadesine dönüştürür.

Eksik kanıt bir varsayılan değil, bir karardır

Bazı kanıtların bulunmaması meşrudur. Yalnızca dokümantasyondan oluşan bir projenin testi olmayabilir. Yeni bir servisin henüz bir SBOM'u olmayabilir. Bir test komutu kapsam yazdırmayabilir.

Kural, her eksik girdinin engellemesi gerektiği değildir. Her durumun bilinçli olarak kararlaştırılması, yazılması ve görünür olmasıdır:

Eksik kanıtSeçenekler
Test çalıştırması yokEngelleyin; veya izin verin ama onaylayıcıya "doğrulanmadı" gösterin
İnceleme sonucu yokEngelleyin. Tamamlanmamış bir inceleme temiz bir inceleme değildir
Bir lisans kuralı için SBOM yokEngelleyin, çünkü kural kontrol edilemez
Kapsam değeri yokBir alt sınır zorunluysa engelleyin; veya alt sınırı atlayın ve atlandığını gösterin
Kapı servisine ulaşılamıyorEngelleyin ve yeniden deneyin

Ne seçerseniz seçin, eksik bir sonuç asla yeşil bir onay işareti olarak gösterilmemelidir. "Kontrol edilmedi" ile "geçti", onaylayan kişiye farklı görünmelidir.

Hata durumunda kapalı kalmanın maliyeti ve nasıl yönetileceği

Hata durumunda kapalı kalmanın gerçek bir maliyeti vardır: kapının bağımlı olduğu bir şey çalışmadığında hiçbir şey yayına çıkmaz. Bu maliyeti göz ardı eden ekipler ilk kesintiye kapıyı kapatarak tepki verme eğilimindedir. Bunun yerine buna göre plan yapın.

  • Başarısız saymadan önce yeniden deneyin. Geçici ağ hataları ve istek limitleri, kapı bir başarısızlık bildirmeden önce geri çekilme (backoff) ile birkaç kez yeniden denenmelidir.
  • Neyin başarısız olduğunu söyleyin. "Release check unavailable" ile "release denied: high-severity finding" farklı sahipleri olan farklı sorunlardır. İkisi de engeller; mesaj insanlara ne yapacaklarını söyler.
  • Bir acil durum yolu tutun. Gerçek acil durumlar için yetkili bir kişi, kaydedilen bir gerekçeyle tek bir değişiklik için kapıyı geçersiz kılabilir. Geçersiz kılma nadir ve görünürdür ve kapı açık kalır.
  • Kapının kendisini izleyin. Kapının ne sıklıkla reddettiğini olduğu kadar ne sıklıkla hata verdiğini de takip edin. Sık hata veren bir kapı atlanır.

Hata durumunda kapalı kalan bir kapı tasarlamak

  1. Retten başlayın. Kapının varsayılan yanıtı hayırdır. Yalnızca gereken her kanıt mevcut ve kabul edilebilir olduğunda evet döndürür.
  2. Hataları ret olarak ele alın. İstisnalar, zaman aşımları ve hatalı biçimlendirilmiş girdilerin tümü gerekçeli bir ret üretir; asla bir onay ve asla "neutral" değil.
  3. Sıkı ayrıştırın. Bir aracın çıktısı okunamıyorsa araç başarılı olmamıştır.
  4. Kanıtı sürüme bağlayın. Önceki bir commit için verilmiş bir test sonucu veya onay güncel commit için sayılmaz.
  5. Her yolun kapıdan geçmesini sağlayın. Git platformundaki merge'ler, konsol merge'lerinin uyduğu bir kapıyı atlıyorsa, kapı başka bir yoldan hata durumunda açık kalıyordur.
  6. Çağıranın da hata durumunda kapalı kalmasını sağlayın. Kapıyı çağıran bir CI adımı, çağrı başarısız olduğunda başarısız olmalıdır.

Son nokta kolayca gözden kaçar. Aşağıda, bir yayın kapısını HTTP üzerinden çağırırken hata durumunda kapalı kalan bir CI adımı var: her ağ hatası, başarılı olmayan durum kodu veya okunamayan yanıt işi başarısız kılar; açık bir izin dışındaki her yanıt da öyle.

response=$(curl -sf --max-time 30 -X POST "https://<your-console>/api/release/check" \
  -H "Authorization: Bearer $WORKSPACE_API_KEY" \
  -H "Content-Type: application/json" \
  -d "{\"pullRequestURL\":\"$PR_URL\"}") || { echo "Release check unavailable: failing closed"; exit 1; }
[ "$(echo "$response" | jq -r '.allowed')" = "true" ] || { echo "$response" | jq -r '.reasons[]?'; exit 1; }

AI CodeOps bunu nasıl yapar

AI CodeOps kapıları, belgelenmiş birkaç istisna dışında hata durumunda kapalı kalacak şekilde kurulmuştur.

  • Yapay zekâ bulgu incelemesi başarısız olursa, zaman aşımına uğrarsa, bütçesi tükenirse veya okunamayan bir şey döndürürse değişiklik bekletilir ve oturum sayfası bunlardan hangisinin olduğunu söyler: bulguları bilinmediği için temiz bir inceleme sayılmaz.
  • Bir pull request açılmak veya konsoldan merge edilmek üzereyken kapı kontrolü çalışamazsa pull request açılmaz ve merge gerçekleşmez: "The release check couldn't run just now."
  • CI yayın kontrolü, değerlendirme hata verirse "Evaluation failed" özetiyle allowed: false döndürür ve eşleşen oturumu olmayan bir değişikliği reddeder.
  • Kodu değiştiren bir oturumun sayılar içeren bir test sonucuna ihtiyacı vardır. Hiç test çalışmadıysa veya test komutu çalışıp hiçbir test sayısı bildirmediyse değişiklik engellenir: "The test command ran but reported no test counts, so nothing shows a test passed. Check the project's test command".
  • disallowedLicenses ayarlıyken SBOM'u olmayan bir proje reddedilir, çünkü lisansları kontrol edilemez.
  • minCoveragePct ayarlıyken test çalıştırmaları kapsam bildirmeyen bir değişiklik reddedilir, çünkü alt sınır kontrol edilemez: "Coverage wasn't reported, so the 80% floor can't be checked".
  • Bir oturum başlarken bütçe kontrolü başarısız olursa oturum ölçümsüz çalıştırılmak yerine engellenir.

İstisnalar bilinçlidir ve gizlenmek yerine gösterilir. Test paketi olmayan bir proje, ayarlarında Don't run tests for this project seçeneğini açabilir. Yayın kapısı bu durumda o projeden test sonucu istemez ve çalıştırma sayfası değişikliğin doğrulanmadığını gösterir. Ayrıca çalışan bir oturum sırasında bütçe kontrolü başarısız olursa oturum çalışmaya devam eder.

Uç nokta hem izin hem ret için HTTP 200 döndürür; bu yüzden allowed değerini okuyun. Bir çalışma alanı için dakikada 60 kontrolün üzerinde 429 yanıtı verir; hata durumunda kapalı kalan bir CI adımı bunu yeniden denemeli ve ardından başarısız olmalıdır. Kapının neyi kontrol ettiği için Kalite kapıları, her alan için API referansı ve genel bakış için Yapay zekâ kod kalite kapıları sayfasına bakın.

Sık sorulan sorular

Bir kalite kapısı için hata durumunda kapalı kalmak ne anlama gelir?

Bir araç çöktüğü, bir servis zaman aşımına uğradığı veya kanıt eksik olduğu için kapı bir karara varamadığında, değişikliği geçirmek yerine reddeder. Karar yokluğu bir başarısızlık olarak ele alınır.

Hata durumunda kapalı kalmak kesintiler sırasında yayınları engellemez mi?

Engelleyebilir; bu yüzden hata durumunda kapalı kalan bir kapı, yeniden denemelere, net hata mesajlarına ve gerçek acil durumlar için kaydedilen bir geçersiz kılmaya ihtiyaç duyar. Kısa bir gecikme, canlı ortamdaki kontrol edilmemiş bir değişiklikten genellikle daha ucuzdur.

Atlanan bir kontrol geçmiş sayılır mı?

Sayılmamalı. Bazı CI sistemlerinde bir koşul nedeniyle atlanan bir iş başarılı bildirir; bu yüzden zorunlu bir kontrol hiç çalışmadan yeşil görünebilir. Her kontrol için atlanmaya izin verilip verilmediğine karar verin ve kapının farkı ayırt etmesini sağlayın.

Acil bir durumda hata durumunda kapalı kalan bir kapıyı nasıl geçersiz kılarım?

Kontrolü kapatarak değil, yetkili bir kişinin gerekçeyle verdiği, açık ve kaydedilen bir kararla. Geçersiz kılma tek bir değişikliğe uygulanmalı ve kapıyı bir sonraki için yerinde bırakmalıdır.