GitLab Pipeline Schedule: Zamanlanmış CI/CD Rehberi

GitLab pipeline schedule, yeni bir commit gelmese bile CI/CD hattınızı belirli saatlerde başlatır. Gece testleri, haftalık uyumluluk denetimi veya veri yenileme işi için sunucuya ayrıca crontab kurmanız gerekmez. Ancak cron ifadesinin doğru olması tek başına yeterli değildir: schedule sahibinin erişimi, hedef branch üzerindeki yapılandırma ve uygun runner birlikte çalışmalıdır.

Bu rehber, GitLab projesinde CI/CD yapılandırmasını düzenleyebilen geliştiriciler içindir. Önce zararsız bir Python sözdizimi denetimi kuracak, ardından inputs, değişkenler ve kaynak kurallarıyla kapsamı daraltacaksınız. Son bölümde dışarıdan POST ile tetikleme örneği bulunur; bu isteğin kabul edilmesiyle pipeline içindeki işlerin tamamlanmasını ayrı değerlendireceksiniz.

Scheduled pipeline modeli nasıl çalışır?

Schedule bir kabuk komutunu doğrudan çalıştırmaz; seçtiğiniz branch veya tag içindeki CI/CD tanımından pipeline oluşturur. Runner ise pipeline içindeki job görevlerini yürüten işlem ortamıdır. Bu nedenle saat geldiğinde pipeline oluşması, işin o saniyede başlayacağı anlamına gelmez. Runner kuyruğunu ve toplam çalışma süresini zamanlama kararına dahil edin.

İlk denemede dağıtım, kayıt silme veya ödeme işlemi seçmeyin. Çıktısı kolay incelenebilen bir kontrol kullanın. Beklenen sonucu önceden yazın: hangi branch okunacak, hangi job oluşacak ve logda ne görülecek? Böylece takvim hatasını uygulama hatasından ayırabilirsiniz. Temel kavramlara ihtiyaç duyarsanız cron job çalışma mantığını okuyabilirsiniz.

İlk schedule kurulumu: YAML dosyasından manuel denemeye

1. Proje köküne aşağıdaki .gitlab-ci.yml dosyasını ekleyin. Var olan bir pipeline kullanıyorsanız tüm dosyanın üzerine yazmak yerine job tanımını kendi aşamalarınıza uyarlayın.
2. Yapılandırmayı GitLab pipeline düzenleyicisinde doğrulayın ve hedef branch'e kaydedin. Örnekteki python:3.13-slim imajı için Docker imajlarını çalıştırabilen bir runner gerekir.
3. Build → Pipeline schedules → New schedule yolunu açın. Açıklamaya işin amacını yazın; hedef branch'i ve zamanlama alanlarını seçin. Örneğin her gece kontrol için 17 2 * * * kullanın.
4. Schedule kaydını kaydedip yanındaki Run ile deneyin. Oluşan pipeline içinden job logunu açın; yalnızca schedule listesindeki sonraki çalışma saatine bakmayın.

stages: [test]

nightly_syntax:
  stage: test
  image: python:3.13-slim
  rules:
    - if: '$CI_PIPELINE_SOURCE == "schedule"'
    - when: never
  script:
    - python -m compileall -q .

Bu komut depodaki Python kaynaklarını derleyerek sözdizimi hatalarını yakalar; işlevsel testlerin yerine geçmez. Shell executor kullanıyorsanız image alanı Python kurmaz; çalıştırıcı makinede uygun Python bulunmalıdır. Örnek başarılı olduktan sonra komutu projenizin gerçek test veya bakım betiğiyle değiştirin. İlk otomatik çalışmanın sonucunu da izleyin; manuel denemenin başarılı olması sahiplik sorunlarını tamamen dışlamaz.

Cron ve saat dilimi: çalışma saatini doğrulayın

Beş alan sırasıyla dakika, saat, ayın günü, ay ve haftanın günüdür. Genel desenleri crontab sözdizimi tablosuyla karşılaştırabilirsiniz. Schedule ekranındaki saat dilimini ayrıca kontrol edin; aynı ifade farklı saat dilimlerinde farklı gerçek anları gösterir. Türkiye iş saatleri hedefleniyorsa Europe/Istanbul seçimini açıkça yapın.

