Sidebar

Combodo

iTop Extensions

VCS Integration

name:
VCS Integration
description:
Integrates VCS webhooks with iTop
version:
1.0.0
release:
2025-01-23
itop-version-min:
3.2
code:
combodo-vcs-integration
state:
stable
diffusion:
Client Store, iTop Hub
php-version-max:
PHP 8.x

This extension integrates Version Control Systems (VCSs), such as GitHub, with iTop. Based on events triggered by organizations on VCSs, it runs user-defined automations that transfer valuable and relevant information linked to the organisation 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/organisations.

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

Features

VCS integration allows:

  • Modelization of VCS webhooks with automatic GitHub configuration synchronization,
  • Automations to run upon the reception of events triggered by a VCS,
  • Creation of custom automations.

Revision History

Version Release Date Comments
1.0.0 2025-01-23 Organization webhooks, asynchronous webhooks handling
0.1.0 2024-09-10 First version

Limitations

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

Requirements

  • A GitHub Application with organization webhook (read & write) authorization.
  • cron.php must be running to enable the processing of incoming webhooks from your VCS system.

Installation

Use the Standard installation process for this extension.

Data Model

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.

VCS submenu

New submenu of the standard Configuration menu, displaying a dashboard of different classes representing VCS objects and predefined automation.

Connector

An API connector to connect to GitHub Application.

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

Connector Properties
Name Type Mandatory?
Connector
Name Alphanumeric string Yes
Provider Possible values: GitHub Yes
Application organization installation
Organization Alphanumeric string (organization where application is installed) No
Application GitHub
Application ID Alphanumeric string Yes
Private key Long Text Yes
Tabs
Tab Description
Webhooks List of webhooks that are using the connector

VCS Webhook

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

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

VCS Webhook Properties
Name Type Mandatory?
Label Alphanumeric string Yes
Synchronization status Possible values: Active, Inactive, Unsynchronized, Error Automatically computed
Connector Foreign key to Connector No
Webhook URL Alphanumeric string Automatically computed
Webhook secret key Alphanumeric string Automatically computed
Last event on Date (year-month-day) Automatically computed
Tabs
Tab Description
Automations Automations associated to the webhook
Contacts Contacts related to the VCS organization
Documents Documents relevant to the VCS organization
Once the webhook label has been defined, it can no longer be changed; it remains read-only for the rest of the time.
The secret key is used to cipher the webhook's data. It is automatically generated when the webhook is created but can manually be overwritten, if required.
Synchronization

Synchronizing a webhook will make sure that information is up-to-date, proactively detects potential issues and keeps the webhook in a good working order. The Synchronization status of the webhook will highlight the status of the last synchronization :

  • Webhook configuration is active.
  • Webhook configuration is inactive.
  • Webhook configuration is not synchronized.
  • Webhook configuration couldn't be synchronized.
Synchronization status is obtained (once a day) thanks to background tasks so don't forget to run cron.php in your scheduling tool.

VCS Event

Typology class defining event could be sent by VCS provider.

Name Type Mandatory?
Provider VCS provider sending event Yes
Name Text Yes

Automations

Automation objects drive the execution of tasks upon reception of events from webhooks. 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…

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

Append to Object Automation

This automation

  • 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 used to retrieve the destination object reference (such as the ticket reference contained in the commit reference).
Only Case Log and HTML attributes are supported. Text and Long Text are working but you will see all HTML syntax.
Name Description Type Mandatory?
General information fieldset
Label Name of your automation Alphanumeric string Yes
Provider Name of VCS provider (only Github for the moment) EnumList Yes
Trigger on event(s) Select the VCS events that will trigger a webhook on the organization attached to the automation.
This extension fills several events for Github provider : Create, Delete, Push, Issues, Pull Request, Milestone, Fork.
External key with Event typology class Yes
Scope The Scope attribute may be used to limit automation to a set of elements contained in a webhook's payload.
For instance, on the push event on GitHub, all related commits are grouped together in an array. The scope allows automation to be activated not globally on the whole event but individually on all single commits. The variables that can be accessed from the template are therefore the commit's variables. Global event variables can be accessed through the context.
Alphanumeric string No
Target Object fieldset
Object Class Specify the target class EnumList Yes
Destination attribute Select the target attribute you will fill EnumList Yes
Group target messages Group messages for the same target object. If you have multiple commits for the same object, it will generate only one entry in the ticket. EnumList No
Target Object Reference fieldset
Attribute used as reference Select the object's attribute to search from the payload to match iTop object EnumList Yes
Data containing the reference Define the part of the webhook payload containing your reference Text Yes
Regex to retrieve reference Define your regex to retrieve the reference of the target object Text Yes
Message to append fieldset
Template Define template with placeholders from data sent by the provider's wehbook. This “text” will be placed in destination attribute you defined above HTML Text Yes

Append to iTop Log Automation

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.

Template syntax must be consistent with events and scope you selected. If you don't put any scope, you can only use global variables of your events, but if you add a scope, additional variables related to your scope can be used.

VCS Manager Profile

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.

Configuration

Connection between Github and iTop

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

Connector

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


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

VCS Webhook

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


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

Automations

By default, two automated functions are integrated into the extension. Both construct messages based on data contained in events triggered by the VCS 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.

Prefilled automations will be created at the extension's installation to make it easier to set up. You can update/adapt them to stick to your environement. As soon as it's fine, don't forget to link them to VCSWebhook's object.

Append to Object Automation

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

Append to iTop Log Automation

The template syntax must be consistent with the events and scope you selected. If you don't specify any scope, you can only use the global variables of your events, but if you add a scope, additional variables related to your scope can be used.

Linking automations to webhooks

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

Name Description Type Mandatory?
Status Field activates or deactivates the automation for the given VCS Webhook Possible values: Active, Inactive Yes
Conditions Filter on a specific condition based on webhook data.
The filter may be used, for instance, to execute automation only on a event for a given branch.
Example to filter only main and support/3.2 branches: ref=refs/heads/(main|support/3.2).*
Alphanumeric string No


You can put until 3 conditions on the link between automation and VCS Webhook


Usage

This extension enables R&D teams to acquire useful VCS informations.

R&D will work on VCS tool (only Github for the moment).
On events triggered by GitHub, according to configuration, some iTop automations will be executed.

Github events

Here are some events triggered by GitHub:

iTop automations

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.

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

Custom automation

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 global payload, if a scope is defined.

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

Templates

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

Datas

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]]

Operators

  • 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]]

Functions

  • Hyperlink: insert a 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]]
  • Substring: split a string
[[@substring offset]]
[[@substring offset size]]
  • Counter: insert a counter for arrays
[[@counter commits]]
[[@counter commits commit commits]]
  • Separator: insert a separator (divider)
[[@separator]]
[[@separator (color)]]
  • Colored text: insert a colored text
[[@text data_text]]
[[@text data_text color]]
extensions/combodo-vcs-integration.txt · Last modified: 2025/01/13 14:02 by 127.0.0.1
Back to top
Contact us