Configure Xsquash4GitLab in SquashTM

Learn More

This page is dedicated to the configuration of the Xsquash4GitLab plugin from the SquashTM administration. To configure synchronizations, go to: Manage Xsquash4GitLab synchronizations.
To learn more about Xsquash4GitLab features, please visit the page Synchronize GitLab Agile Objects in SquashTM.

Xsquash4GitLab is a SquashTM plugin dedicated to the synchronization of issues from GitLab. Here are its main features:

• An automatic synchronization module that enables SquashTM to import and keep:
• GitLab issues, updated as requirements in the Requirements workspace;
• GitLab milestones or iterations, and their content, updated as sprints in the Executions workspace. This feature allows the user to see in the Executions workspace sprint issues that needs to be verified. It also automatically feeds the sprint execution plan with tests associated to the issues;
• A reporting module that enables you to display information in the issues about the course of acceptance testing in SquashTM. This information can be displayed in GitLab issues in notes that are created and updated by SquashTM.

Most of the Xsquash4GitLab's features are automatic and start on their own once the configuration is fully completed:

Name	Start	Flow direction
Synchronization of GitLab issues	Automatic once the configuration is completed	From GitLab to SquashTM
Synchronization of GitLab milestones and iterations	Automatic once the configuration is completed	From GitLab to SquashTM
SquashTM acceptance data reporting	Automatic once the configuration is completed	From SquashTM to GitLab
Create a test plan in SquashTM from GitLab objects	Manual from the SquashTM Execution workspace	From GitLab to SquashTM

Warning

During these automatic actions, the plugin will never erase objects synchronized in SquashTM (requirements or sprints) or objects in GitLab (issues, milestones or iterations). If objects were to be deleted or moved in GitLab, the corresponding synchronized objects would remain in SquashTM and would have to be manually deleted by SquashTM users if needed.

Installation and Prerequisites

Info

The Xsquash4GitLab plugin is available for free. To use it, you must download it and install it on SquashTM. GitLab Bugtracker must also be installed.
For more information, please visit these pages: Downloads and Install SquashTM plugins.

SquashTM/GitLab Communication

The Xsquash4GitLab plugin is based on a bidirectional communication between SquashTM and GitLab. It is a server to server communication that goes through GitLab GraphQL API. For the plugin to work, the communication must be possible. Often, this requires interventions on the network's infrastructure: opening flows in the firewalls, adding certificates in the JVMs, etc.

If the same GitLab server is already used with success as a bugtracker thanks to the GitLab Bugtracker plugin, it means that the communication is already possible.

Should there be a problem, you must directly test the SquashTM server to verify if it can access GitLab. For this, try to make a request directly to the GitLab GraphQL API or from the server hosting SquashTM using a curl or wget. If it does not work, it means it's a network problem.

GitLab account authorizations

To work, the plugin must be able to communicate with GitLab, or through a GitLab user. That user must at least have Read permissions on the API for all the objects to synchronize (issues, milestones and iterations). If reporting from SquashTM to GitLab is activated, the user must have writing permissions on the API for all the involved issues.

Create the Xsquash4GitLab server in SquashTM

To use the Xsquash4GitLab plugin, you must declare a synchronization server of the type "gitlab.bugtracker" in the SquashTM Administration workspace, in the Servers>Bugtrackers and Synchronization servers workspace.

In the pop-up to create a new server, enter the server name (unrestricted), "gitlab.bugtracker" as the type, and the simplest GitLab URL, then click on [Add].

Warning

An Xsquash4GitLab synchronization server cannot be deleted if it is being used for synchronizations. You must delete the synchronizations beforehand to be able to delete the server.

Credentials used for the synchronizations

The plugin uses the GitLab GraphQL API to retrieve data with a basic authentication, using the credentials of the GitLab account used for each synchronization.

Learn More

For security reasons, the login and password entered to connect to third-party tools are encrypted in the database with an encryption key. The Xsquash4GitLab plugin also has two properties that must be directly configured in SquashTM configuration file squash.tm.cfg.properties. To learn more, please visit the page Manage SquashTM Configuration File.

Use SquashTM credentials

This option enables all the synchronizations to be done with the same GitLab account. The usual solution we recommend is to create a technical account dedicated to the plugin in GitLab with the necessary rights only for the desired GitLab projects.

