Gitlab mit Webhooks erweitern

Gitlab mit Webhooks erweitern

Markus Günther 12. Februar 2014 Expert Topics

5 Kommentare // Lesezeit: 5 min.

In unserem letzten Blog-Eintrag haben wir euch schon eine kleine Einführung in Gitlab gegeben. Ihr wisst jetzt, welche Funktionen euch Gitlab bietet und wir bei sgalinski Internet Services nutzen. Des Weiteren habe ich kurz erläutert, wie ihr Gitlab installiert und euer erstes Projekt einrichtet. Falls ihr den letzten Betrag nicht gelesen habt, holt es doch einfach nach.

Heute ist der Webhook unser Thema. Ich bin im letzten Beitrag nur kurz darauf eingegangen, um dies nun ausführlicher nachzuholen.

Was sind Webhooks?

“Mit WebHooks (zusammengesetzt aus „Web“ und „Hook“) wird ein nicht-standardisiertes Verfahren zur Kommunikation von Servern bezeichnet, das im Rahmen des verteilten Rechnens oder der Nachrichtenorientierten Middleware stattfindet. WebHooks ermöglichen es, einer Server-Software mitzuteilen, dass ein bestimmtes Ereignis eingetreten ist und eine Reaktion auf das Ereignis auszulösen. WebHooks finden als einfaches Callback-Verfahren Verwendung zur Daten-Synchronisation, externen Berechnung und zur Daten-Validierung. Technisch wird dazu eine HTTP-POST-Message an eine dafür vorbereitete URL gesendet, welche die angeforderten Daten zurückliefert.Im Gegensatz zu SOAP wird keine zusätzliche Transportschicht verwendet, im Unterschied zu RESTful Messaging und dem Atom Syndication Format sind WebHooks nicht auf das XML-Format festgelegt. WebHooks werden vor allem als einfach implementierbare Lösung gesehen, um exzessives Polling zu vermeiden.”
Quelle Wikipedia (11.02.2014)

In Gitlab kann man seit der Version 2.7 sogenannte System Hooks verwenden. Das war die erste Möglichkeit, zu bestimmten Ereignissen in Gitlab eine Aktion auf dem Server auszuführen, beispielsweise ein Shell-Script. Mit der Version 4.2 wurden dann auch Webhooks eingeführt.

Die erste Version der Webhooks konnte nur bei einem Push-Event in einem Repository ausgelöst werden. Hierzu muss man in den Einstellungen des Repositories im Reiter Webhooks eine URL angeben. Diese URL wird bei einem Push aufgerufen.

Bei dem Aufruf werden Informationen zum letzten Push übergeben. Diese Daten sind im JSON-Format und sehen wie folgt aus:

{
   "before":"dc31e890f7dc82ac8dd978...",
   "after":"b13e2372455a8633ed2497f...",
   "ref":"refs/heads/master",
   "user_id":21,
   "user_name":"Markus Günther",
   "project_id":42,
   "repository":{
      "name":"Bethselamin",
      "url":"git@gitlab.domain.de/bethselamin.git",
      "description":"Test Projekt fuer die Gitlab Webhooks",
      "homepage":"http://gitlab.domain.de/bethselamin/"
   },
   "commits":[
      {
         "id":"b13e2372455a8633ed2497f680e904af67eb9fd4",
         "message":"[TASK] Update foo translation to bar",
         "timestamp":"2014-02-03T12:17:44+01:00",
         "url":"http://gitlab.domain.de/bethselamin/commit/b13e2372455a8633ed2497f680e904af67eb9fd4",
         "author":{
            "name":"Markus Günther",
            "email":"markus@sgalinki.de"
         }
      },
      {
         "id":"da1560886d4f094c3e6c9ef40349...",
         "message":"[BUGFIX] fixed readme",
         "timestamp":"2014-02-01T23:36:29+02:00",
         "url":"http://gitlab.domain.de/bethselamin/commit/da1560886d...",
         "author":{
            "name":"Markus Günther",
            "email":"markus@sgalinki.de"
         }
      }
   ],
   "total_commits_count":2
}

Daten: JSON-Push-Event 

Mit diesen Daten kann man nun salopp gesagt tun und lassen was man will. Der Webhook ruft eine URL auf und übergibt ein JSON-String. Somit besteht keine Bindung an eine bestimmte Programmiersprache bei der Weiterverarbeitung.

Wir nutzen vorrangig PHP und haben uns ein eben solches Script geschrieben, um die Daten weiter zu verarbeiten. Doch ihr könnt auch Ruby, Java, Perl, JavaScript oder was immer ihr mögt verwenden.

Seit der Version 6.2 sind noch zwei andere Arten von Triggern dazu gekommen. Der Webhook kann nun auch bei dem Anlegen eines neuen Tickets und eines neuen Merge-Requests ausgeführt werden.

{
   "object_kind":"issue",
   "object_attributes":{
      "id":205,
      "title":"TEST Webhook Issue Trigger",
      "assignee_id":null,
      "author_id":21,
      "project_id":42,
      "created_at":"2014-02-05T20:49:32.165Z",
      "updated_at":"2014-02-05T20:49:32.165Z",
      "position":0,
      "branch_name":null,
      "description":"",
      "milestone_id":null,
      "state":"opened",
      "iid":7
   }
}

Daten: JSON-Issue-Event

Wie man sehen kann, ist dieses JSON anders als beim Push-Event. Somit müsst ihr entweder verschiedene Webhook-Skripte haben oder dieses Verhalten bei eurem Webhook bedenken. In Gitlab können beide Fälle mit Hilfe der Checkboxen konfiguriert werden.

Abschließend noch ein Beispiel für einen Merge-Request.

{
   "object_kind":"merge_request",
   "object_attributes":{
      "id":1,
      "target_branch":"master",
      "source_branch":"blog",
      "source_project_id":42,
      "author_id":21,
      "assignee_id":null,
      "title":"Blog article merge",
      "created_at":"2014-02-05T21:10:03.680Z",
      "updated_at":"2014-02-05T21:10:03.680Z",
      "st_commits":null,
      "st_diffs":null,
      "milestone_id":null,
      "state":"opened",
      "merge_status":"unchecked",
      "target_project_id":42,
      "iid":1,
      "description":"This has to be merged for the blog article please."
   }
}

Daten: JSON-Merge-Request-Event

Es ist also recht einfach einen Webhook zu verwenden. Neben der sehr leichten Konfiguration muss man nur die Art des Triggers beachten. Ihr könnt nun die erhaltenen Daten nutzen, um euch Funktionen zu implementieren, welche ihr in Gitlab vermisst oder um andere Systeme automatisch mit neuen Daten zu befüllen.

Vielleicht nutzt ihr ein CI-System und wollt bei jedem Push prüfen, ob eurer Test korrekt ausgeführt wird. Doch wie schon angemerkt, grundsätzlich steht es euch vollkommen frei, was ihr mit den Informationen macht und daher haben wir die Webhooks lieben gelernt.

In einem weiteren Beitrag werden wir euch an einem Beispiel zeigen, wie wir Gitlab-Webhooks konkret verwenden. Unser Beispiel werden wir euch dann auch stilecht in einem öffentlichen Gitlab-Repository zur Verfügung stellen.


5 Kommentare

Dateien hier ablegen
Dateien hochladen