Extend Gitlab with Webhooks

Extend Gitlab with Webhooks

Markus Günther 12. February 2014 Expert Topics

5 Comments // Reading Time: 5 min.

In our last blog entry we already gave you a short introduction to Gitlab. Now you know which functions Gitlab offers you and we use at sgalinski Internet Services. I've also briefly explained how to install Gitlab and set up your first project. If you didn't read the last amount, just make up for it.

Today the webhook is our topic. In the last article I only mentioned it briefly in order to make up for it in more detail.

What are Webhooks?

"WebHooks (composed of "Web" and "Hook") is a non-standardized method of communication between servers that takes place within the framework of distributed computing or message-oriented middleware. WebHooks make it possible to inform a server software that a certain event has occurred and to trigger a reaction to the event. WebHooks are used as a simple callback procedure for data synchronization, external calculation, and data validation. Technically, an HTTP POST message is sent to a prepared URL that returns the requested data, and unlike SOAP, no additional transport layer is used, unlike RESTful messaging and the Atom Syndication format, WebHooks are not fixed to the XML format. WebHooks are mainly seen as an easy to implement solution to avoid excessive polling".
Source Wikipedia (11.02.2014)

Since version 2.7 you can use so-called system hooks in Gitlab. This was the first possibility to execute an action on the server for certain events in Gitlab, for example a shell script. With version 4.2 webhooks were introduced as well.

The first version of webhooks could only be triggered by a push event in a repository. To do this, you have to specify a URL in the Webhooks tab of the repository settings. This URL is called during a push.


Do you want to talk to web development specialists at eye level?

 


The call passes information about the last push. This data is in JSON format and looks like this:

{
   "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
}

Data: JSON Push Event 

With this data you can now do what you want and leave it as it is. The webhook calls up a URL and passes a JSON string. Thus there is no binding to a certain programming language for further processing.

We mainly use PHP and have written such a script to process the data further. But you can also use Ruby, Java, Perl, JavaScript or whatever you like.

Since version 6.2 two other types of triggers have been added. The webhook can now also be executed when creating a new ticket and a new merge request.

{
   "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
   }
}

Data: JSON Issue Event

As you can see, this JSON is different from the push event. So you either have to have different webhook scripts or consider this behavior with your webhook. In Gitlab both cases can be configured using the checkboxes.

Finally, an example of a 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."
   }
}

Data: JSON Merge Request Event

So it is quite easy to use a webhook. Besides the very easy configuration you only have to consider the type of trigger. Now you can use the received data to implement functions that you miss in Gitlab or to automatically fill other systems with new data.

Maybe you are using a CI system and want to check if your test is executed correctly with every push. But as already mentioned, basically you are completely free what you do with the information and therefore we learned to love the webhooks.

In another article we will show you an example of how we use Gitlab webhooks in practice. We will then make our example available to you in a public Gitlab repository.

Contact us!

We are a digital agency headquartered in Munich/Unterföhring, which works remotely worldwide. We are specialized in the development of digital products. Our core topics are websites and portals with TYPO3, eCommerce with Shopware and Android and iOS-Apps. In addition, we deal with many other topics in the field of web development. Feel free to contact us with your concerns!


5 Comments

  • Peter

    Peter

    at 18.10.2016

    Ich würde gerne eine GitLab Webhook Aufruf in PHP schreiben. Habt ihr einen Tipp für mich, wie man das am Besten testet, z.B. welcher Input im PHP Script ankommt? Testing per Browser funktioniert ja [...] Ich würde gerne eine GitLab Webhook Aufruf in PHP schreiben. Habt ihr einen Tipp für mich, wie man das am Besten testet, z.B. welcher Input im PHP Script ankommt? Testing per Browser funktioniert ja wohl nicht ;)

    Drop files here
  • Stefan Galinski

    Stefan Galinski

    at 18.10.2016

    Hi Peter,

    Wir haben einen Webhook in unserem Gitlab veröffentlicht. Eventuell hilft dir das ja schon einmal. Debuggen geht dann am Besten indem du XDebug nutzt oder die Debug-Ergebnisse in eine [...] Hi Peter,

    Wir haben einen Webhook in unserem Gitlab veröffentlicht. Eventuell hilft dir das ja schon einmal. Debuggen geht dann am Besten indem du XDebug nutzt oder die Debug-Ergebnisse in eine Datei umleitest. Du kannst bei der Webhooks-Ansicht ja Testcalls an den Webhook abfeuern, um stetig neue Tests fahren zu können.

    https://gitlab.sgalinski.de/gitlab/commit-webhook

    Drop files here
  • Peter

    Peter

    at 18.10.2016

    Danke für die Tipps! Danke für die Tipps!

    Drop files here
  • Peter

    Peter

    at 02.12.2016

    Der Link auf den vorhergehenden Blog-Eintrag ist "kaputt". Richtig ist: https://www.sgalinski.de/news/technik/einfuehrung-in-gitlab/ Der Link auf den vorhergehenden Blog-Eintrag ist "kaputt". Richtig ist: https://www.sgalinski.de/news/technik/einfuehrung-in-gitlab/

    Drop files here
  • Stefan Galinski

    Stefan Galinski

    at 02.12.2016

    Hi Peter, danke für den Hinweis. Ist angepasst. :-) Hi Peter, danke für den Hinweis. Ist angepasst. :-)

    Drop files here
Drop files here