GitLab Connector

The GitLab connector allows users to sync issues from GitLab repositories to other work systems such as Jira, Azure DevOps, and more. This guide provides detailed steps on setting up the GitLab connector, configuring sync processes, and managing synchronization settings.

⚙️ Setting Up the GitLab Connector

To set up the GitLab connector in SyncNow, follow these steps:

Navigate to the Connectors Page
Access the "Connectors" page from the main menu.
Add a New Connector
Press the "Add Connector" button to create a new connector.
Select "GitLab" from the list of available connectors.
Configure the GitLab Connector
- Name: Enter a unique name for the GitLab connector.
- Username and Token: Provide the GitLab username and a personal access token. The token must have the necessary permissions to access the repository and manage webhooks.
🔒 Webhooks Security Configuration
- Authentication Method: Choose how to authenticate webhooks with SyncNow:
  - Anonymous: No authentication required.
  - IP Address/Range: Restrict access to specific IP addresses or ranges.
  - SyncNow Username/Token: Use SyncNow credentials for authentication.
Save and Validate
Click the "Save" button to save the connector settings.
Press the "Validate" button to ensure the connection to GitLab is correctly configured.

Once the GitLab connector is set up and validated, users can proceed to create sync processes to synchronize data between GitLab and other work systems.

🔄 Creating a Sync Process

After configuring the GitLab connector, follow these steps to create a sync process:

Navigate to the Sync Processes Page
Access the "Sync Processes" page from the main menu.
Add a New Sync Process
Press the "Add Sync Process" button to start configuring a new sync process.
Select GitLab Repository
Choose the GitLab repository you want to sync issues from.
Configure Sync Filters
- Filter Criteria: Select the GitLab fields and specify the values to filter issues. Multiple fields can be selected, and they will be checked using an AND clause.
- Example: Filter issues where label = bug and state = open.
Select Synchronization Mapping
- Predefined Template: Choose from predefined templates for mapping issues to another work system.
- Custom Mapping: Create your own mapping by selecting:
  - Entity Mapping: Map GitLab issues to corresponding entities in the target work system (e.g., Jira tickets, Azure DevOps work items).
  - Field Mapping: Map specific fields from GitLab issues to fields in the target work system.
Synchronization Method
- Real-time Sync: Select this option to use webhooks for real-time synchronization. SyncNow will automatically register the necessary webhooks in GitLab during the activation of the first sync process.
- Timer Sync: Choose this option to synchronize data at regular intervals.
Save and Activate
- Click the "Save" button to save the sync process settings.
- Activate the sync process to start synchronizing data between GitLab and the target work system.

🗂️ Supported Fields for GitLab Synchronization

SyncNow provides support for synchronizing various fields between GitLab and other work systems. The following table lists the fields that can be synchronized, specifying whether they support one-way or two-way synchronization.

Field	Description	Direction
ID	Id of an issue.	Unidirectional
Title	The title of the issue.	Bidirectional (GitLab & Target System)
Description	The detailed description of the issue.	Bidirectional (GitLab & Target System)
State	The status of the issue (open, closed).	Bidirectional (GitLab & Target System)
Labels	Tags or labels assigned to the issue.	Bidirectional (GitLab & Target System)
Assignees	Users assigned to the issue.	Bidirectional (GitLab & Target System)
Notes	Comments on the issue.	Bidirectional (GitLab & Target System)
Milestone	The milestone associated with the issue.	Bidirectional (GitLab & Target System)
Due Date	The due date of the issue.	Bidirectional (GitLab & Target System)
Priority	The priority of the issue.	Bidirectional (GitLab & Target System)
CreatedAt	Issue Creation Date	Unidirectional
UpdatedAt	Issue Updated Date	Unidirectional

🏷️ Entity Mapping

The GitLab connector currently supports mapping only the Issue entity type. This means you can synchronize GitLab issues with equivalent entities (such as tasks, work items, or tickets) in other work systems.

ℹ️ Note: Ensure that your sync processes are configured to map GitLab issues to the appropriate entity type in your target system for successful synchronization.

⚠️ Limitations

Body and Comments Synchronization: SyncNow supports the synchronization of issue bodies and comments with rich text and pictures.
Embedded Attachments: Embedded attachments within issue bodies and comments are not supported for synchronization.

🔗 Code Linking with Work System Entities

SyncNow supports linking code commits and merge requests in GitLab to entities that have remote links in your connected work systems (such as Jira, Azure DevOps, and others).

Overview

With this feature, you can automatically create remote links from GitLab commits or merge requests to issues, tasks, or tickets in your target work systems. This enables traceability between code changes and work items across your integrated tools.

How It Works

When a commit message or merge request description in GitLab contains references to work system entity IDs (e.g., #JIRA-123, #DEVOPS-456), SyncNow detects these references.
SyncNow then adds a remote link from the referenced entity in the target system to the corresponding GitLab commit or merge request.
This allows users to easily navigate from a work item to the related code change in GitLab.

Usage Example

Reference an Entity in a Commit or Merge Request
In your GitLab commit message or merge request description, include the entity key or ID, such as:
```
Fixes bug in authentication flow. Related to #JIRA-123 and #DEVOPS-456
```
SyncNow Processes the Reference
During synchronization, SyncNow parses the message, identifies the referenced entities, and creates remote links in the target work system.
Remote Link Added
The referenced issue or work item in Jira, Azure DevOps, or another system will now display a remote link to the GitLab commit or merge request.

Supported Events

Code pushed (commits)
Merge request created
Merge request updated
Merge request merged

ℹ️ Note:
Ensure that your sync process is configured to enable code linking and that entity keys or IDs are included in your commit messages or merge request descriptions.

This feature brings full traceability between your GitLab code and your work system entities, making it easier to track changes and collaborate across teams.

💡 Tip: For best results, ensure your field mappings are configured correctly in your SyncNow workflow.