Bu belge, Workcube WEX (Workcube Extension) kullanarak Bitbucket pull request olaylarını Workcube sistemine entegre etmek için bir API/Webhook çözümünü açıklamaktadır. Bu entegrasyon, geliştirme süreçlerinizdeki pull request hareketliliğini Workcube içerisine otomatik olarak taşıyarak iş süreçlerinizin takibini kolaylaştırır ve proje yönetimini zenginleştirir.

Genel Bakış

Bu WEX bileşeni, Bitbucket'tan gelen Pull Request olaylarını dinleyerek, ilgili verileri Workcube veritabanına kaydetmek üzere tasarlanmıştır. Bu sayede, Bitbucket üzerinde açılan, güncellenen veya kapatılan her bir Pull Request için Workcube içerisinde otomatik olarak ilgili bilgilere erişilebilir hale gelinir.

Amaç: Bitbucket'tan gelen Pull Request verilerini işleyip, Workcube'daki ilgili task ID'lerine bağlamak veya genel bir kayıt olarak tutmak.
Teknoloji: ColdFusion (CFML) ile geliştirilmiş bir Workcube Extension (WEX) bileşenidir.
Çalışma Şekli: Bitbucket repository ayarlarında tanımlanan Webhook üzerinden tetiklenir. Bitbucket'tan bir Pull Request olayı geldiğinde, bu WEX bileşenine bir HTTP POST isteği gönderilir ve gelen JSON payload'u işlenir.

API Uç Noktası (Endpoint) Bilgileri

Bitbucket Webhook ayarlarınızda kullanmanız gereken Workcube WEX uç noktası aşağıdaki gibidir:

URL:/WEX/bitbucket.cfc?method=ap (Bu URL, Workcube kurulumunuzun kök dizinine göre belirlenir ve sunucu adını içermez. Örneğin: https:yourworkcube.com/WEX/bitbucket.cfc?method=ap)
Metot:POST
İçerik Tipi (Content-Type):application/json

Gereksinimler

Workcube sisteminizde WEX (Workcube Extension) modülünün kurulu ve aktif olması gerekmektedir.
Bu dokümanda bahsedilen WEX bileşeninin (WEX/bitbucket.cfc) ve bağımlı bileşenlerin (örneğin WEX.bitbucket.components.data) Workcube sunucunuzda konuşlandırılmış olması gerekmektedir.
Bitbucket repository'nizde "Webhooks" ayarları altında bu uç noktanın doğru şekilde yapılandırılması gerekmektedir. Özellikle "Pull Request" olaylarının seçili olduğundan emin olun.

Çalışma Mantığı

WEX bileşeni, Bitbucket'tan gelen Pull Request payload'unu aşağıdaki adımlarla işler:

Bitbucket, bir Pull Request olayı tetiklendiğinde (oluşturma, güncelleme, birleştirme vb.), belirlenen WEX uç noktasına bir HTTP POST isteği gönderir. Bu isteğin gövdesi (body) JSON formatında Pull Request bilgilerini içerir.
ap fonksiyonu, gelen JSON verisini (data argümanı) alır.
Veride pullrequest anahtarının olup olmadığını kontrol eder. Eğer varsa, Pull Request'e özel işleme fonksiyonu olan pullrequest fonksiyonunu çağırır.
pullrequest fonksiyonu, gelen JSON verisinden aşağıdaki bilgileri ayrıştırır ve ilgili değişkenlere atar:
- Başlık: Pull Request'in başlığı.
- Açıklama: Pull Request'in HTML formatındaki açıklaması.
- Task ID: Pull Request başlığından veya açıklamasından # işareti ile başlayan rakamlar (örn: #12345) formatında bir Workcube Task ID'si aranır. Eğer bulunursa bu ID eşleştirilir.
- Görüntüleme URL'si: Bitbucket üzerindeki Pull Request'i görüntülemek için kullanılan URL.
- Yazar Bilgileri: Pull Request'i oluşturan kullanıcının adı ve diğer detayları.
- Oluşturulma Tarihi: Pull Request'in oluşturulma zamanı.
- Bitbucket PR ID: Bitbucket'ın bu Pull Request'e atadığı benzersiz kimlik.
- Hedef Dal (Destination Branch): Pull Request'in birleştirileceği hedef dalın adı.
- Kaynak Dal (Source Branch): Pull Request'in geldiği kaynak dalın adı.
- Durum (State): Pull Request'in mevcut durumu (örn: OPEN, MERGED, DECLINED).
- Katılımcılar: Pull Request'teki inceleyiciler veya diğer katılımcıların bilgileri.
Ayrıştırılan bu veriler, WEX.bitbucket.components.data bileşenindeki insert fonksiyonu çağırılarak Workcube veritabanına kaydedilir. Bu, entegrasyonun temel veri depolama adımıdır.
İşlem başarılı olursa, result(1) ile başarılı bir JSON yanıtı döndürülür. Herhangi bir hata oluşması durumunda, result(0, "", cfcatch) ile hata bilgileri içeren bir JSON yanıtı döner.
result fonksiyonu, tüm işlem sonuçlarını standart bir JSON formatında döndürmekle sorumludur.