Saat başına yığılmayı azaltmak için örneklerde farklı dakikalar kullanılmıştır. GitLab örneğinizin izin verdiği en yüksek schedule sıklığı ayrıca sınırlandırılabilir; cron ifadesine bakarak dakika garantisi vermeyin. Yaz saati uygulanan bir bölgeye hizmet veriyorsanız cron saat dilimi rehberindeki yerel saat ve UTC ayrımını da değerlendirin. Rakip CI platformunda ise GitHub Actions schedule davranışı benzer biçimde UTC değerlendirilir ve yoğun dakikalarda gecikebilir.

Branch ve schedule sahibi: yetkileri birlikte yönetin

Hedef branch'in mevcut ve CI/CD dosyasının o branch'te geçerli olduğundan emin olun. Korunan branch için schedule sahibinin gerekli merge izni bulunmalıdır. Zamanlanmış çalışma sahibinin yetkileriyle yürürken schedule üzerindeki manuel Run işlemi tıklayan kullanıcının yetkilerini kullanır. İki denemenin farklı sonuç vermesinin nedeni bu olabilir.

Bakım sorumluluğunu bir kişiye bırakırken devir sürecini de tanımlayın: ekipten ayrılan kullanıcının schedule kayıtları incelensin, yeni sorumlu erişimi doğrulasın ve otomatik deneme izlensin. Engellenen veya projeden çıkarılan sahip nedeniyle pasifleşen kayıtta Maintainer ya da Owner yetkili kişi sahipliği devralabilir. Ayrıntılar için GitLab scheduled pipelines belgesini esas alın.

Inputs ve değişkenler: yapılandırmayı sır bilgilerinden ayırın

Schedule inputs desteği GitLab 17.11 ile eklenmiştir. Destekleyen kurulumlarda çalışma türünü serbest metin yerine seçenekleri tanımlanmış input ile vermek yanlış değerleri erken yakalar. Aşağıdaki dosya ilk örneğin alternatifidir; input başlığı ile job tanımı arasındaki üç tire YAML belge ayırıcısıdır.

spec:
  inputs:
    check_mode:
      default: syntax
      options: [syntax, tests]
---
scheduled_check:
  image: python:3.13-slim
  variables:
    CHECK_MODE: $[[ inputs.check_mode ]]
  rules:
    - if: '$CI_PIPELINE_SOURCE == "schedule"'
    - when: never
  script:
    - |
      if [ "$CHECK_MODE" = "tests" ]; then
        python -m unittest discover -s tests -v
      else
        python -m compileall -q .
      fi

Schedule oluştururken Inputs alanında modu seçin. tests seçeneği, depoda standart kütüphane unittest testlerinin bulunduğu bir tests dizini olduğunu varsayar. Projeniz başka test aracı kullanıyorsa komutu ve bağımlılık kurulumunu uyarlayın. Sıfır test çalıştıran yeşil sonuç yerine beklenen testlerin gerçekten keşfedildiğini logdan kontrol edin.

Parolayı input örneğine veya depoya koymayın. Gizli değerleri proje CI/CD değişkenlerinde uygun maskeleme ve koruma ayarlarıyla yönetin; korunan değişkenin korunmayan branch'e gelmemesini hata sanmayın. Schedule değişkenleri yalnızca ilgili zamanlanmış pipeline için kullanılabilir. Inputs dokümantasyonu tür, seçenek ve varsayılan değer kurallarını açıklar.

Pipeline source kuralları ve iki gerçek senaryo

CI_PIPELINE_SOURCE tetiklemenin nereden geldiğini belirtir. Native schedule için değer schedule, pipeline trigger token ile çağrılan API için trigger olur. Sadece job seviyesindeki rules yeterli olmayabilir: dosyanızdaki workflow:rules pipeline oluşumunu daha önce engelliyorsa ilgili kaynağa orada da izin vermelisiniz. Kurallar yukarıdan aşağıya değerlendirilir; geniş kapsamlı kuralı dar kuralın önüne koymayın.

