GitHub Actions'ta yeniden kullanılabilir iş akışları yazma rehberi

Yeniden kullanılabilir iş akışı nedir, ne zaman gerekir?

Bir ekipte onlarca depo varsa ve her birinde aynı derleme, test ve dağıtım adımları kopyalanmışsa, bir değişiklik her depoda elle yapılmak zorunda kalır. Yeniden kullanılabilir iş akışı (reusable workflow) bu tekrarı ortadan kaldırır: ortak adımlar tek bir workflow dosyasında yazılır, diğer workflow'lar onu çağırır.

Bu yapı özellikle şu durumlarda işe yarar: aynı yapı ve test süreci birden fazla depoda kullanılıyorsa, kurumsal bir standart (güvenlik taraması, imaj yayınlama kuralları) tek yerden yönetilmek isteniyorsa ya da bir iş akışı çok uzayıp okunmaz hale geliyorsa. Tek depoda, tek seferlik bir işlem için ayrı bir reusable workflow yazmak ise gereksiz karmaşıklık getirir.

Reusable workflow nasıl tanımlanır?

Çağrılabilir bir workflow, tetikleyici olarak workflow_call kullanır (on anahtarının altında). Dosya, deponun .github/workflows klasöründe bulunmalıdır; alt klasörler desteklenmez. Girdiler on.workflow_call.inputs altında tanımlanır; her girdi için gerekli olup olmadığı (required) ve türü (string, number ya da boolean) belirtilir. Gizli bilgiler on.workflow_call.secrets altında tanımlanır.

Çıktılar on.workflow_call.outputs altında açıklama ve değerle tanımlanır. Değer, çağrılan workflow'daki bir iş çıktısına (job output) bağlanmalıdır; adım çıktısı doğrudan verilemez, önce iş çıktısına eşlenir. Çağrılan workflow içinde girdilere inputs bağlamıyla, gizli bilgilere secrets bağlamıyla erişilir.

Örneğin bir uygulama için ortak bir 'derle ve test et' workflow'u, Node sürümünü ve çalışma klasörünü girdi olarak alıp, üretilen paket adını çıktı olarak verebilir. Böylece her depo yalnızca farklı olan değerleri geçer.

Başka bir workflow'dan nasıl çağrılır?

Çağıran workflow'da bir iş (job), steps yerine uses anahtarıyla tanımlanır. Bu en önemli ayrımdır: reusable workflow iş düzeyinde çağrılır, adım düzeyinde değil. uses değeri farklı biçimlerde yazılabilir: aynı depodaki dosya için yol, başka bir depodaki dosya için sahip, depo, dosya yolu ve ref (dal, etiket ya da commit) ya da aynı depodaki aynı commit için ilgili biçim.

Girdiler with altında, gizli bilgiler secrets altında geçirilir. Aynı kuruluş ya da kurumsal hesaptaki workflow'lar için secrets: inherit yazarak çağıranın tüm gizli bilgilerini aktarabilirsiniz. Çıktılar çağıran tarafta needs bağlamıyla okunur: needs, iş adı, outputs ve çıktı adı biçiminde.

Başka bir depodaki workflow'u çağırırken ref olarak değişmez bir etiket ya da commit kullanmak, ortak workflow'daki beklenmedik bir değişikliğin tüm depoları bozmasını önler.

Composite action ile farkı nedir?

Bu yapılar tekrarı azaltır ama farklı düzeylerde çalışır. Reusable workflow, tam bir workflow'dur: kendi işlerini (jobs), çalıştırıcılarını (runner), ortamlarını ve gizli bilgilerini tanımlar; bir çağıran işin yerini alır. Composite action ise bir iş içindeki adım grubunu paketler; çağıran işin çalıştırıcısında, o işin bir adımı olarak çalışır.

Pratik kural: birden çok işi, farklı çalıştırıcıları ya da ortam ve onay kapılarını içeren bir süreç gerekiyorsa reusable workflow tercih edilir. Aynı işin içinde tekrar eden birkaç adımı (örneğin ortamı kurmak, önbelleği ayarlamak, bir betik çalıştırmak) paketlemek içinse composite action daha hafiftir. Bu ikisi birlikte de kullanılabilir: reusable workflow içindeki işler composite action'ları adım olarak çağırabilir.

