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

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

  2. Enable SCM integration on for a Compass Repository
    1. Locate the Compass REST API Server’s bin directory and issue the following command:

      cqperl setupSCM.pl <<repository_name>> <<admin_user_name>>

    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.

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

  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