Senaryo 1: Her gece 02:17'de ana branch üzerinde entegrasyon testleri çalıştırın. Commit olmasa da dış hizmet değişiklikleri nedeniyle bozulan bağlantıları yakalamak amaçlanır. Test veritabanını üretimden ayırın ve test hesapları kullanın. Sonuçları değerlendirirken kaç test koştuğunu ve hata veren servisi birlikte kaydedin.

Senaryo 2: Pazartesi 07:23'te desteklediğiniz bağımlılık sürümlerine karşı uyumluluk denetimi yapın. Ayrı schedule ve ayrı job kuralı kullanarak gecelik testten ayırın; örneğin seçimi bir input üzerinden yönetin. Çıktı bir rapor olmalı, kendiliğinden üretime dağıtım olmamalıdır. Kaynak bazlı örnekleri GitLab job rules referansıyla karşılaştırın.

Runner, pasif schedule ve diğer sık hatalar

Schedule Inactive görünüyor

Önce kaydın etkinlik durumunu ve sahibin proje üyeliğini kontrol edin. Sahip engellendiyse veya çıkarıldıysa yetkili kullanıcı sahipliği devralıp kaydı yeniden doğrulasın. Cron ifadesini değiştirip beklemek erişim sorununu çözmez; sonraki otomatik çalışmada yeni sahibin yetkilerini de sınayın.

Pipeline oluşuyor ama job pending kalıyor

İş listesinde bekleyen job varsa takvim tetiklemesi gerçekleşmiştir. Runner çevrimiçi mi, duraklatılmış mı, job etiketlerinin tamamını karşılıyor mu kontrol edin. Korunan runner ve branch uyumunu inceleyin. Etiketsiz job için runner'ın etiketsiz işleri kabul etmesi gerekir. Runner eşleştirme kuralları bu aşamada yol gösterir.

Pipeline hiç oluşmuyor veya beklenen job görünmüyor

Hedef branch içindeki YAML dosyasını doğrulayın; sonra workflow ve job rules koşullarını inceleyin. Yalnızca push kabul eden kural schedule için eşleşmez. Sorunu izole etmek için bakım job'unu sadece schedule kabul eden basit kuralla deneyin; üretim dağıtım kurallarını topluca gevşetmeyin.

Manuel deneme başarılı, otomatik çalışma yetkisiz

Run düğmesini kullanan kişinin ve schedule sahibinin erişimleri farklı olabilir. Korunan değişken, ortam veya branch erişimini iki kullanıcı için karşılaştırın. Loga parola basarak kontrol yapmayın; değişkenin varlığını ve yetki koşulunu güvenli biçimde doğrulayın.

Önceki bakım bitmeden yenisi başlıyor

İş süresini ölçün; yalnızca cron aralığını küçültmek işi hızlandırmaz. Aynı kaynağı değiştiren job'larda resource_group: maintenance ile seri yürütme tasarlayabilirsiniz. Bu kuyruklamadır; tekrar tetiklenen işin etkilerini kendiliğinden ortadan kaldırmaz. Ayrıntı için job yürütme denetimlerini inceleyin.

Trigger API ile dış zamanlama ve cronjob.com.tr

Dış takvim gerektiğinde Settings → CI/CD → Pipeline trigger tokens bölümünden token oluşturun. GitLab'ın Trigger API kimlik doğrulaması token ve ref parametreleriyle yapılır; keyfi bir Bearer header bu parametrelerin yerine geçmez. Terminaldeki temel POST örneği aşağıdadır. Gerçek token'ı depoya veya URL sorgusuna koymayın.

curl --fail-with-body --request POST \
  --form "token=$GITLAB_TRIGGER_TOKEN" \
  --form "ref=main" \
  "https://gitlab.com/api/v4/projects/123456/trigger/pipeline"

