cache-mode, GitHub Actions önbelleğinde geri yükleme ve kaydetme yetkilerini ayrı ayrı yönetir. Düşük güvenli veya dış katkıya açık tetikleyicilerde önbelleğe yazma iznini varsayılan hâline bırakmak yerine, işin gerçekten bu izne ihtiyacı olup olmadığını değerlendirmek güvenli bir workflow tasarımını destekler.
Temel yaklaşım şudur: Bir iş yalnızca bağımlılıkları hızlandırmak için mevcut önbelleği kullanıyorsa okuma erişimi yeterli olabilir. Yeni bir önbellek oluşturması ya da mevcut kapsamda güncelleme yapması gerekiyorsa yazma yetkisi, güvenilen tetikleyicilerle ve dar kapsamla verilmelidir.
GitHub Actions cache-mode neyi ayırır?
cache-mode, belirli bir action’a ait with girdisi değil, GitHub Actions workflow söz diziminde yer alan bir anahtardır. İşin önbelleği geri yükleyebilmesi ile önbellek kaydedebilmesi için verilen erişimi birbirinden ayırır. GitHub, bu erişimi işin önbellek belirtecine uygular; actions/cache ve @actions/cache araç seti de etkin modu dikkate alır. Ayrıntılı davranış, GitHub’ın dependency caching başvuru dokümantasyonunda açıklanır.
Bu ayar dört değer kabul eder: read geri yüklemeye izin verir, kaydetmeye izin vermez. write hem geri yükleme hem kaydetme izni sağlar. write-only yalnız kaydetme izni verir. none ise iki işlemi de kapatır. Okuma izni olmayan bir işte geri yükleme atlanır ve bu durum cache miss olarak ele alınır. Yazma izni olmayan bir işte ise kaydetme işlemi yapılmaz, workflow devam eder.
cache-mode workflow düzeyinde tanımlandığında, ilgili workflow içindeki işlere uygulanır. Bir işte ayrıca tanımlanırsa iş düzeyindeki değer o iş için önceliklidir. Yeniden kullanılabilir workflow çağrılarında da çağıran işte açıkça belirtilen mod, çağrılan workflow’un isteyebileceği erişim için üst sınır oluşturur. Böylece ortak workflow dosyalarının ihtiyaç duyduğundan geniş cache erişimi alması önlenebilir.
Ayar belirtilmezse GitHub, tetikleyicinin güven bağlamına göre etkin bir varsayılan seçer: güvenilen tetikleyicilerde yazma erişimi, düşük güvenli tetikleyicilerde ise salt okuma erişimi kullanılır. Bu nedenle dış katkıdan etkilenebilen bir çalıştırmada write veya write-only değerini açıkça eklemek, varsayılan korumayı bilinçli olarak değiştiren bir karardır.
En az ayrıcalık ilkesi cache güvenliğini nasıl destekler?
En az ayrıcalık ilkesi, her job’a yalnızca yaptığı iş için gereken erişimi vermektir. Örneğin bir pull request doğrulama işi bağımlılıkları indirip test çalıştırıyorsa, mevcut önbelleği geri yüklemesi yeterli olabilir. Aynı işin önbelleğe yazmasına izin vermek, performans açısından zorunlu değilse ek bir yetki alanı açar.
Önbellek anahtarı, tek başına güvenlik sınırı değildir. Anahtar, hangi dosyaların hangi cache girdisiyle eşleşeceğini belirler; GitHub ayrıca dal, etiket ve pull request bağlamına göre cache kapsamı uygular. Pull request ile oluşturulan cache girdileri birleşim başvurusu kapsamına bağlıdır ve taban dalın ya da diğer pull request’lerin kullanımına açılmaz. Buna karşılık düşük güvenli bir tetikleyicide varsayılan dal kapsamına yazma yetkisini açıkça genişletmek, daha sonra güvenilen bir workflow’un geri yükleyebileceği içeriğin kaynağını dikkatle ele almayı gerektirir. GitHub bu durumu cache poisoning riski kapsamında değerlendirir ve düşük güvenli tetikleyiciler için salt okunur varsayılan uygular. GitHub’ın pull_request_target güvenlik rehberi, özellikle dış etkilenebilir kodla çalışan işlerde cache yazma erişiminin neden sınırlandırılması gerektiğini açıklar.
Somut senaryoda, pull_request_target ile çalışan bir iş pull request verisini, komutunu veya kodunu işleyebilir. Bu iş yazma yetkisine sahipse ve önbelleğe çalıştırılabilir içerik kaydedebiliyorsa, aynı cache kapsamını kullanan daha ayrıcalıklı bir workflow bu içeriği daha sonra geri yükleyebilir. Buradaki amaç her cache kullanımını engellemek değil, güvenilmeyen girdinin cache’e yazılabildiği yolları görünür hâle getirmektir.
| Tetikleyici | İş amacı | Önerilen cache erişimi |
|---|---|---|
push |
Varsayılan dalda bağımlılık önbelleğini güncellemek | write |
workflow_dispatch |
Kontrollü bakım veya önbellek yenileme | Girdi ve çalıştıran yetkileri denetleniyorsa write |
pull_request |
Derleme ve test doğrulaması | Yazma gerekmiyorsa read |
pull_request_target, issue_comment, workflow_run |
Dış etkilenebilir olaylara yanıt vermek | Genellikle read veya none |
Bu çerçevede cache yoluna erişim anahtarları, token’lar veya başka hassas veriler eklenmemelidir. Ayrıca cache geri yüklendikten sonra çalıştırılan dosyaların, o cache’in hangi workflow tarafından ve hangi yetki bağlamında üretildiğiyle birlikte değerlendirilmesi gerekir.
read, write, write-only ve none seçenekleri nasıl karşılaştırılır?
cache-mode, bir işin mevcut cache girdilerini geri yükleyip yükleyemeyeceğini ve yeni cache kaydedip kaydedemeyeceğini ayrı ayrı belirler. GitHub Actions, bu anahtar için read, write, write-only ve none değerlerini kabul eder. Ayar belirtilmezse güvenilen tetikleyicilerde etkili varsayılan write, düşük güvenli tetikleyicilerde ise read olur. Ayrıntılı davranış, GitHub’ın dependency caching referansında açıklanır.
| Seçenek | Cache geri yükleme davranışı | Cache kaydetme davranışı | Uygun iş amacı |
|---|---|---|---|
read |
İzin verilir. | İzin verilmez. | Pull request doğrulama, test ve inceleme gibi mevcut bağımlılıkları kullanması yeterli işler. |
write |
İzin verilir. | İzin verilir. | Güvenilen bir dalda bağımlılıkları hem kullanıp hem güncellemesi gereken derleme veya dağıtım işleri. |
write-only |
İzin verilmez. | İzin verilir. | Önceki girdileri tüketmeden, yalnızca yeni bir cache üretmesi amaçlanan kontrollü işler. |
none |
İzin verilmez. | İzin verilmez. | Cache kullanımının iş akışı açısından gerekli olmadığı veya özellikle devre dışı bırakılmak istendiği işler. |
read ve write çoğu senaryoda en anlaşılır seçimlerdir. write-only ise geri yükleme yapılmadığında cache miss olarak devam eden, yalnız kaydetme adımını uygulayan daha özel bir davranıştır. none seçildiğinde hem geri yükleme hem kaydetme atlanır; bu durum işin başarısız olduğu anlamına gelmez.
cache-mode workflow ve job düzeyinde nerede uygulanır?
cache-mode YAML dosyasının üst düzeyinde ya da belirli bir job altında tanımlanabilir. Üst düzeydeki ayar, job kendi değeriyle ezmediği sürece iş akışındaki tüm job’lara uygulanır. Job düzeyindeki ayar ise yalnızca ilgili job’un cache erişimini değiştirir. GitHub’ın workflow syntax dokümantasyonu, bu öncelik sırasını açıkça tanımlar.
- Workflow düzeyi: Ortak politika gerekirken kullanılır. Örneğin tüm doğrulama işlerinin yalnızca cache okuması istenebilir.
- Job düzeyi: Aynı workflow içinde farklı gereksinimleri ayırmak için kullanılır. Bir test job’u
read, güvenilen bir derleme job’uwritealabilir. - Action çağrısı:
cache-mode,actions/cacheadımınınwithgirdisi olarak değil, workflow veya job anahtarı olarak konumlandırılır. Action, job’a tanınan etkili cache moduna göre geri yükleme ve kaydetme işlemlerini uygular.
Hiçbir düzeyde tanım yapılmazsa tetikleyici türüne bağlı varsayılan devreye girer. Bu nedenle yalnızca bir job’un yazma yetkisine ihtiyacı varsa, workflow genelini write yapmak yerine o job için açıkça tanımlamak en az ayrıcalık yaklaşımını destekler.
Reusable workflow çağrılarında da çağıran job’a verilen açık cache-mode sınırı, çağrılan workflow’un isteyebileceği erişimi sınırlar. Çağrılan workflow bu sınırın ötesinde bir mod isterse çalışma başlamadan doğrulama hatası oluşur. Çağıran job’da açık bir sınır yoksa, yalnız tetikleyici varsayımına güvenmek yerine çağrılan workflow’un ihtiyaç duyduğu erişimi bilinçli biçimde sınırlamak daha nettir.
Pull request ve push için güvenli YAML örneği
Cache geri yükleme ve cache kaydetme ayrı yetkilerdir. Pull request doğrulamasında mevcut bağımlılık cache’ini kullanmak yararlı olabilir, ancak yazma yetkisini kapatmak yeni bir cache kaydının oluşmasını engeller. Güven düzeyi daha düşük tetikleyicilerde write veya write-only tanımlamak, GitHub’ın varsayılan salt okunur sınırını aşabileceğinden, yazma iznini güvenilen akışlarla sınırlamak en az ayrıcalık ilkesiyle daha uyumludur.
Aşağıdaki örnek, npm kullanan ve kök dizininde package-lock.json bulunan bir proje içindir. Pull request job’u cache’i yalnızca geri yükler; main dalına yapılan push ise aynı cache’i geri yükleyip koşullar uygunsa kaydedebilir.
name: Test and dependency cache
on:
pull_request:
push:
branches: [main]
jobs:
verify-pull-request:
if: github.event_name == 'pull_request'
runs-on: ubuntu-latest
cache-mode: read
steps:
- uses: actions/checkout@v7
- uses: actions/setup-node@v7
with:
node-version: '24'
package-manager-cache: false
- uses: actions/cache@v5
with:
path: ~/.npm
key: npm-${{ hashFiles('**/package-lock.json') }}
- run: npm ci
- run: npm test
maintain-cache-on-push:
if: github.event_name == 'push'
runs-on: ubuntu-latest
cache-mode: write
steps:
- uses: actions/checkout@v7
- uses: actions/setup-node@v7
with:
node-version: '24'
package-manager-cache: false
- uses: actions/cache@v5
with:
path: ~/.npm
key: npm-${{ hashFiles('**/package-lock.json') }}
- run: npm ci
- run: npm testBeklenen davranış: Pull request çalışmasında anahtarla eşleşen uygun cache geri yüklenebilir, fakat read nedeniyle kaydetme adımı uygulanmaz. push job’unda ise write, hem geri yükleme hem kaydetme izni verir. Cache işlemi izin nedeniyle atlanırsa workflow hata vermez; geri yükleme cache miss olarak, kaydetme ise yapılmamış işlem olarak devam eder.
Aşağıdaki çerçeve, job’un ihtiyacına göre modu seçmeyi kolaylaştırır. Özellikle yalnız cache yazmak için tasarlanan bir job, geri yükleme izni olmadan write-only kullanabilir.
| Tetikleyici türü | Güven düzeyi | Cache ihtiyacı | Cache yazımının etkisi | İşin amacı | Uygun mod |
|---|---|---|---|---|---|
| Pull request doğrulaması | Daha düşük güvenli olabilir | Geri yükleme yararlı | Yazma engellenir | Test ve derleme kontrolü | read |
| Güvenilen push akışı | Güvenilen | Geri yükleme ve güncelleme gerekli | Yeni cache kaydı oluşturabilir | Bağımlılık cache’ini sürdürmek | write |
| Cache’e ihtiyaç duymayan job | Değişken | Yok | Cache işlemi yapılmaz | Bağımsız doğrulama | none |
| Yalnızca cache kaydetme işi | Güvenilen | Geri yükleme gerekli değil | Yeni cache kaydı oluşturabilir | Üretilen cache’i saklamak | write-only |
Sık Sorulan Sorular
Pull request iş akışında neden cache yazma yetkisi sınırlandırılmalıdır?
Pull request kodu veya girdileri güvenilir kabul edilmeden çalışabilir. read kullanmak, gerekli olduğunda cache geri yüklemeyi korurken yeni bir cache’in kaydedilmesini önler. Böylece sonraki güvenilen işlerde kullanılacak cache içeriklerinin kontrolsüz biçimde değişmesi riski azaltılır.
read ile write arasındaki temel fark nedir?
read yalnız cache geri yüklemeye izin verir. write ise hem geri yükleme hem de yeni cache kaydetme izni sağlar.
write-only seçeneği hangi iş akışlarında kullanılabilir?
write-only, mevcut cache’i geri yüklemeye gerek duymayan fakat oluşturulan çıktıyı cache olarak kaydetmesi gereken güvenilen job’larda kullanılabilir. Bu modda geri yükleme atlanır, kaydetme izni korunur.
cache’e hiç ihtiyaç olmayan bir job için none seçeneği ne zaman tercih edilir?
Bir job bağımlılık veya derleme cache’i kullanmıyorsa none seçilebilir. Bu ayar, hem geri yüklemeyi hem kaydetmeyi kapatarak job’un cache erişimini açıkça sıfırlar.
Reusable workflow içinde cache-mode ayarının sınırları nelerdir?
Çağıran job’daki açık bir cache-mode ayarı, reusable workflow’a verilebilecek cache erişiminin üst sınırını belirler. Çağrılan workflow bu sınırın üzerinde bir mod isterse çalışma başlamaz ve doğrulama hatası oluşur. Çağıran job’da açık veya devralınmış bir sınır yoksa, reusable workflow kendi ayarıyla daha geniş erişim isteyebilir.
Cache ayarını tetikleyicinin güven düzeyi ve job’un gerçek ihtiyacıyla birlikte değerlendirmek, workflow’ları hem daha anlaşılır hem de daha kontrollü tutar.
