GitHub Actions Schedule: Cron ile Otomatik Çalıştırma

GitHub Actions schedule, bir workflow dosyasındaki görevleri cron ifadesine göre başlatır. Gece test çalıştırmak, düzenli veri kontrolü yapmak veya rapor üretmek için kullanılabilir. Ancak dosyanın doğru dala eklenmesi, zamanın doğru yorumlanması ve görevin gerçekten tamamlandığının izlenmesi gerekir; yalnızca YAML içine cron satırı yazmak yeterli bir işletim planı değildir.

Bu rehberde önce zararsız bir saat yazdırma örneğiyle tetiklemeyi doğrulayacak, ardından kendi komutunuzu ekleyeceksiniz. Son bölümde cronjob.com.tr üzerinden yetkili HTTP isteğiyle aynı workflow'u başlatma seçeneği bulunuyor. Cron alanlarının ayrıntılı açıklaması için cron ifadeleri rehberini kullanın; burada odağımız dosyanın yerleşimi, çalışmanın yaşam döngüsü ve hata teşhisidir.

Schedule olayı nasıl çalışır?

Workflow, GitHub'ın çalıştıracağı işleri ve adımları tanımlayan YAML dosyasıdır. Runner, bu adımları yürüten çalışma ortamıdır. Zamanlama olayı çalışmayı başlatır; işlerin runner üzerinde tamamlanması daha sonra gerçekleşir. Başlatılma, kuyrukta bekleme ve tamamlanma zamanlarını ayrı kaydetmek, geç başlayan bir işi uzun süren bir komuttan ayırmanızı sağlar.

Depo GitHub yerine GitLab'da barınıyorsa aynı periyodik iş pipeline schedule ile zamanlanmış GitLab derlemesi olarak kurulur; iki sistemin cron saat dilimi ve dal kuralları farklı olduğundan ifade taşınırken yeniden hesaplanmalıdır.

İlk kullanım senaryosu, her gece 03.17'de bağımlı bir servisten günlük özet verisini alıp doğrulamaktır. Günlük aralık veri kaynağının yenilenme düzeniyle uyumludur. İkinci senaryo, hafta içi her sabah 08.23'te rapor üretmektir; raporun ofis açılışından önce hazırlanması amaçlanır. Her iki durumda da komutun çalışması kadar beklenen raporun veya doğrulama sonucunun oluşmasını kontrol edin.

Üretim görevi seçerken maliyeti ve erişimi de düşünün. Komutun ihtiyaç duyduğu ağ bağlantıları runner ortamından sağlanabiliyor mu, çıktı nerede saklanacak ve başarısız sonucu kim inceleyecek? Geçici çalışma ortamının yerel dosyasını tek kalıcı kayıt olarak kullanmayın; raporun tüketileceği konumu iş akışınızda açıkça tanımlayın. Raporu zaten Vercel üzerinde koşan bir API yoluna yazdıracaksanız Vercel cron job ayarlarıyla zamanlamayı aynı platformda tutmak ara katmanı kaldırır.

Adım adım ilk workflow dosyası

1. Depoda Actions kullanımının açık olduğunu ve workflow ekleme yetkiniz bulunduğunu doğrulayın. İlk denemeyi gerçek veri değiştirmeyen bir komutla yapın.
2. Varsayılan dalda .github/workflows/daily-report.yml dosyasını oluşturun. Dosyanın .yml veya .yaml uzantısı olmalıdır; başka klasöre koymak workflow tanımı oluşturmaz.
3. Aşağıdaki örneği kaydedin. Girintilerde boşluk kullanın ve schedule listesinin on altında kaldığını kontrol edin. Cron değerini tırnak içinde tutun.
4. Actions sekmesinde Daily report workflow'unu açın. Run workflow ile manuel deneyin; tamamlanan çalışmanın print-time adımını inceleyin. Böylece cron saatini beklemeden YAML ve komut tarafını kontrol edersiniz.
5. Sonraki planlı çalışmayı izleyin. Örnekte yazdırılan UTC saati komutun çalıştığı anı gösterir; beklediğiniz tetikleme zamanı ile karşılaştırın.