cronjob.com.tr panelinden doğrudan çağrıda URL bu API adresi, metot POST, içerik türü application/x-www-form-urlencoded, gövde ise URL kodlaması yapılmış token=GERCEK_TOKEN&ref=main olabilir. Gizli token'ı özel header ile koruyan bir uç nokta tercih ederseniz aşağıdaki Worker aracısını kullanın. GitLab token'ını aracıda saklayın; panel yalnızca aracıya ait sırrı taşısın. Proje numarasını ve branch'i kodda sabitlemek, çağıranın farklı bir dağıtım hedefi seçmesini önler.

export default {
  async fetch(request, env) {
    const url = new URL(request.url);
    if (url.pathname !== "/run") return new Response("Not found", { status: 404 });
    if (request.method !== "POST") return new Response("Method not allowed", { status: 405 });
    if (!env.CRON_SECRET || !env.GITLAB_TRIGGER_TOKEN) {
      return new Response("Missing configuration", { status: 500 });
    }
    if (request.headers.get("Authorization") !== "Bearer " + env.CRON_SECRET) {
      return new Response("Unauthorized", { status: 401 });
    }
    try {
      const result = await fetch(
        "https://gitlab.com/api/v4/projects/123456/trigger/pipeline",
        {
          method: "POST",
          body: new URLSearchParams({
            token: env.GITLAB_TRIGGER_TOKEN,
            ref: "main"
          })
        }
      );
      if (!result.ok) return new Response("GitLab rejected request", { status: 502 });
      const pipeline = await result.json();
      return Response.json({ id: pipeline.id, status: pipeline.status }, { status: 202 });
    } catch {
      return new Response("GitLab connection failed", { status: 502 });
    }
  }
};

Aracı Worker'a CRON_SECRET ve GITLAB_TRIGGER_TOKEN sırlarını tanımlayın. Panelde URL olarak https://gitlab-kopru.ornek.workers.dev/run, metot POST, özel header olarak Authorization: Bearer GERCEK_ARACI_SIRRI girin. Zamanlama için 17 2 * * * ve Europe/Istanbul seçin. Worker alan adını kendi dağıttığınız adresle değiştirin. YAML kurallarına trigger kaynağını da eklemeden bu yönteme geçmeyin.

Cron ifadeli işlerde yanıt bekleme süresi 290 saniyedir; bir dakikalık hazır aralıkta 55 saniyedir. HTTP 200–399 ve bağlantı hatası olmaması başarı sayılır. Varsayılan ardışık hata eşiği 3'tür; 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 bulunur.

Aracının 202 yanıtı pipeline'ın kabul edildiğini gösterir; testlerin geçtiğini göstermez. Yanıttaki pipeline kimliğiyle GitLab sonucunu takip edin. Native schedule ile dış zamanlayıcıyı aynı işe bağlarsanız çift çalışma oluşturabilirsiniz. Tetikleme hatalarında token türünü, proje numarasını ve ref'i kontrol edin; resmi Trigger API rehberi hata ayrımlarını açıklar.

Sıkça Sorulan Sorular (SSS)

GitLab pipeline schedule yeni commit olmadan çalışır mı?

Evet. Etkin bir schedule, hedef branch veya tag için kod değişikliği beklemeden pipeline başlatabilir. Geçerli CI/CD tanımı, uygun kurallar ve çalışabilecek bir runner gerekir.

Manuel Run ile otomatik schedule aynı yetkiyi mi kullanır?

Hayır. Schedule üzerindeki manuel Run işlemi başlatan kullanıcının, otomatik çalışma ise schedule sahibinin yetkileriyle yürür. Bu fark korunan kaynaklara erişim sonucunu değiştirebilir.

Trigger API çağrısında pipeline source schedule olur mu?

Pipeline trigger token ile tetiklenen pipeline için kaynak trigger olur. Native zamanlanmış pipeline için kaynak schedule değeridir; kuralları kullandığınız yönteme göre düzenleyin.

HTTP başarılıysa GitLab testleri de geçmiş midir?

Hayır. Tetikleme yanıtı pipeline oluşturma isteğinin kabul edildiğini gösterebilir. Testlerin ve dağıtım işlerinin sonucu GitLab pipeline ve job durumlarından ayrıca izlenmelidir.

İlgili Rehberler