Readme for OpenText GitLab Connector for MF Connect 24.1.1

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

© 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

Features

Supported Versions

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.

Supported Assets

The OpenText GitLab Connector supports the following asset types. Ensure that the correct "Server license plan" option is selected

Unsupported Assets in this release

 

Top

Prerequisites

This connector requires at least build 24.1.1 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.

  1. Create a Connector directory. For example: C:\Program Files\Micro Focus\Connect\AppData\connectors\mfcConnectorGitLab
    • NOTE: If this is being installed into an existing connector directory, you must remove the existing mfc*.jars
  2. Copy the following libraries (and the provided Connector jar, and the provided mfcConnectorUtil jar) into the connector directory you created.

GitLab access token permissions

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:

 

Top

Installation and Upgrade Information

The following information contains notes regarding installation, but does not replace the entire process.

Required Connection Information

To use this connector, you will need to collect and enter this information in the MF Connect user interface:

Optional Connection Information

 

Top

Known Issues

Syncing Rich text fields like Description

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.

Description and comment fields for Epic type cannot be updated while sync to GitLab

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.

Epics and Iterations from ancestor groups are not available for sync from/to 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.

Duplicate Labels in project and group levels.

GitLab connector could have issues handling scoped labels which have the same names but different values in Project and group level.

Changing access token in Data source properties.

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 not working.

"Project changes" chart for GitLab projects does not work with MF connect 24.1.1 version.

Intermittent error "Timeout on validation of query" thrown while sync to GitLab.

"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.

Relative links in Description / Comments doesn't work correctly

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.

Rich text formatting that doesn't work

Fallback users are not supported

When selecting a fallback user a message will state there are no users.

Technical Notes

User Maps for GitLab

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.

Data Source Setup

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.

Mapping Rich Text Fields from GitLab (outgoing)

Rich text fields are available to read for "Description" and "Notes (Comments)" fields in Issue, Incident, Task, Iteration and Epic types.

Mapping Rich Text Fields to GitLab (incoming)

Rich text fields are available to write for "Description" and "Notes (Comments)" fields in Issue, Incident and Task types

Note(Comment) Support

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

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

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.

Relationship (Links)

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".

Epic hierarchy

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.

User fields

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.

Support for Custom types

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

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.

Rich text syncing with ALM Octane 16 or earlier

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.

 

Top

Getting Help

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.

 

Top