Then, on a synchronization server configuration page, in the Authentication Policy block, it is necessary to add the GitLab technical account token generated in GitLab in the SquashTM credentials section.

Configure Xsquash4GitLab for a Project

You can configure GitLab issue synchronizations individually for each SquashTM project. For this, go to your project's consultation page, then click on the Plugins anchor .

First, activate the Xsquash4GitLab connector plugin to access its own specific configuration page by clicking on the button .

To deactivate the plugin for the project, click on the same button you clicked on to activate it. When checked, the option Save plugin configuration enables you to save the plugin's configuration while it is being deactivated, and the project's synchronizations. If unchecked, the project's configuration and synchronization are permanently deleted when the plugin is deactivated.

You can access Xsquash4GitLab's configuration page clicking on the button at the end of the Xsquash4GitLabConnector row.

The Xsquash4GitLab configuration page is composed with the following blocks:

• The Synchronizations block enables you to configure the synchronization perimeters (more details on page: Manage synchronizations);
• The Field mappings block enables you to configure the mapping for GitLab and SquashTM fields;
• The Field value mappings block enables you to configure the value mapping for list-type fields: Criticality, Category, and Status;
• The TM acceptance data reporting block allows you to enable or disable the reporting to see the course of acceptance testing with GitLab issues;
• The Real-time synchronization block gives the information needed to configure in GitLab the real time issues synchronization in SquashTM.

Configure Field Mappings

For SquashTM to display the information contained in the fields of GitLab issues, you must configure the field mappings. For this, go to the 2nd block on the Xsquash4GitLab configuration page.

Info

When mappings are configured, the corresponding SquashTM fields can no longer be updated manually.
These fields are updated via the synchronization process only, as long as the related requirement is within the synchronization perimeter, and if the associated plugin is active.

The button on top of the block enables you to add a new mapping.

The SquashTM fields available are in a drop-down list. You can add more fields to this list by adding custom fields to the project's requirements. For most cases, we recommend that you use "Simple text" or "Tag" SquashTM custom fields to retrieve the data from GitLab issues.

Learn More

To learn more about custom fields, please visit the page Manage custom fields.

The GitLab fields are also available in a drop-down list. The same GitLab field can be mapped with several SquashTM fields. There are some default mapping that cannot be modified and/or deleted.

Once you have configured the block, do not forget to force the project's synchronization for your changes to be taken into account. You must also force the synchronization after deleting a mapping in the table. Otherwise, errors will appear in the logs.

Info

Some GitLab fields in the drop-down list are only available with GitLab Premium or Ultimate. If there is a mapping with one of these fields with GitLab Community, the field's synchronization will be ignored.

Configure Field Value Mappings

In GitLab, the issue information is mostly defined as labels or scoped labels in a unique field. Criticality, status, and category are usually defined as labels.

If a field value mapping was configured between the GitLab field Label and the SquashTM fields Criticality, Category, or Status, you must configure the field value mappings to get a complete mapping. For this, go to the Field Value Mappings block.

To configure them, you must use YAML syntax. You must follow this format, which is explained in the Guidelines.

In the Guidelines:

• squashfield corresponds to the name of the SquashTM field in English and in lowercase, as displayed in the list of fields and values available at the end of the guidelines;
• gitlabvalue is the value of the GitLab label as defined in GitLab, it is case-sensitive. Scoped labels' syntax must be key::value;
• squashvalue is the value of the SquashTM field as displayed in the list of fields and values available in the guideline section.

Here is an example to configure these three fields:

Once you have configured this block, do not forget to force the project's synchronizations for your changes to be taken into account. You also must force the synchronization after deleting a mapping.

Learn More

You can associate an information list to the Category field of the project's requirement to retrieve the value of GitLab issues in SquashTM as in the example above.
To learn more about custom list, please visit the page Manage Custom Lists.

Configure the Reporting from SquashTM to GitLab

The Xsquash4GitLab plugin is able to transfer information related to acceptance in SquashTM to GitLab. This information is directly reported in GitLab issues, as a note or a label.

Focus

For the reporting to work, the SquashTM public URL must be configured. Only a SquashTM administrator can do it. The procedure is described on the page SquashTM public URL.

GitLab note

There are four types of information: three testing progress rates (Writing of test cases, Verification of GitLab issues, Validation of GitLab issues) and one field, Testing Status, presenting a summary analysis of these three rates.

