VCS Integration

This extension integrates Version Control Systems (VCSs), such as GitHub, with iTop. Based on events triggered by repositories hosted on VCSs, it runs user-defined automations that transfer valuable and relevant information linked to these repositories directly to iTop objects such as tickets or CIs.

The extension may be used in conjonction with Software and Release management (restricted to Combodo's customers) or any other extension that deals with source code repositories.

This wiki page is compound of 2 wiki pages (this one and the configuration page).

VCS integration allows:

• Modelization of VCS repositories,
• Automations to run upon the reception of events triggered by a VCS,
• Synchronization of the repositories defined in iTop with the real ones hosted on the VCS in order to maintain webhooks' configuration in an operational state,
• Creation of custom automations.

For the time being, the extension only provides integration with GitHub.

Only repository webhooks are taken into consideration. More information on the different webhooks available on GitHub can be found here.

Regardless of the process (manual or automatic) that is applied to synchronize repositories, the VCS will require that appropriate rights be defined:

• On GitHub, rights will be required to configure Webhooks attached to repositories, as described here.

• On GitHub, iTop will be asked to authenticate itself to use the REST API with either:
  • a Personal Access Token
  • or an Application ID / Private key pair.

Furthermore, some autorisations will be required for iTop on:

• 🔒Contents: repository contents, commits, branches, downloads, releases, and merges.
• 🔒Webhooks: to manage a repository's post-receive hooks.

Use the Standard installation process for this extension.

Configuring Github integration requires several steps.
Find the configuration steps using App Authentication by clicking this dedicated page.

This extension enables R&D teams to automatically send VCS tool's information on triggered event to iTop.

R&D will work on VCS tool (only Github for the moment).
On events triggered by GitHub, information will be sent to iTop's Automations.

Here are some events triggered by GitHub:

By default, two automated systems are included in the extension.

• VCSLogAttributeAutomation
  • Insert a message, based on the data provided by the VCS WebHook, in the attribute of an iTop object (Case Log or Text of a User Request, for instance)
  • A regular expression can be used to retrieve the destination object reference (such as the ticket reference contained in the commit reference).
• VCSLogJournalAutomation
  • Insert a message, based on the data provided by the VCS WebHook, in iTop log file (<itop>/log/error.log)

Users may develop and bring their own automation, based on the framework provided by the extension.

For instance, R&D can decide to

• automatically send comments on each commit to corresponding iTop ticket (UserRequest, UserStory if you installed Software and Release management or any itop ticket) using VCSLogAttributeAutomation.
  

• document iTop error.log file for each specific action on Github using VCSLogJournalAutomation.
  

The entry point for handling it is a new submenu of the standard Configuration menu which will display a dashboard of different classes representing VCS objects and predefined automation.

The following image shows the various classes provided by the extension and their relationships.

This model does not contain any classes representing VCS objects, such as commits or pull requests.

The extension brings with it the new “VCS Manager” profile, which has full rights on all classes brought by the extension and the Document class, as well as read rights on other groups.

A connector holds the connection informations that are required to automate configuration tasks.

If you need more step by step configuration information, go to dedicated connector's configuration section.

(*) The mandatory nature of the attribute actually depends on the Authentication mode value. See below.

From the general Configuration menu, open the VCS management sub menu and click on the of the Connector badge to display the creation form.

According to the selected value for the Authentication mode, the attributes that are relevant for this mode become mandatory :

This class modelizes repositories of Version Control Systems (VCS). The actual VCS used (GitHub, …) is implicitely defined by the provider of the connector attached to the repository.

If you need more step by step configuration information, go to dedicated repository's configuration section.

From the general Configuration menu, open the VCS management sub menu and click on the of the Repository badge to display the creation form.

Synchronizing a repository will make sure that information is up-to-date, proactively detects potential issues and keeps the repository in a good working order. To activate this feature, you need to create a GitHub connector. The Synchronization status of the repository will highlight the status of the last synchronization :

• Synchronization is functional, webhooks are active on GitHub and correctly received.
• Synchronization is functional but webhooks are deactivated on GitHub .
• Repository is not synchronized and no webhook is correctly received.
• Synchronization is not working. Connection information of the connector must be verified.

When synchronized, additional information will be displayed on the detailed presentation of the repository, under the Properties tab. That information is updated at the time of synchronization.

Manual synchronization is launched through the Synchronize repository action available in the Other actions menu. It can be checked with the Check synchronization action.

Under such configuration, the synchronization is automatically verified on a daily basis. The default periodicity can be modified using the synchro_auto_interval configuration parameter.

Events related to a repository that are processed by automation engines are recorded in the Events log of the repository. The number of automations triggered by the event is indicated in the log.

As usual with iTop, you may link a person to a user account. Once this operation has been performed, the logs are referenced to the person's name and no longer to the user account.

Automation objects drive the execution of tasks upon reception of events from repositories. The data provided by the events is processed in accordance with what they are been requested, for example: log a message, create an object in iTop, send a mail…

All automation objects rely on a common set of parameters held by the VCSAutomation abstract class.

This topology class defines possible events of provider.
This extension fills several events for Github provider : Create, Delete, Push, Issues, Pull Request, Milestone, Fork.

Automations are linked to repositories through a n:n relation. A few attributes carried by the link specify how the automation should behave for the repository.

By default, two automated functions are integrated into the extension. Both build messages based on data contained in events triggered by the repository webhooks and store these messages, one in an object's attribute and the other one in the error log file. Messages are built through templates that can be defined with the templating engine provided by the extension.

This automation logs a message into an object's attribute.

To activate this automation, a target object of class Object class must be identified using the data contained in the event received.

Example:
Let's suppose we want to fill the case log attribute of a User Request with the commit message made on a repository.

• Within the Automation fieldset:
  • Define the events and scope that you are expected
• Within the Target of the Message fieldset:
  • Specify the target class : User Request
  • Select the object's attribute in which to search for the reference extracted from the payload to match iTop object : Ref
  • Select the target attribute you will fill : private_log
  • Define the part of the webhook payload containing your reference: message
  • Define your regex to extract the target object reference and the variable where to look for it : (R-\d{6})

This automation logs a message into the <itop>/log/error.log file.

The message is built based on a template that is applied on events data.

In addition to the two automation classes provided by the extension, custom classes can also be created. To do this, the new VCSAutomation daughter classes must extend the abstract VCSAutomation class, with :

• The set of specifc attributes required to perform the automation,
• An implementation of the HandleEvent method.

abstract public function HandleEvent($sEvent, $aPayload, $context = []);

which parameters are:

• $sEvent : source event,
• $aPayload : event's data embedded in the webhook's payload,
• $context : data related to the specified perimeter, if any.

More information on the data provided by GitHub events can be found here.

You can create your own templates in raw text format or HTML format for a better layout.

These are the ones included in the webhook layout as well as in the source event.

• Reference data with double square brackets,
• Use expressions with arrows to access data in depth.

Examples:
Display the sender's login

[[sender->login]]

Inject the source event

[[event]]

• Iterator: loop over an array of elements and inject the data of each event.

Examples:
Display the message and ID of every commit made through a PUSH

[[for commits]]
   [[message]] - [[id]]
[[endfor]]

• Hyperlink: insert an hyperlink in a message and give it a label

[[@hyperlink url]]

[[@hyperlink url as label]]

• eMail link: insert a mailto to the message and give it a label

[[@mailto email]]

[[@mailto email as label]]

• Images: insert an image within the message and define its size

[[@image url]]

[[@image url size]]

• Split: split a string

[[@substring offset taille]]

This template can be used with the PUSH event.

<strong>[[event]]</strong> event form GitHub !

[[@image context->repository->owner->avatar_url 32]] [[@mailto committer->email as committer->username]]

<a href="[[url]]" target="_blank" style="font-size:1.5rem;">#[[@substring id 0 6]]</a> on 🌵 [[context->ref]]
[[message]]

[[@hyperlink context->compare as compare on GitHub]]

Q: On iTop caselog, when I click on Github commit link, I get the error 404
A: On the same case log, you may receive Github commits from differents repositories with differents logins (if you have multiple logins on Github). Your browser records a Github login aand it may not be the right one to access this repository.
You'll need to log out of Github and log in with the correct credentials.