Synchronize GitLab Agile Objects in Squash TM
What It Does
Once the Xsquash4GitLab plugin is correctly set up, 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 TM.
This part explains how these assets are organized in the Requirements workspace.
In Squash TM, synced requirements are the equivalent of GitLab issues. In the requirements 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 always 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 doesn't 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 ticket's synchronization status is unknown (for example, when the global synchronization has failed)
Synced requirements have 3 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 TM 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 TM. 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 are erased with the next synhronization if the issue is updated in GitLab
- it isn't a synchronized field: modifications are kept in Squash TM
'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 requirements library. Again, several behaviors:
- the requirements are moved into the same project: they are still updated and stay or don't 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 TM:
- 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 TM
It is possible to add a herarchy of native requirements under a synchronized requirement.
For example, a GitLab issue could lead to several test requirements in Squash TM. These test requirements can be added under the synchronized requirement that matches this issue in Squash TM.
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.
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 TM 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 projet: 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 TM, they are recreated with the next synchronization.
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 requirements library.
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 don't 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 requirements 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.
For synchronizatons 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 TM.
Accumulation of closed iterations and milestones in GitLab leads to the creation of numerous matching folders in Squash TM. 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 restricion is to not delete the closed iterations and milestones folders, in order to prevent them from being recreated with the next synchronization.
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.
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 requirements 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 restricion is to not delete the former project folders, in order to prevent them from being recreated with the next synchronization.