Github Connector

description: Github Connector

GitHub Connector

SyncNow works with connectors to synchronize data between various work systems. Each system connector is tailored to connect to a specific work system. The GitHub connector allows users to sync issues from GitHub repositories to other work systems such as Jira, Azure DevOps, and more. This guide provides detailed steps on setting up the GitHub connector, configuring sync processes, and managing synchronization settings.

⚙️ Setting Up the GitHub Connector

To set up the GitHub 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 "GitHub" from the list of available connectors.
Configure the GitHub Connector
- Name: Enter a unique name for the GitHub connector.
- Username and Token: Provide the GitHub 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 GitHub is correctly configured.

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

🔄 Creating a Sync Process

After configuring the GitHub 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 GitHub Repository
Choose the GitHub repository you want to sync issues from.
Configure Sync Filters
- Filter Criteria: Select the GitHub 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 GitHub issues to corresponding entities in the target work system (e.g., Jira tickets, Azure DevOps work items).
  - Field Mapping: Map specific fields from GitHub 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 GitHub 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 GitHub and the target work system.

🛡️ Managing Synchronization

Webhooks Management: If real-time sync is enabled, webhooks will be automatically registered and managed by SyncNow. Ensure that the webhooks' authentication settings are properly configured to maintain secure communication.
Monitor and Adjust Sync Processes: Regularly review and adjust sync processes to ensure they are functioning correctly and meeting your synchronization needs.

🗂️ Supported Fields and Limitations

SyncNow provides support for synchronizing various fields between GitHub 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
Number	Number of an issue.	Unidirectional
Title	The title of the issue.	Bidirectional (GitHub & Target System)
Description	The detailed description of the issue.	Bidirectional (GitHub & Target System)
State	The status of the issue (open, closed).	Bidirectional (GitHub & Target System)
Labels	Tags or labels assigned to the issue.	Bidirectional (GitHub & Target System)
Assignees	Users assigned to the issue.	Bidirectional (GitHub & Target System)
Comments	Comments on the issue.	Bidirectional (GitHub & Target System)
Milestone	The milestone associated with the issue.	Bidirectional (GitHub & Target System)
Due Date	The due date of the issue.	Bidirectional (GitHub & Target System)
Priority	The priority of the issue.	Bidirectional (GitLab & Target System)
Date Fields	The title of the issue.	Unidirectional

⚠️ 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.

🏷️ Entity Mapping

The GitHub connector currently supports mapping only the Issue entity type. This means you can synchronize GitHub 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 GitHub issues to the appropriate entity type in your target system for successful synchronization.

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

🔗 Code Linking with Work System Entities

SyncNow supports linking code commits and pull requests in GitHub 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 GitHub commits or pull 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 pull request description in GitHub 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 GitHub commit or pull request.
This allows users to easily navigate from a work item to the related code change in GitHub.

Usage Example

Reference an Entity in a Commit or PR
In your GitHub commit message or pull 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 GitHub commit or pull request.

Supported Events

Code pushed (commits)
Pull request created
Pull request updated
Pull 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 pull request descriptions.

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