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 |
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 :
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).
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.
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 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 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.
Append to Object Automation
Append to iTop Log Automation
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
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]]