Git
Chapters ▾ 2nd Edition

6.4 GitHub - GitHub’ı otomatikleştirme

GitHub’ı otomatikleştirme

Şimdi GitHub’ın tüm önemli özelliklerini ve iş akışlarını ele aldık, ancak büyük bir grup veya projenin her zaman yapabileceği özelleştirmeler veya eklemek isteyebileceği harici hizmetler olacaktır.

Neyse ki, GitHub birçok yönden oldukça esnek. Bu bölümde, GitHub’ın kanca (hook) sistemi ve API’sini nasıl kullanacağımızı ve GitHub’ı istediğimiz gibi çalıştırmak için nasıl kullanabileceğimizi ele alacağız.

Kancalar ve Hizmetler (Hooks and Services)

GitHub repo yönetiminin "Hooks and Services" (Kancalar ve Hizmetler) bölümü, GitHub’ı harici sistemlerle etkileştirmenin en kolay yoludur.

Hizmetler (Services)

Öncelikle Hizmetlere bir göz atalım. Kancalar ve Hizmetler entegrasyonlarını, reponuzun - daha önce ortak eklemeyi ve projenizin varsayılan dalını değiştirdiğimiz yer olan- "Settings" (Ayarlar) bölümünde bulabilirsiniz. ``Webhooks and Services`` (ağ Kancaları ve Hizmetler) sekmesi altında Hizmetler ve Kancalar yapılandırma bölümü. gibi bir şey göreceksiniz.

Hizmetler ve kancalar
Görsel 129. Hizmetler ve Kancalar yapılandırma bölümü.