This reporting is optional. You can enable it or disable it in the TM acceptance data reporting block.
If it is enabled, a note is created in each synchronized GitLab issue. This note is then updated during a synchronized cycle, only if the indicators values have changed.
If it is disabled, nothing is created in GitLab. However, if the reporting was previously enabled, the existing GitLab notes will not be deleted when disabling it.

GitLab Label

When GitLab label publishing is enabled, a label is added to each synchronized GitLab issue.

It is possible to define a label prefix that will be added before the available values. For example, if the prefix is "TestingStatus::", the possible values for the label will be:

• TestingStatus::Not initialized
• TestingStatus::Design in progress
• TestingStatus::Ready
• TestingStatus::Validation in progress
• TestingStatus::Valid
• TestingStatus::Invalid

These labels must be created in GitLab so that SquashTM can apply them to synchronized issues.

The label prefix can also be redefined for each synchronization (see the section Create a synchronization).

Learn More

The coverage indicators and the different testing statuses, as reported in GitLab, are detailed in Follow testing activity in GitLab.

Configure real-time synchronization

GitLab issues can be synchronized in real-time in SquashTM, without waiting for the next synchronization cycle.

The configuration has to be done in GitLab and is based on webhooks.

This Real-time synchronization panel allows you to copy the information you need to set up the integration in GitLab:

• Webhook URL: To see this URL, SquashTM public URL must be configured;
• Secret token: Optional, only if a token has been configured in the properties file by a system administrator. Depending on the configuration, it is shown or hidden in SquashTM UI.

In GitLab, the configuration can be set up for a project, a group, or an instance (for GitLab Self-Managed). The following procedure describes the configuration for a project:

1. On the top bar, select Main menu > Projects and find your project;
2. On the left sidebar, select Settings > Integrations;
3. Select SquashTM;
4. Ensure that the Active toggle is enabled;
5. In the Trigger section, indicate which type of issue is concerned by the real-time synchronization;
6. In the SquashTM webhook URL field, paste the webhook URL;
7. In the Secret token (Optional) field, paste the secret token (only if configured in SquashTM);
8. Save.

Xsquash4GitLab configuration in Project templates

You can configure Xsquash4GitLab in a project template. Thus, you will be able to share it with the projects associated with the template or created from the template. After, at the project level, this configuration can be transmitted to the template or evolve independently of the template.

This feature is useful when you want to configure the Xsquash4GitLab plugin for multiple SquashTM projects and the Jira issues to synchronize come from Jira projects with the same configuration (custom fields, types of issues, priorities, workflow, etc.).

Configure Xsquash4GitLab in Project templates

The Xsquash4GitLab plugin configuration page for templates is similar to the projects one, except for the Synchronizations block which is not there for project templates.

For templates, you can configure mappings between the SquashTM and GitLab fields, namely:

• Field mappings;
• Field value mappings;
• TM acceptance data reporting.

Create a Project using the template's Xsquash4GitLab configuration

When creating a project from a template, the Xsquash configuration option applies the synchronization plugins settings (Xsquash4Jira and Xsquash4GitLab) from the template.

Thus, in the created project, the Xsquash4GitLab plugin is already configured, except for synchronizations which must be added at project level. At the project level, Xsquash4GitLab's configuration can be transmitted to the template or evolve independently of the template.

Link the template's Xsquash4GitLab configuration to the linked Projects

When creating a new Project

When creating a project from a template, the Link Xsquash configuration option:

• links the project's synchronization plugins to the template's (checked option):
  • the project-level configuration is inherited from the template, except for synchronizations;
  • any changes made to the template will be propagated to the linked projects.
• does not link the project's synchronization plugins' configuration to the template's (unchecked option):
  • the project-level configuration can evolve independently of the template;
  • changes made at the template level will not affect the linked projects.

When associating an existing Project with a template

You can also link Xsquash4GitLab's configuration when associating an existing project to a template.

In this case, if the Xsquash4GitLab plugin was already configured at the project level, this configuration is replaced by that of the template. This will only have an impact on mapping settings, the synchronizations will not be deleted.

Deactivate Xsquash4GitLab in the templates

Deactivating or deleting the configuration in the template deletes the configuration in the linked projects, except for the synchronizations.