Synchronize GitLab issues in the Requirement workspace of Squash TM
What It Does
If an Xsquash4GitLab synchronization is configured, GitLab issues are automatically synced as requirements in Squash TM and updated on a regular basis. The synchronization repository as well as all the requirements it contains are created during the first update.
The synchronization is only one way, from GitLab to Squash.
This part explains how these assets are organized in the Requirement workspace.
For the organisation in the Execution workspace, please consult the Synchronize sprints page.
Synced Requirements
In Squash, synced requirements are the equivalent of GitLab issues. In the requirement library, their name is grayed out and preceded by this icon .
This icon indicates that it is a synced requirement and also gives information on the synchronization status of the linked GitLab issue using the following color code:
- green icon: the requirement is still updated via synchronization;
- yellow icon: the requirement is no longer updated via synchronization because the matching GitLab issue is no longer in the synchronization perimeter defined in the plugin's configuration (for example, for a synchronization with a filter on the 'label' field, the GitLab issue does not have this label anymore);
- red icon: the requirement is no longer updated via synchronization because the matching GitLab issue was deleted in GitLab;
- black icon: the issue's synchronization status is unknown (for example, when the global synchronization has failed).
Synced requirements have three more details than native requirements:
- A hyperlink to the original GitLab issue;
- The GitLab issue's synchronization status that indicates if the requirement is still updated by synchronization and if the matching GitLab issue is still in GitLab;
- The GitLab issue's synchronization status, which alerts the user if the communication between Squash and GitLab is disrupted or if an error has occurred during the last update.
Modify, move and delete
Synced requirements can be modified in Squash. There are two behaviors depending on the field to be modified:
- It is a synchronized field (description, reference, or any other field with a mapping): modifications will be erased with the next synchronization if the issue is updated in GitLab;
- It is not a synchronized field: modifications are kept in Squash.
Warning
Approved and Obsolete statuses prevent requirements from modifications. As a result, when a requirement is modified with one of these statuses, it is not updated anymore. The status has to be manually set to Work in progress or Under review to enable again the requirement update.
Synchronized requirements can be moved in the requirement library. Again, several behaviors:
- The requirements are moved into the same project: they are still updated and stay or do not stay at their new location depending on the organization type (see Synchronized requirements organization);
- The requirements are moved into another project: they become native requirements in the target project and are recreated in the source project during the next synchronization.
When deleting synchronized requirements in Squash:
- If the requirements are still in the synchronization perimeter: they are recreated with the next synchronization;
- If the requirements are not in synchronization perimeter anymore: they are not recreated in Squash.
Hybrid hierarchies
It is possible to add a hierarchy of native requirements under a synchronized requirement.
For example, a GitLab issue could lead to several test requirements in Squash. These test requirements can be added under the synchronized requirement that matches this issue in Squash.
Target Repository
The target repository is the parent repository in which the GitLab issues are synchronized. Depending on the synchronization type, repositories can be automatically created under the target repository.
Synchronization Status
Target repositories are also preceded by this icon and their color code is similar to the one of synced requirements:
- green icon: the synchronization of the target repository has succeeded and all the synced requirements it contains are updated via synchronization;
- yellow icon: the synchronization of the target repository has succeeded, but it contains requirements that are no longer updated via synchronization because they are no longer in the synchronization perimeter or in GitLab;
- red icon: the synchronization of the target repository has failed (for example, when the communication between Squash and GitLab is disrupted or if an error has occurred during the last update).
Move and delete
Target repositories can be moved in the requirement library:
- Target repositories are moved in the same project: their synchronized requirements are still updated;
- Target repositories are moved in another project: their synchronized requirements become native requirements in the destination project and the target repositories are recreated with the next synchronization in the original project.
If the target repositories are deleted in Squash, they are recreated with the next synchronization, at their original location.
Synchronized requirements organization
When adding a synchronization, there are several options to organize the synchronized requirements depending on the synchronization type (issue or board). Depending on the chosen organization, Xsquash4GitLab automatically creates folders under the target repository in the requirement library.
Flat organization
This organization is only available with the Issue synchronization type.
With the Flat organization, issues are synchronized at the root of the target repository. Users are then free to organize the synchronized requirements as they want, as long as they do not move them into another project so they can still be updated.
Iteration and milestone organizations
These two organizations are available with both Issue and Board synchronization types.
With the Iteration and Milestone organizations, iterations and milestones are synchronized as folders in the requirement library and contain synchronized requirements corresponding to GitLab issues linked to each iteration or milestone in GitLab.
Issues not linked to any iteration or milestone are synchronized at the root of the target repository.
Focus
For synchronizations of a GitLab project:
- a folder is created for each milestone of the project, sub-group, and group;
- a folder is created for each iteration of the sub-group, and group.
For synchronizations of a GitLab group:
- a folder is created for each milestone of the group, its sub-groups, and its projects;
- a folder is created for each iteration of the group, and its sub-groups.
If an issue is linked to another iteration or milestone in GitLab or is not linked to an iteration or milestone anymore, it is automatically moved in the matching folder in Squash.
Focus
Accumulation of closed iterations and milestones in GitLab leads to the creation of numerous matching folders in Squash. To improve readability, it is possible to create one (or several) archive folders at the root of the target repository and move the closed iterations and milestones into it. In this archive folder, iterations and milestones folders can be organized by year, theme or else.
If the iteration or milestone organization is not relevant anymore, synchronized requirements can be moved anywhere in the same Squash project. The only restriction is not to delete the closed iterations and milestones folders, in order to prevent them from being recreated with the next synchronization.
Warning
It is recommended to move neither unfinished iterations and milestones folders, nor their content. Once the iterations and milestones and its issues are closed, archiving can be done in Squash.
Tree organization
This organization is only available with the Issue synchronization type.
It is mostly relevant when synchronizing the issues of a GitLab group.
With the Tree organization, GitLab subgroups and projects of the synchronized group are synchronized as folders in the requirement library. Each Project folder contains synchronized requirements corresponding to GitLab issues linked to each iteration or milestone in GitLab.
If the tree organization is not relevant anymore, synchronized requirements can be moved anywhere in the same Squash project. The only restriction is not to delete the former project folders, in order to prevent them from being recreated with the next synchronization.