How to configure SCM integrations
A Compass administrator can setup one or more SCM Integrations to record SCM events from one or more SCM applications. The Compass administrator can also customize which record type in Compass will record events from a configured SCM application.
About this task
Once an SCM Integration is setup, the SCM application will send webhooks to Compass as users make changes in the SCM. Compass will process the webhooks to identify related Compass records and create SCM Event records for them.
Administration of the SCM integration
All administration activities for the SCM Integration package are controlled by the membership of the SCMIntegrationAdmins user group. This group enables SCM Integration administration to be delegated to specific individuals. Create the SCMIntegrationAdmins user group for each schema that uses the SCM Integration package. Then, subscribe that group to all databases that use a schema to which the SCM Integration package has been applied. The group users can modify, create and delete SCM Integration records, just like an event editor. Users not listed in the SCMIntegrationAdmins user group can only see SCMIntegrationEvent records.
Adding new SCM Types
Out of the box, the SCM Integration package comes with three supported SCM types: VVExpress, GitHub, and GitLab.
As Compass adds support for new SCM types, you can add the newly supported SCM types to the list without requiring a new SCM Integration package or an edit to the package. In addition, you can change the available list to a limited list such as VVExpress only. This is done by editing the dynamic named list called SCMIntegrationSCMTypes, and either adding or removing SCM types from the list. See the section “Editing dynamic lists” on editing the named list.
Attention: Adding an SCM type not supported by Compass can lead to SCM Integration issues, and the integration would not work.
For details about the SCM integration package, see the SCM integration record types topic.
Configuring the SCM application
The steps to configure Compass to handle the SCM Webhooks are:
Procedure
-
Enable SSO for a Compass Repository
Locate the Compass REST API Server’s bin directory and issue the following command:
cqperl setupSSO.pl <<repository_name>> <<admin_user_name>> <<sso_user_name>>
For example: cqperl setupSSO.pl 2.1.0 admin SSO_USER
The <<admin_user_name>> must be the name of a super user for that repository and the <<sso_user_name>> must be a unique name which will be used for SSO logins.
Note: You can skip step two if the enablement was already done to setup Keycloak with Compass.
-
Enable SCM integration on for a Compass Repository
For example: cqperl setupSSO.pl 2.1.0 admin
The <<admin_user_name>> must be the name of a super user for that repository.
This step will create if needed, the SCMIntegrationAdmins group and SCMIntegrationUser user. All incoming SCM events will be recorded under the SCMIntegrationUser user.
-
Create a SCMIntegrationConfig record
Creates a SCMIntegrationConfig, and the associated SCMIntegrationSecurity, record for the SCM to be integrated. Note below the Config Name (<<config_name>>) and secret (<<secret>>) for step 4.
-
Configure SCM to send Webhooks to Compass
Please consult the SCM documentation on how to set up webhooks.
During this setup, you must configure the SCM to send webhooks to Compass REST API Server on this URL:
https://<<hostname>>:8190/ccmweb/rest/repos/<<repository_name>>/databases/<<db>>/services/scm/webhooks/<<config_name>
For example: https://my.host.com:8190/ccmweb/rest/repos/2.1.0/databases/SAMPL/services/scm/webhooks/CfgVV , and specify the <<secret>> as created in step 3.
While setting up the Webhook, you must configure the SCM to send these webhooks (see Webhook Name column table). Based upon these Webhooks, Compass will use the Matching Field’s first word as Record Id to look up a Compass record and create the Compass Event for it if a match is found.
Table 1. Webhook Name column SCM Webhook Name Matching Field Compass Event VersionVault Express Deliver
Modify Activity
Activity Name
Activity Name
Activity
Activity
GitHub Push
Pull Request
Create/Delete
Commit Message
Pull Request Title
Branch Name
Commit
Pull Request
Branch
GitLab Push
Merge Request
Commit Message
Merge Request Title
Commit Branch
Merge Request