name: Daily report
on:
  schedule:
    - cron: '17 3 * * *'
      timezone: 'Europe/Istanbul'
  workflow_dispatch:
permissions:
  contents: read
jobs:
  report:
    runs-on: ubuntu-latest
    timeout-minutes: 10
    steps:
      - name: print-time
        run: date -u

Örnek yalnızca işletim sisteminin date komutunu çalıştırdığı için depo dosyalarını indirmez. Kendi rapor betiğinizi çalıştıracaksanız önce depo içeriğini çalışma alanına alan bir checkout adımı ve gerekiyorsa dil ortamı kurulumu ekleyin. Bağımlılık dosyalarının projede mevcut olduğunu doğrulayın. Manuel testin başarılı olması, schedule olayının ayrıca doğru yapılandırıldığını kanıtlamaz.

Cron ve timezone ayarı

Beş alan sırasıyla dakika, saat, ayın günü, ay ve haftanın günüdür. Zaman dilimi belirtilmezse UTC kullanılır; güncel GitHub Actions, schedule girdisinde IANA adıyla timezone belirtmeyi destekler. Örnekte 03.17 İstanbul saatidir. UTC karşılığıyla ilerlemek isterseniz timezone satırını kaldırıp 17 0 * * * kullanabilirsiniz.

Hafta içi raporu için aynı yapıdaki ifadeyi 23 8 * * 1-5 yapıp Europe/Istanbul değerini koruyun. Birden fazla schedule girdisi eklerken hangi işin hangi takvimde çalışacağını belgeleyin. İfade üretirken crontab sözdizimi sayfasından yararlanabilirsiniz; fakat GitHub'a kabuk komutu veya Linux kullanıcı alanı yapıştırmayın, yalnız beş zaman alanını yazın.

Runner içindeki TZ ortam değişkeni, programın tarih gösterimini etkileyebilir; olayın takvimini ayarlamak için schedule girdisini düzenleyin. Farklı bölgelerde yaz saati geçişi bulunabildiğinden yalnız sabit saat farkına dayanarak dönüşüm yapmayın. Yerel saat gereksinimi olan işler için cron saat dilimi rehberindeki kontrol yaklaşımını uygulayın.

Default branch koşulu

Schedule, workflow dosyası varsayılan dalda bulunduğunda tetiklenir ve o dalın son commit'i üzerinde çalışır. Varsayılan dalın adı her depoda main olmak zorunda değildir. Depo ayarından gerçek adı öğrenin; yalnız bir özellik dalına eklenmiş dosyayla planlı çalışma beklemeyin. Bu davranış GitHub schedule belgelerinde açıklanır.

Bir değişikliği inceleme dalında hazırlayıp manuel denemek faydalıdır; planlı kullanım için dosyanın varsayılan dala ulaşması gerekir. Değişikliği birleştirdikten sonra Actions ekranında doğru dosyanın ve güncel commit'in görüldüğünü kontrol edin. Dal adı değişmişse dış tetikleme gövdesindeki ref değerini de gözden geçirin.

Minimum aralık, gecikmeler ve çakışmalar

GitHub schedule için en kısa aralık beş dakikadır. Yoğunlukta, özellikle saat başlarında, çalıştırmalar gecikebilir ve bazı kuyruktaki işler düşürülebilir. Dakikası kesin bir son teslim beklentisini yalnız bu mekanizmaya bağlamayın. Örnekteki 17. dakika yoğun saat başından kaçınır; yine de başlangıç garantisi vermez.

