How to configure SCM integrations

A DevOps Plan administrator can setup one or more SCM Integrations to record SCM events from one or more SCM applications. The DevOps Plan administrator can also customize which record type in DevOps Plan will record events from a configured SCM application.

About this task

Once an SCM Integration is setup, the SCM application will send webhooks to DevOps Plan as users make changes in the SCM. DevOps Plan will process the webhooks to identify related DevOps Plan 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 DevOps Plan 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 DevOps Plan 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 DevOps Plan to handle the SCM Webhooks are:

Procedure

  1. Enable SSO for a DevOps Plan Repository

    Locate the REST API Server 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.

  2. Enable SCM integration on for a DevOps Plan Repository
    1. Locate the REST API Server 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 DevOps Plan

    Please consult the SCM documentation on how to set up webhooks.

    During this setup, you must configure the SCM to send webhooks to DevOps Plan REST API Server on this URL:

    https://<<hostname>>:8190/ccmweb/rest/repos/<<repository_name>>/databases/<<db>>/services/scm/webhooks/<<config_name>

    Note: The details for <<repository_name>> can be found by clicking Tenant Management > Teamspace > Details > Database.

    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, DevOps Plan will use the Matching Field’s first word as Record Id to look up a DevOps Plan record and create the DevOps Plan Event for it if a match is found.

    Table 1. Webhook Name column
    SCM Webhook Name Matching Field DevOps Plan Event
    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