.ejo dosyası

.ejo ne işe yarar?#

.ejo, repo kökünde duran ve servisi tanımlayan YAML dosyasıdır. EJO bu dosyayı okuyarak:

• repo'yu Servisler > Katalog altında bir servis olarak listeler,
• servisin sahibini EJO kullanıcı veya gruplarına eşler,
• dosyada bir pipeline varsa (organizasyon izin veriyorsa) repo için binding'i kendisi kurar,
• preview, otomatik tarama ve deploy verification gibi ayarları binding'e ve environment'a uygular.

En basit .ejo yalnızca bir ad ve açıklamadan oluşur:

name: web
description: Acme web arayüzü
owner: team-web

EJO dosyayı nereden okur?#

1. Ayarlar > Organizasyon altında, SCM grupları kartında organizasyonunuza bir SCM grubu ekleyin. Provider ve Grup alanları:

   Provider	Grup
   GitHub organizasyonu veya team'i	acme ya da acme/platform (organizasyon/team)
   GitLab grubu	acme ya da alt grup için acme/platform
   Azure DevOps projesi	org/project

   GitHub gruplarını EJO Cloud GitHub App'i ile okur. GitLab ve Azure DevOps gruplarını taramak için EJO'da GitLab token'ı ya da Azure DevOps PAT'i tanımlı olmalıdır; değilse grup gitlab token is not configured ya da azure devops token is not configured hatası gösterir. Bkz. Kaynak kod bağlantısı (SCM).

2. EJO grubun repo'larını tarar. Her repo için önce SCM'nin default branch'ine, yoksa main'e, yoksa master'a bakar ve o branch'in kökünde .ejo arar.

3. Sonuç Servisler > Kaynaklar sayfasında görünür: .ejo yok, .ejo hatalı (sebebiyle), katalogda ama pipeline yok, binding kuruldu ya da binding kurulamadı (sebebiyle).

Tarama, seçili branch'e yapılan ve .ejo'yu değiştiren her push'ta (GitHub) ya da her push'ta (GitLab, Azure DevOps) tekrarlanır. Ayrıca her grup 30 dakikada bir taranır. Kaynaklar sayfasındaki Tekrar oku ile taramayı elle de başlatabilirsiniz.

Alanlar#

Not: preview, supply_chain, verify, oncall ve argocd bloklarında bilinmeyen bir anahtar hata verir. Böylece lable: gibi bir yazım hatası sessizce yok sayılmaz.

name ve servis kimliği#

Ad serbest metindir, ancak pipeline OIDC token'larında servis kimliği olarak kullanılabilmesi için ^[a-z0-9][a-z0-9._-]{0,62}$ biçiminde (küçük harf, rakam, ., _, -) ve organizasyonda benzersiz olmalıdır. Aynı adı ilk alan repo adı korur; aynı adı kullanan ikinci bir repo Kaynaklar sayfasında uyarıyla görünür.

owner#

Sahip, EJO'nun bildiği kullanıcı ve gruplarla eşleştirilir. Eşleşmezse servis yine kataloğa eklenir, sahip boş kalır ve bu durum Eksikler sekmesinde görünür. Eşleştirme her taramada yeniden yapılır.

Pipeline tanımlama#

.ejo içinde pipeline iki şekilde tanımlanabilir.

Ayrı bir dosyaya başvuru (önerilen)#

name: web
owner: team-web
pipeline:
  file: ci/ejo.yaml

• Yol repo köküne göre göreli olmalı, / ile başlamamalı, .. içermemeli ve .yaml, .yml veya .json ile bitmelidir (en fazla 512 karakter).
• file yanında başka bir anahtar olamaz.
• Dosya .ejo ile aynı repo ve branch'ten okunur ve pipeline tanımı şemasıyla doğrulanır. Dosya yoksa ya da bozuksa repo "binding kurulamadı" durumunda kalır ve sebep yolu adlandırır, örneğin pipeline file ci/ejo.yaml not found.
• Otomatik kurulan binding'in pipeline kaynağı repo olur; o dosyadaki değişiklikler push'larla pipeline'a yansır.

Bu yöntem, servis kimliğini (.ejo) ve sık değişen pipeline'ı ayrı dosyalarda tutmanızı ve CODEOWNERS ile ayrı ayrı korumanızı sağlar.

Satır içi pipeline#