Postman veya Benzeri Araçlarla Test Etme

Bu API'yi test etmek için Postman, Insomnia gibi REST istemcileri veya cURL kullanabilirsiniz. Aşağıdaki adımları takip ederek bir Pull Request olayını simüle edebilirsiniz:

Metot:POST olarak seçin.
URL: Workcube WEX uç noktasını (örneğin: https://yourworkcube.com/WEX/bitbucket.cfc?method=ap) girin.
Headers:Content-Type başlığını application/json olarak ayarlayın.
Body: Bitbucket'tan gelen gerçek bir Pull Request JSON payload'ını kullanın. Aşağıda basit bir örnek verilmiştir. Not: Bu JSON, Bitbucket'ın gerçek payload'unun basitleştirilmiş bir versiyonudur. Detaylı ve tam bir payload için Bitbucket dökümantasyonuna bakınız veya gerçek bir webhook tetikleyerek yakalayınız.

Örnek Bitbucket Pull Request Payload (Basit)

{

"pullrequest": {

"id": 123,

"title": "Yeni Özellik: Workcube Task #9876",

"description": "Bu pull request yeni bir özellik eklemektedir. İlgili Task ID: #9876",

"state": "OPEN",

"created_on": "2023-10-27T10:00:00.000000+00:00",

"links": {

"html": {

"href": "https://bitbucket.org/your_repo/pull-requests/123"

}

},

"author": {

"display_name": "Geliştirici Adı"

},

"destination": {

"branch": {

"name": "master"

}

},

"source": {

"branch": {

"name": "feature/yeni-ozellik"

}

API Yanıtları

API çağrısının sonucunda dönecek olan JSON yanıtları aşağıdaki formatlarda olacaktır:

Başarılı Yanıt

İşlem başarılı bir şekilde tamamlandığında:

{

"status": 1

}

Hatalı Yanıt

İşlem sırasında bir hata oluştuğunda:

{

"status": 0,

"message": "Hata mesajı burada yer alacaktır.",

"obj": {

"detail": "Hata detayları",

"type": "Hata Tipi"

}

Güvenlik Notları

Webhook uç noktanızın güvenliğini sağlamak için aşağıdaki yöntemleri göz önünde bulundurmanız önerilir:

Webhook URL'nizi sadece Bitbucket'ın erişebileceği şekilde kısıtlayın (örn: firewall ile IP kısıtlamaları).
Bitbucket webhook'ları için bir "secret token" tanımlayarak, gelen isteğin Bitbucket'tan geldiğini doğrulayabilirsiniz. Bu token'ı WEX bileşeninizde doğrulayacak ek bir mekanizma geliştirebilirsiniz.
Hassas bilgileri doğrudan URL parametrelerinde göndermekten kaçının.

Geri Bildirim

Bu içeriği faydalı buldunuz mu?

Geri Bildirimizi Lütfen Yazınız!

Ad*

Soyad*

E-posta *