Çoğu diğer ticari ve açık kaynak sistemlere entegrasyon sunan onlarca hizmet arasından dileğinizi seçebilirsiniz. Bunların çoğu, daimi entegrasyon hizmetleri, hata ve sorun izleyicileri, sohbet odası sistemleri ve belgeleme sistemleri içindir. Şimdi bunlar içerisinden, çok basit bir hizmet olan E-posta kanca hizmetini kurmayı göstereceğiz. Eğer ``Add Service`` (Hizmet Ekle) açılır menüsünden ``email`’i seçerseniz, karşınıza E-posta hizmet yapılandırması. gibi bir yapılandırma ekranı çıkar.

E-posta hizmeti
Görsel 130. E-posta hizmet yapılandırması.

Burada ``Add service`` (Hizmet ekle) düğmesine basarsak, birisi repomuza her itme yaptığında belirttiğimiz e-posta adresine bir e-posta gelir. Hizmetler birçok farklı türde etkinlik dinleyebilir, ancak çoğu yalnızca itme etkinliklerini dinler ve ardından bu verilerle bir şeyler yapar.

Eğer GitHub ile entegre etmek istediğiniz bir sistem varsa, burada mevcut bir servis entegrasyonu olup olmadığını kontrol etmelisiniz. Örneğin, kod tabanınızda testleri çalıştırmak için Jenkins kullanıyorsanız, Jenkins’in yerleşik hizmet entegrasyonunu etkinleştirerek, biri reponuza itme yaptığında bir test çalıştırabilirsiniz.

Kancalar (Hooks)

Eğer daha belirli bir ihtiyacınız varsa veya bu listede bulunmayan bir servis veya siteyle entegre olmak istiyorsanız, daha genel kancaları kullanabilirsiniz. GitHub repo kancaları oldukça basittir. Bir URL belirtirsiniz ve GitHub istediğiniz herhangi bir etkinlikte o URL’ye bir HTTP yükü (payload) gönderir.

Bu genellikle, GitHub kancası yükünü dinlemesi için küçük bir ağ hizmeti kurulması ve veri alındığında onunla bir şeyler yapması şeklinde çalışır.

Bir kancayı etkinleştirmek için Hizmetler ve Kancalar yapılandırma bölümü.'daki ``Add webhook`` (ağ kancası ekle) düğmesine tıklarsınız. Bu sizi Ağ kancası yapılandırması. gibi bir sayfaya götürecektir.

Ağ kancası
Görsel 131. Ağ kancası yapılandırması.

Bir ağ kancasını yapılandırmak çok basittir. Çoğu durumda, sadece bir URL ve bir gizli anahtar girip, ardından ``Add webhook`` (Webhook ekle) düğmesine tıklarsınız. GitHub’ın size bir yük göndermesini istediğiniz olaylar için birkaç seçenek vardır. Varsayılan olarak, yalnızca birisi herhangi bir repo dalına yeni bir kod ittiğinde bir yük alacağınız push (itme) olayıdır.

Bir ağ kancasını yönetmek üzere ayarlayabileceğiniz bir ağ hizmetinin küçük bir örneğini görelim. Oldukça kısa olduğundan ve ne yaptığımızı kolayca anlayabilmeniz gerektiğinden, Ruby ağ çerçevesi (framework) Sinatra’yı kullanacağız.

Diyelim ki, belirli bir kişinin, belirli bir dosyayı değiştirerek, belirli bir dala ittiğinde bir e-posta almak istiyoruz. Bunu aşağıdaki gibi bir kodla çok kolay bir şekilde yapabiliriz:

require 'sinatra'
require 'json'
require 'mail'

post '/payload' do
  push = JSON.parse(request.body.read) # parse the JSON

  # gather the data we're looking for
  pusher = push["pusher"]["name"]
  branch = push["ref"]

  # get a list of all the files touched
  files = push["commits"].map do |commit|
    commit['added'] + commit['modified'] + commit['removed']
  end
  files = files.flatten.uniq

  # check for our criteria
  if pusher == 'schacon' &&
     branch == 'ref/heads/special-branch' &&
     files.include?('special-file.txt')

    Mail.deliver do
      from     'tchacon@example.com'
      to       'tchacon@example.com'
      subject  'Scott Changed the File'
      body     "ALARM"
    end
  end
end

Burada GitHub’ın bize sunduğu JSON verisini alıp; kimin ittiğini, hangi dalı ittiğini ve hangi dosyaların değiştirildiğini kontrol ediyoruz. Ardından, yukarıdaki kriterlere göre kontrol edip, eşleşiyorsa bir e-posta gönderiyoruz.

Böyle bir şey geliştirmek ve test etmek için, kancayı kurduğunuz ekranda güzel bir geliştirici konsolunuz bulunur. GitHub’ın bu kanca için dağıtmaya çalıştığı son birkaç teslimatı görebilirsiniz. Her kanca için: ne zaman teslim edildiğini, başarılı olup olmadığını, istek ve yanıtın gövdesini ve başlıklarını inceleyebilirsiniz. Bu, kancalarınızı test etmeyi ve hataları ayıklamayı (debug) inanılmaz derecede kolaylaştırır.

Ağ kancası hata ayıklama
Görsel 132. Ağ kancası hata ayıklama bilgileri.

Bunun diğer bir harika özelliği, hizmetinizi kolayca test etmek için yüklerden herhangi birini yeniden gönderebilmenizdir.

Web kancalarının nasıl yazılacağı ve dinleyebileceğiniz tüm farklı olay (event) türleri hakkında daha fazla bilgi için [GitHub Geliştirici belgelerine](https://developer.github.com/webhooks/) bakabilirsiniz.

GitHub API

Hizmetler ve kancalar, repolarınızda gerçekleşen olaylar hakkında bildirim almanızı sağlar, ancak ya bu olaylar hakkında daha fazla bilgiye ihtiyacınız varsa! Örneğin, projeye çalışma arkadaşı veya konulara etiket eklemek gibi bir şeyi otomatikleştirmeniz gerekiyorsa ne yapacaksınız?

İşte GitHub API’sinin devreye girdiği yer burasıdır. GitHub, hemen hemen ağ sayfasındaki neredeyse her şeyi otomatikleştirebileceğiniz birçok API uç noktasına sahiptir. Bu bölümde, API’ye kimlik doğrulama yapmayı, API’ye bağlanmayı, bir konuya yorum yapmayı ve bir birleştirme isteğinin durumunu değiştirmeyi öğreneceğiz.

Temel Kullanım

Yapabileceğiniz en temel şey, bir uç noktada kimlik doğrulaması gerektirmeyen basit bir GET isteğidir. Bu, bir kullanıcı veya açık kaynaklı bir projedeki salt-okunur bilgiler olabilir. Örneğin, ``schacon`` adlı bir kullanıcı hakkında daha fazla bilgi edinmek istiyorsak, şöyle bir şey çalıştırabiliriz:

$ curl https://api.github.com/users/schacon
{
  "login": "schacon",
  "id": 70,
  "avatar_url": "https://avatars.githubusercontent.com/u/70",
# …
  "name": "Scott Chacon",
  "company": "GitHub",
  "following": 19,
  "created_at": "2008-01-27T17:19:28Z",
  "updated_at": "2014-06-10T02:37:23Z"
}

GitHub üzerinde görebileceğiniz - herkese açık olarak yayınlanan - neredeyse her şey (topluluklar, projeler, konular, katkılar, vs) hakkında bilgi alabileceğiniz, buna benzer birçok uç nokta bulunmaktadır. API’yi kullanarak keyfinize göre bir Markdown oluşturabilir veya bir .gitignore şablonu bulabilirsiniz.

$ curl https://api.github.com/gitignore/templates/Java
{
  "name": "Java",
  "source": "*.class

# Mobile Tools for Java (J2ME)
.mtj.tmp/

# Package Files #
*.jar
*.war
*.ear

# virtual machine crash logs, see https://www.java.com/en/download/help/error_hotspot.xml
hs_err_pid*
"
}

Bir Konuda Yorum Yapmak

Ancak, bir konu ya da birleştirme isteğine yorum yapmak veya özel içeriği görüntülemek ya da onla etkileşime girmek gibi bir işlem yapmak istiyorsanız, kimlik doğrulaması yapmanız gerekecektir.

Kimlik doğrulamanın birkaç yolu vardır. Sadece kullanıcı adı ve şifrenizle temel kimlik doğrulaması yapabilirsiniz, ancak kişisel bir erişim jetonu kullanmak genellikle daha iyidir. Bunu, "Ayarlar" (Settings) sayfanızın "Uygulamalar" (Applications) sekmesinden oluşturabilirsiniz.

Erişim jetonu
Görsel 133. Ayarlar sayfanızın "Uygulamalar" sekmesinden erişim jetonu oluşturmak.

Size bu jetonu ne amaçla kullanmak istediğiniz sorulup, bir açıklama beklenecek. Betiğiniz veya uygulamanız artık kullanılmadığında, jetonu kafanız rahat bir şekilde kaldırabilmek için, bu jetonu neden oluşturduğunuza dair iyi bir açıklama yazdığınızdan emin olun.

GitHub bu jetonu yalnızca bir kez gösterecektir, bu nedenle onu kopyaladığınızdan emin olun. Bunu betik veya uygulamanızda kullanarak kimliğinizi doğruladığınız taktirde artık kullanıcı adı ve şifre kullanmak zorunda kalmayacaksınız. Bunun güzel yanı, kullanım kapsamını sınırlayabilir veya istediğinizde iptal edebilirsiniz.

Bu yöntem ayrıca, istek sınırınızı artırmak gibi ek bir avantaja da sahiptir. Kimlik doğrulamasız, saatte 60 istekle sınırlanırsınız ama kimlik doğruladığınızda saatte 5.000 istek yapabilirsiniz.

Hadi bunu bir konuya yorum yapmak için kullanalım. Diyelim ki belirli bir konuya (konu #6 diye adlandıralım) bir yorum bırakmak istiyoruz. Bunu yapmak için yeni oluşturduğumuz jetonu bir yetkilendirme başlığı olarak kullanarak repos/<user>/<repo>/issues/<num>/comments adresine bir HTTP POST isteği yapmamız gerekecek.

$ curl -H "Content-Type: application/json" \
       -H "Authorization: token TOKEN" \
       --data '{"body":"A new comment, :+1:"}' \
       https://api.github.com/repos/schacon/blink/issues/6/comments
{
  "id": 58322100,
  "html_url": "https://github.com/schacon/blink/issues/6#issuecomment-58322100",
  ...
  "user": {
    "login": "tonychacon",
    "id": 7874698,
    "avatar_url": "https://avatars.githubusercontent.com/u/7874698?v=2",
    "type": "User",
  },
  "created_at": "2014-10-08T07:48:19Z",
  "updated_at": "2014-10-08T07:48:19Z",
  "body": "A new comment, :+1:"
}

Şimdi bu konuya giderseniz, az önce başarıyla yayınladığımız yorumu GitHub API’den gönderilen bir yorum. olarak görebilirsiniz.

API Yorumu
Görsel 134. GitHub API’den gönderilen bir yorum.

GitHub API’sini web sitesinde yapabileceğiniz hemen hemen her şeyi yapmak için kullanabilirsiniz: kilometre taşları oluşturma ve ayarlama, insanları görevlere ve birleştirme isteklerine atama, etiketler oluşturma ve değiştirme, katkı verilerine erişme, yeni katkı ve dallar oluşturma, birleştirme istekleri açma/kapatma veya birleştirme, takımlar oluşturma ve düzenleme, birleştirme isteğindeki kod satırlarına yorum yapma, siteyi arama yapma ve çok daha fazlası.

Birleştirme İsteğinin Durumunu Değiştirmek

Son olarak, birleştirme istekleriyle çalışıyorsanız oldukça yararlı olan bir örnek daha inceleyeceğiz. Her bir işlem, bir veya daha fazla durumla ilişkilendirilebilir; bu durumları eklemek ve sorgulamak için bir API bulunmaktadır.

"Sürekli Entegrasyon" ve test hizmetlerinin çoğu, kodun test edilmesi için yapılan itmelere (push) tepki vermek için bu API’yi kullanır ve ardından bu işlemin tüm testleri geçip geçmediğini bildirir. Siz bu API ile, katkı mesajının uygun şekilde biçimlendirilip biçimlendirilmediğini, göndericinin sizin katkı rehberinize uyup uymadığını, katkının geçerli şekilde imzalanıp imzalanmadığını, vb bir çok şeyi kontrol etmek için kullanabilirsiniz.

Örneğin reponuzda, "katkı mesajında Signed-off-by dizesi olup olmadığını kontrol eden bir ağ hizmetine" erişen bir ağ kancası kurduğunuzu varsayalım.

require 'httparty'
require 'sinatra'
require 'json'

post '/payload' do
  push = JSON.parse(request.body.read) # parse the JSON
  repo_name = push['repository']['full_name']

  # look through each commit message
  push["commits"].each do |commit|

    # look for a Signed-off-by string
    if /Signed-off-by/.match commit['message']
      state = 'success'
      description = 'Successfully signed off!'
    else
      state = 'failure'
      description = 'No signoff found.'
    end

    # post status to GitHub
    sha = commit["id"]
    status_url = "https://api.github.com/repos/#{repo_name}/statuses/#{sha}"

    status = {
      "state"       => state,
      "description" => description,
      "target_url"  => "http://example.com/how-to-signoff",
      "context"     => "validate/signoff"
    }
    HTTParty.post(status_url,
      :body => status.to_json,
      :headers => {
        'Content-Type'  => 'application/json',
        'User-Agent'    => 'tonychacon/signoff',
        'Authorization' => "token #{ENV['TOKEN']}" }
    )
  end
end

Umarım kolayca takip edebilirsin. Bu web kancası işleyicisinde, yeni işlenen her katkıyı inceleyerek, katkı mesajında Signed-off-by dizesini arıyoruz ve son olarak durumu (status) belirtmek için HTTP aracılığıyla /repos/<user>/<repo>/statuses/<commit_sha> API uç noktasına POST gönderiyoruz.

Burada, bir durum (success, failure, error), ne yapıldığına ilişkin bir açıklama, kullanıcının daha fazla bilgi almak için gidebileceği bir hedef URL ve tek bir katkı için birden fazla durum (status) olması durumunda da bir ``bağlam`` (context) gönderebilirsiniz. Örneğin, bir test hizmeti de veya bunun gibi bir doğrulama hizmeti de bir durum sağlayabilir; "bağlam" (context) alanı onların nasıl farklılaştırıldığını gösterir.

Eğer birisi GitHub’da yeni bir birleştirme isteği açarsa ve bu kanca kurulmuşsa, API üzerinden katkı durumu. gibi bir şey görebilirsiniz.

Katkı durumu
Görsel 135. API üzerinden katkı durumu.

Artık, mesajında ``Signed-off-by`` dizesi bulunan katkının yanında küçük yeşil bir onay işareti görünürken, yazarın imzalamayı unuttuğu katkının yanında ise kırmızı bir çarpı işareti bulunduğunu görebilirsiniz. Ayrıca, birleştirme isteğinin, daldaki son katkıyla aynı durum kodunu taşıdığını ve başarısızlık durumunda sizi uyardığını görebilirsiniz. Eğer bu API’yi test sonuçları için kullanıyorsanız, testleri geçemeyen bir katkıyı yanlışlıkla birleştirmenizi engelleyeceği için, bu çok kullanışlıdır .

Octokit

Bu örneklerde neredeyse her şeyi curl ve basit HTTP istekleri aracılığıyla yapmamıza rağmen, bazı açık kaynaklı kütüphaneler bu API’yi daha kendine özgü bir şekilde kullanmaktadır. Bu yazının kaleme alındığı sırada desteklenen diller arasında Go, Objective-C, Ruby ve .NET de bulunmaktadır. HTTP işlemlerinin birçoğunu sizin için halleden bu kütüphane hakkında daha fazla bilgi için https://github.com/octokit adresine bakabilirsiniz.

Umarım bu araçlar, GitHub’ı özelleştirerek, size özel iş akışlarının daha iyi çalışmasını sağlamanıza yardımcı olur. Yaygın görevler için kılavuzlar ve API hakkında daha detaylı belgeler için https://developer.github.com adresine göz atabilirsiniz.

scroll-to-top