Introduction

ConnectALL helps you to integrate GitHub artifacts with other applications.

Supported Artifacts

(tick) Branch

(tick) Commit

(tick) Pull Request

Supported Functionalities

(tick) Sync Fields 

Unsupported Functionalities

(error) Attachments

(error) Attachment as URL 

(error) Comments

(error) Sync Custom Fields

(error) Sync Issue Linking

Authentication

(tick) Basic Authentication

GitHub does not support password-based authentication. So, select PAT while you create a connection and leave the Password field blank. Refer to this page for PAT generation: https://docs.github.com/en/authentication/keeping-your-account-and-data-secure/creating-a-personal-access-token. Make sure the URL configured in ConnectALL is 'https://api.github.com' and not the browser URL. (URL tip will already indicate this in ConnectALL.)

Metadata

  • Organization — This is the top-level metadata.
  • Repositories — This is the second level metadata. The Metadata field will list all repositories for the selected organization.
  • Artifact Type — Supports the list of artifact types listed above.

Artifacts

Branch

GitHub allows you to only create Branches. So, a 'Branch' is treated as a 'Create/Write' only artifact. As that's the case, select only 'Create' against the 'Sync Option' (in the Entity Mapping screen) for GitHub. And do not select either option (Create or Update) for the other adapter.

A 'Branch' has the following two fields exposed:

  • custom_basebranch — Supply the base branch from where a new branch has to be created. It can be a 'Constant' at the applink level or provided through field mapping from the source artifact.
  • custom_additional_repository — Supply the additional repositories where the branch has to be created — this will be added to the mapped repository in metadata. A 'Constant' can be mapped. In case you have more than one, supply comma-seperated repository names.

Note: A hyphen will replace spaces, if any, in a branch name.

Commit

‘Commits’ can only be fetched from GitHub. So a 'Commit' is treated as a 'read-only' artifact. As that’s the case, ensure that you select neither of the sync options (Create or Update) for GitHub (in the Entity Mapping screen) when configuring an app link. 'Commits’ are queried from all the branches of a mapped repository, and unique commits are filtered before sending to ConnectALL. Remember to filter unique commits, as the same may be available in more than one branch when queried.

'Commits' have a limitation when queried based on 'modified since time'. Note that a 'Commit' timestamp reflects the committed time in the local git repo and not when you pushed to a remote git repo. (Typically,  a 'Commit' is made and kept in a local drive for some time before being pushed to a remote repository.) Hence, the traditional ConnectALL method of incremental time-query results in losing some 'Commits'— if not pushed immediately after completion. To avoid this, for the ‘Commits', queries are run for the last 24hrs (one day) from the current timestamp to reprocess the commits received during the previous one-day timeframe. So, 'Commits' in a delayed push will still be picked up by ConnectALL. Some organizations practice pushing artifacts to remote repositories at a lesser frequency. In such a scenario, use the 'commit.query.since.days' property in ConnectALL to configure the frequency against a particular connection. Mention the property value as an 'Integer' (in terms of days).

Use the Flow Filter to limit the branches scanned for 'Commits' based on a given branch pattern. The below examples show how to configure this.

  1. branch=master – scans for commits only in the master branch
  2. branch=master;branch=release* – scans for commits in the master branch and any branch that starts with the release
  3. branch=*test – scans for commits in any branch that ends with a test
  4. branch=*feature* – scans for commits in any branch that contains a feature

Pull Request

Pull Requests are bidirectional artifacts with some limitations. ConnectALL supports 'Update' for Pull Request, and only an update to the 'body field' is supported. If you are mapping a Pull Request, don't select 'Create' against the 'Sync Option' in the Entity Mapping screen for GitHub. ('Create' is not supported for Pull Request).