This readme describes how to configure OpenText GitLab Connector. Refer to the OpenText Community and MF Connect User Guide for further configuration instructions.
The OpenText GitLab Connector for MF Connect lets you synchronize GitLab assets with assets in OpenText products such as ALM Octane and Micro Focus ALM.
© Copyright 2018 - 2024 Open Text
The only warranties for products and services of Open Text and its affiliates and licensors ("Open Text")are as may be set forth in the express warranty statements accompanying such products and services. Nothing herein should be construed as constituting an additional warranty. Open Text shall not be liable for technical or editorial errors or omissions contained herein. The information contained herein is subject to change without notice.
Except as specifically indicated otherwise, this document contains confidential information and a valid license is required for possession, use or copying. If this work is provided to the U.S. Government, consistent with FAR 12.211 and 12.212, Commercial Computer Software, Computer Software Documentation, and Technical Data for Commercial Items are licensed to the U.S. Government under vendor's standard commercial license.
| Contents | ||
|---|---|---|
| Installation and Upgrade Information | Technical Notes | |
| Prerequisites | Known Issues | Getting Help |
This version of the connector is certified with GitLab OnPremise server 15.11 as well as the Cloud version (hosted)
Unless otherwise specified, for any given MF Connect connector from OpenText, all versions of the connector product that are officially released and supported by it's vendor both four months before the time of the release of the connector as well as at the time of using the connector, are supported by OpenText. Not all product versions will be tested and validated by OpenText for each connector release. Instead, OpenText chooses a subset of versions that we deem representative or most important to run validation and certification tests against. These selected versions are mentioned in the respective connector read-me, clearly identifying them as "validated" or "certified". As stated above, this does not mean that MF Connect does not support other product versions – it only means that no validation test cycle was executed for the other versions.
The OpenText GitLab Connector supports the following asset types. Ensure that the correct "Server license plan" option is selected
This connector requires at least build 24.2 of MF Connect and can be configured using the MF Connect UI.
The thesaurus.properties file should be copied to the MF Connect's AppData\data folder.
The following are required to run the Connector. For further configuration instructions, see the MF Connect Release Notes.
GitLab connector uses access tokens (Personal/Project or Group access token) to authenticate to GitLab server and access resources using apis. The access token configured in the GitLab data source must have the following access:
The following information contains notes regarding installation, but does not replace the entire process.
To use this connector, you will need to collect and enter this information in the MF Connect user interface:
Enables (true) or disables (false) the injection of a comment header to comments that are created or
updated by MF Connect. The comment header consists of: Updated by MF Connect: 'Author' 'UpdateTime'.
'Author' and 'UpdateTime' values are taken from the comment on the opposite side of the connection.
MF Connect will exclude comments that were created before this date (exclusive).
The date format is <year>-<month>-<day>.
For example: The value '2023-01-01' will make MF Connect only process comments that were created
on January, 1, 2023 and later.
Leaving it empty will result in all comments being included for synchronization.
When following option under project Settings/General/Visibility,project features and permissions Require authentication to view media files. Prevents direct linking to potentially sensitive media files is selected, GitLab server fails while using access tokens to retrieve media files. There is an open GitLab issue 25838 requesting this capability. This could potentially cause issues while synchronizing description and comment field which have embedded images. The workaround to retrieve media files using GitLab apis is to turn off the above option on the GitLab server. The MF connect service must be restarted for the new setting changes to take effect.
There is currently no way to upload images to a group through GitLab apis. There is an open GitLab issue 329615 requesting this capability. Writing image/media files to a GitLab Epic during sync for Description and Comments can lead to the links not working. Due to this reason, description and comments for Epic type are available only for read purpose until this issue is resolved by GitLab.
If a project belonging to a subgroup was chosen to synchronize, Epics and iterations from ancestor groups are not available for sync. Issues in GitLab can be assigned to an epic belonging to an ancestor group, in which case the epic field for the issue will not be synced.
GitLab connector could have issues handling scoped labels which have the same names but different values in Project and group level.
While updating access token in an existing GitLab data source, the user might need to clear the existing project/group selections to ensure the changes can be saved successfully.
"Project changes" chart for GitLab projects does not work with MF connect 24.1.1 version.
"Timeout on validation of query" error has been noticed intermittently during sync of large number of items into GitLab On-premise server. There is an open GitLab issue 396784 related to this error. Failed items will generally get synced in subsequent iterations.
If the GitLab issues have relative links to its resources mentioned in the issue's description / comments, the synced item on the master source contains link similar to GitLab, but link doesn't work as the intended resource is relative to GitLab.
When selecting a fallback user a message will state there are no users.
User Map entries in OpenText GitLab connector must use the "username" field to identify an user. For project and group access tokens, the bot user (internal GitLab user) associated with the token must be provided for mapping.
The number of "Project Name" values in the drop down list is limited to 500. Project not in the list can be entered manually as the full path of the project.
Rich text fields are available to read for "Description" and "Notes (Comments)" fields in Issue, Incident, Task, Iteration and Epic types.
Rich text fields are available to write for "Description" and "Notes (Comments)" fields in Issue, Incident and Task types
Syncing of GitLab Notes (also referred to as Comment) is supported for all types except Requirement. By default, note/comment syncing is enabled for each type. Comment functionality is controlled for each type via 3 type specific properties on the datasource properties TYPE tab - Allow Comment Delete, Allow Comment Update, and Allow Comment Create. When comments are created via MF Connect synchronizations the comment creator will always be the GitLab data source user. System generated notes are ignored during sync from GitLab.
Scoped labels in GitLab are supported to sync to/from GitLab as enumerated fields with the prefix of "Labels." in the display name. Group level scoped labels are only available for Epic and Iteration type, while Project and Group labels are both available for Issue, Incident, Task type. Scoped Labels inherited from ancestor groups are also available to sync.
Non Scoped labels in GitLab are supported to sync to/from GitLab as "Labels" field. GitLab labels can be mapped with "Tags" in Octane. Group level non-scoped labels are available for Epic and Iteration type, while Project and Group non scoped labels are both available for Issue, Incident, Task type. Non Scoped Labels inherited from ancestor groups are also available to sync.
Links from the supported asset types are supported to be synced to/from GitLab. The four link types available for sync are "link.is.blocked.by", "link.blocks", "link.inward.relates.to" and "link.outward.relates.to". Epic type does not support "link.is.blocked.by".
GitLab supports hierarchy (multi-level child epics) for Epic type. This feature is available only for "Ultimate license" plan ("Server license plan" property should be selected). When available, GitLab connector allows sync of the hierarchy of epic. GitLab connector supports fields like "Hierarchy Level","Has children", "Has parent" for Epic type which can be useful in establishing sync criteria based on the hierarchy level.
When updating GitLab, the Connector identifies users based on closest match. When the match isn't exact, log messages will show information on users which were not found during update.
The GitLab Connector currently supports only default types listed above and has no support for custom work item types which is currently work in progress in GitLab.
Rate limiting can be configured on a GitLab server per user or for operations like creating Issues and Notes. When the GitLab connector encounters rate limiting error while updating assets on the GitLab server, it waits for a minute before retrying the operation that failed. Since this could affect performance of GitLab connector, it is recommended to exclude the GitLab connector user from the rate limit.
GitLab uses HTML5 recommended style tags for Rich text content like "strong", "em" for bold, italics etc. instead of CSS based style. So the rich text formatting works fine only with Octane versions 16.1 and above.
Visit https://portal.microfocus.com to communicate directly with OpenText SupportLine to resolve your issues.
Visit OpenText SupportLine at https://www.microfocus.com/en-us/support for up-to-date support news and access to other support information. First time users may be required to register to the site.