Bir işin ortalama süresinden çok en uzun süresini düşünün. On beş dakikada bir başlayan fakat yirmi dakika süren bir veri aktarımı önceki çalışmayla kesişebilir. Aynı raporun iki kez yazılması sorun yaratıyorsa uygulamada benzersiz dönem kaydı veya kilit kullanın. GitHub concurrency ayarını da gereksiniminize göre değerlendirin; bir çalışmayı iptal etmek yarım kalan dış işlemleri kendiliğinden geri almaz.

Örnekteki timeout-minutes runner işinin süre sınırıdır. Harici API bağlantısının bekleme sınırıyla aynı şey değildir; curl gibi istemcilerin bağlantı ve toplam istek sürelerini ayrıca sınırlayın. İş yarım kaldığında son başarılı dönemi saklamak ve eksik dönemleri kontrollü tamamlamak, yalnız bir sonraki takvimi beklemekten daha güvenilir bir kurtarma yöntemidir.

Pasifleşen workflow'lar ve sık hatalar

Herkese açık depolarda 60 gün depo etkinliği olmazsa zamanlanmış workflow'lar otomatik devre dışı bırakılır. Actions ekranından etkinliği kontrol edip gerekiyorsa workflow'u yeniden etkinleştirin. Hata araştırırken önce hiç çalışma kaydı oluşmamış mı, yoksa oluşan çalışma mı başarısız olmuş sorusunu ayırın.

• Hiç schedule kaydı yok: Dosyanın varsayılan dalda, doğru klasörde olduğunu ve workflow'un etkin bulunduğunu kontrol edin. Sonra cron saatini ve timezone değerini yeniden hesaplayın.
• Invalid workflow file: YAML girintisi, yanlış anahtar konumu veya eksik alan olabilir. Actions ekranındaki satır bilgisini inceleyin; çalışan en küçük örneğe dönüp kendi adımlarınızı sırayla ekleyin.
• Run workflow görünmüyor: Dosyada workflow_dispatch bulunduğunu, varsayılan dala ulaştığını ve yazma yetkiniz olduğunu kontrol edin. Schedule tanımı tek başına manuel başlatma düğmesi oluşturmaz.
• Komut dosyası bulunamıyor: Depo dosyalarını almadan yerel betiği çalıştırıyor olabilirsiniz. Checkout adımını, göreli yolu ve dosya adındaki büyük küçük harfleri doğrulayın.
• API'de 401, 403 veya 404: Token, depo erişimi ve workflow dosya adı uyuşmayabilir. Önce doğru owner/repo ve ref kullanıldığını, sonra token'ın seçili depoya yetkisini kontrol edin.

Secrets ve çalışma kayıtları

Workflow içinden başka bir servise bağlanırken parolayı YAML'a yazmayın. Depo ayarlarındaki Secrets and variables alanında Actions secret oluşturup yalnız ihtiyaç duyulan adıma ortam değişkeni olarak aktarın. Secret değerini ekrana basarak doğrulamaya çalışmak yerine isteğin sonucunu ve sunucunun verdiği güvenli işlem kimliğini kontrol edin. Kullanım ayrıntıları GitHub secrets belgelerinde bulunur.

- name: Trigger report endpoint
  env:
    REPORT_TOKEN: ${{ secrets.REPORT_TOKEN }}
  run: |
    curl --silent --show-error --fail-with-body \
      --connect-timeout 10 --max-time 45 \
      --request POST \
      --header "Authorization: Bearer $REPORT_TOKEN" \
      https://example.com/api/jobs/report

Bu adımı örnekteki steps listesine ekleyebilirsiniz; uç noktanın ilgili header'ı doğrulaması gerekir. Gerçek alan adınızı kullanın ve alıcının istediği gövdeyi ayrıca ekleyin. Gövde hassas veri içeriyorsa çıktıların çalışma günlüklerine taşınabileceğini hesaba katın; teşhis için gereken az miktarda bilgi kaydedin.