name: web
owner: team-web
environment: staging
pipeline:
  name: web
  steps:
    - name: Testler
      kind: SHELL
      image: node:20-alpine
      config:
        command: npm ci && npm test

Satır içi pipeline ejo.yaml ile aynı şemayı kullanır ve binding kurulurken bir kerelik başlangıç pipeline'ı olarak yayınlanır. Sonraki değişiklikleri konsoldan yaparsınız.

Otomatik binding#

Varsayılan olarak .ejo yalnızca kataloğu besler; binding'i siz kurarsınız. EJO'nun binding'i kendisi kurmasını isterseniz:

1. Ayarlar > Organizasyon sayfasında .ejo'dan binding oluştur seçeneğini açın.
2. Otomatik binding'e açık environment'lar listesinden EJO'nun binding kurabileceği environment'ları seçin.

Bir sonraki taramada, pipeline'ı olan ve binding'i olmayan her repo için EJO environment: alanındaki (yoksa tek) environment'a bir binding kurar ve pipeline'ı repo adıyla yayınlar. Aynı adlı bir pipeline varsa üzerine yazılmaz; sebep Kaynaklar sayfasında yazar. Var olan binding'lere dokunulmaz. Her otomatik binding audit log'a yazılır.

İpucu: Binding'den önce geçerli bir .ejo iste seçeneği açıkken, taramanın geçerli bir .ejo okumadığı repo'lar için elle veya blueprint ile binding kurulamaz.

Preview ayarları#

preview:
  enabled: true          # binding'de PR preview'ı açar (PR trigger'ı da açılır)
  label: preview         # yalnızca bu label'ı taşıyan PR'lar preview alır; boş = her PR
  health_path: /healthz  # preview'ın hazır sayılması için istek atılan yol

Yalnızca yazdığınız anahtarlar binding'e uygulanır; yazmadıklarınız konsolda seçildiği gibi kalır. label en fazla 64 karakter olabilir, virgül veya tırnak içeremez. health_path / ile başlamalı ve boşluk içermemelidir. Ayrıntılar: Preview'lar.

Deploy verification check'leri#

Environment'ta deploy verification açıksa, servis kendi check'lerini ekleyebilir:

verify:
  - name: hata-orani
    environment: production
    type: prometheus
    query: sum(rate(http_requests_total{service="{{.Service}}",code=~"5.."}[5m]))
    comparator: "<"
    threshold: 0.5
  - name: health
    type: http
    url: https://web.example.com/healthz
    expect_status: 200

• type yazılmazsa query varsa prometheus, url varsa http kabul edilir.
• Prometheus check'leri comparator (<, <=, >, >=) ve sayısal threshold ister.
• HTTP check'leri http:// veya https:// ile başlayan bir url ve 100-599 arası expect_status ister.
• environment boşsa check her environment'ta uygulanır.
• query ve url içinde {{.Service}}, {{.Environment}}, {{.Namespace}}, {{.Deployment}}, {{.CommitSHA}} ve {{.ImageDigest}} kullanılabilir.

Ayrıntılar: Deploy verification ve rollback.

Belgeler, API'ler ve on-call#

docs:
  - docs/runbook.md
  - title: Mimari kararlar
    path: adr/0001.md
provides:
  - name: web-api
    spec: openapi.yaml
consumes:
  - api: payments-api
    service: payments
    version: "2"
oncall:
  pagerduty_service: P1A2B3C

• docs yalnızca repo'daki Markdown (.md) dosyalarını kabul eder. Bir girdi düz bir yol ya da {title, path} olabilir; bir belgeyi runbook olarak işaretlemek için runbook: true ekleyin.
• provides[].name ve consumes[].api küçük harf, rakam, ., _ ve - içerebilir.
• oncall için pagerduty_service (örneğin P1A2B3C) veya opsgenie_team alanlarından en az biri gerekir.

Tam örnek#

name: web
description: Acme web arayüzü
owner: group:team-web
environment: staging
pipeline:
  file: ci/ejo.yaml
preview:
  enabled: true
  label: preview
  health_path: /healthz
metrics:
  ignore:
    - docs/
    - "*.snap"
supply_chain:
  auto_scan: true
verify:
  - name: health
    type: http
    url: https://web.example.com/healthz
    expect_status: 200
docs:
  - docs/runbook.md

Sonraki adımlar#

• Pipeline tanımı
• Trigger'lar ve binding'ler
• Preview'lar