Sorumluluk ayrımı da farklıdır: composite action kendi başına gizli bilgi almaz, girdi olarak ister; reusable workflow ise secrets tanımı taşır.

Sürümleme, güvenlik ve sınırlar

Ortak workflow'lar organizasyonun altyapısıdır; bu yüzden sürümlenmelidir. Ana dalı doğrudan çağırmak yerine etiket kullanın ve değişiklikleri sürüm notlarıyla yayımlayın. Kırıcı değişiklik yaparken yeni bir ana sürüm etiketi açın, depoların kendi hızında geçmesine izin verin.

Gizli bilgiler yalnızca doğrudan çağrılan workflow'a geçer; zincirde daha aşağıdaki bir workflow'a aktarım için açıkça yeniden tanımlama gerekir. Çağrılabilir workflow zincirinin de derinlik sınırı vardır; ayrıntılı sınırlar için güncel resmi dokümantasyona bakın. Ortak workflow'lara en az yetkiyle (permissions) çalışacak şekilde izin tanımlayın ve harici action'ları sürüme sabitleyin.

Görünürlük de önemlidir: başka bir depodaki workflow'un çağrılabilmesi, deponun erişim ayarlarına bağlıdır. Özel depolarda ortak workflow'a erişim izni açıkça verilmelidir.

Örnek senaryo: ortak derleme ve test akışı

Örneğin bir şirkette birçok servis aynı dilde yazılmış ve hepsi aynı adımları izliyor: kodu al, bağımlılıkları kur, önbellekten yükle, test et, güvenlik taraması yap. Bu akışı tek bir platform deposunda reusable workflow olarak yazarsınız. Girdiler çalışma klasörü ve dil sürümü; çıktı, test raporunun yolu olabilir.

Her servis deposunda yalnızca kısa bir workflow dosyası kalır: tetikleyici olarak pull request ve ana dala gönderim, tek bir iş ve o işin uses ile platform deposundaki akışı çağırması. Güvenlik taramasına yeni bir kural eklemek gerektiğinde değişiklik yalnızca platform deposunda yapılır, tüm servisler sonraki çalıştırmada yeni kuralı kullanır.

Bu yaklaşım hem tutarlılığı hem de denetlenebilirliği artırır: hangi servislerin hangi sürümü kullandığı sürüm etiketlerinden izlenir.

Sık yapılan hatalar

• Reusable workflow'u adım içinde çağırmaya çalışmak. Çağrı iş düzeyinde, uses ile yapılır.
• Çıktıyı doğrudan adımdan vermek. Adım çıktısı önce iş çıktısına eşlenmelidir.
• Ortak workflow'u ana dal üzerinden çağırıp sürüm etiketi kullanmamak.
• Gerekli gizli bilgiyi secrets altında tanımlamamak ya da aktarmamak.
• Her küçük adım için reusable workflow yazıp yapıyı gereksiz karmaşıklaştırmak; küçük tekrarlar için composite action yeterlidir.
• Hata ayıklamayı unutmak: çağrılan workflow'un günlüğü çağıranın çalıştırma ekranında iç içe görünür; girdi değerlerini günlüğe yazarak sorunu izleyin.

Bu beceriyi Mindset programlarında nerede çalışırsınız?

CI/CD Pipeline Tasarımı (GitHub Actions) eğitiminin modül başlıkları arasında GitHub Actions Temelleri, Sürekli Entegrasyon Boru Hattı, Konteyner ve Image Yönetimi, Çok Ortamlı Deployment Stratejileri, Yeniden Kullanılabilir İş Akışları, Güvenlik ve Uyumluluk Entegrasyonu ile Gözlemlenebilirlik ve Optimizasyon yer alır. Bu sayfadaki konu doğrudan Yeniden Kullanılabilir İş Akışları modülüne denk gelir.

Eğitim, aynı derleme ve dağıtım adımlarını depo depo kopyalayan yazılım geliştiricilere ve DevOps mühendislerine yöneliktir. Birden çok ürün ekibi olan kurumlarda ortak CI/CD standardı kurmak isteyen platform ekipleri için, modüllerin sırası temelden kurumsal ölçeğe doğru ilerlediğinden iyi bir başlangıç çerçevesi sunabilir.