Actions kaydında hangi adımın başarısız olduğunu, çıkış kodunu ve süreyi inceleyin. HTTP kabul yanıtıyla dönen uzun işlerde runner yeşil görünse bile rapor henüz hazır olmayabilir. Tamamlanmayı denetleyen ayrı adım veya uygulama izleme kaydı kurun. Güvenli uç nokta tasarımı için cron job güvenliği rehberini kullanabilirsiniz.

cronjob.com.tr ile workflow_dispatch üzerinden dış tetikleme

Workflow_dispatch, GitHub REST API aracılığıyla da başlatılabilir. Önce örnekteki olay tanımını koruyun ve hedef depoya erişen, yalnız gereken yetkilere sahip bir token hazırlayın. Fine-grained token için Actions yazma izni gerekir. Resmî dispatch API belgesi ref alanını ve güncel yanıt biçimini açıklar.

POST https://api.github.com/repos/OWNER/REPO/actions/workflows/daily-report.yml/dispatches
Authorization: Bearer GITHUB_TOKEN_DEGERINIZ
Accept: application/vnd.github+json
Content-Type: application/json
X-GitHub-Api-Version: 2026-03-10

{"ref":"main"}

1. Panelde yeni iş açın; OWNER ve REPO değerleri değiştirilmiş API adresini URL alanına girin, POST seçin.
2. Örnekteki header'ları ayrı ad ve değer olarak ekleyin. Gizli token'ı Authorization başlığında taşıyın. Gövde alanına yalnız ref JSON'unu yazın; main yerine gerçek hedef dalınızı kullanın.
3. Örneğin 23 8 * * 1-5 ifadesi ve Europe/Istanbul saat dilimi seçin. Aynı işi iki kez başlatmamak için yerleşik schedule ile dış takvimden hangisinin sorumlu olacağını belirleyin.
4. Manuel çalıştırıp HTTP yanıtını inceleyin; ardından GitHub Actions ekranında ilgili çalışmanın oluştuğunu ve tamamlandığını doğrulayın.

API sürümü 2026-03-10 için belgelenen başarılı dispatch yanıtı HTTP 200 ile çalışma kimliği ve adreslerini içerir. Bu kabul, workflow sonucunun başarılı olduğunu göstermez. Panelde bağlantı hatası olmadan HTTP 200–399 başarı sayılır; sonraki runner hatasının otomatik olarak HTTP iş hatasına dönüşeceğini varsaymayın.

Cron ifadeli işlerde yanıt bekleme sınırı 290 saniyedir. Hazır aralıkta bir dakika için 55, iki dakika için 115, beş dakika ve üzerinde 290 saniyedir. HTTP kayıtları yedi gün tutulur. Ardışık hata eşiği varsayılan üçtür; 1–20 arasında ayarlanabilir. Eşik aşılınca erişim sorunu, düzelince kesinti süresiyle düzeldi e-postası gönderilir; aynı işin bildirimleri arasında en az 60 dakika vardır. Bu bildirimler dispatch isteğini izler; workflow sonucunu Actions üzerinden ayrıca takip edin.

Sıkça Sorulan Sorular (SSS)

GitHub Actions schedule hangi saat dilimini kullanır?

Varsayılan saat dilimi UTC'dir. Schedule girdisine timezone ekleyerek Europe/Istanbul gibi bir IANA saat dilimi seçebilirsiniz.

Schedule her dakika çalışabilir mi?

Hayır. GitHub Actions schedule için desteklenen en kısa aralık beş dakikadır; yoğunluk nedeniyle başlangıç gecikebilir.

Workflow yalnız özellik dalındaysa schedule çalışır mı?

Hayır. Zamanlanmış workflow dosyası varsayılan dalda bulunmalıdır; schedule o dalın son commit'i üzerinde çalışır.

Dispatch isteğinin başarısı workflow'un tamamlandığını gösterir mi?

Hayır. HTTP yanıtı tetikleme isteğinin sonucudur. Workflow'un tamamlanma durumunu ve adım sonuçlarını GitHub Actions kayıtlarından ayrıca kontrol edin.

İlgili Rehberler