Add SCM data into ALM Octane (technical preview)

Use this topic to learn how you can inject SCM (source code management) data into ALM Octane using the REST API. Then you can use ALM Octane to track commits and other relevant data such as repositories and branches, and perform code analysis.

In this topic:

Flow

To manually inject SCM data to the ALM Octane server: 

1. Authenticate and sign in as a user with the necessary permissions.

2. Push the SCM data into ALM Octane.

3. Check the status of the push, and get commit and branch data.

Back to top

Push the SCM data into ALM Octane

Use the PUT operation with a payload to create new SCM Data entities, like repositories, branches, and commits.

The unique commit identifier is parentRevId. If the revision ID is found in the context but for a different repository/branch, the commit will be linked to the other repository .

Request syntax

The request syntax for injecting SCM information is:

PUT .../api/shared_spaces/space_id/scm-commits?instance-id='<instance_id>'&job-ci-id='<path_to_file>'&build-ci-id='<build_id>'

When PUTing, specify: 

• A query for identifying the pipeline run.

• A request body containing the JSON payload described below.

• The Content-Type header field, set to application/json.

• Optionally, the content can be compressed in gzip format. In this case, the Content-Encoding header field must be set to application/gzip.

The following table describes how to identify the corresponding pipeline run in request:

The JSON payload in the request body

The payload in the request body describes the pipeline run that you want to update with SCM data.

You can specify more than one commit in the payload.

The payload uses the standard ALM Octane REST API syntax. Here is an example:

[{
        "repository": {
            "type": "git",
            "url": " https://github.com/repository.git",
            "branch": "master"
        },
        "commits":
        [{
                "user": "user",
                "userEmail": "user@mail.com",
                "time": "1586269223000",
                "parentRevId": "e5358a5f1456aebbf5c436790179fe6b218def89",
                "comment": "some comment",
                "revId": "7583cc0704efd0ef96bbb4689a401d252adea821",
                "changes": [{
                        "type": "edit",
                        "file": "src/…filePath/Example1.java",
                        "renameToFile": null,
                        "commitId": null
                    }
                ]
            }, {
                "user": "user",
                "userEmail": "user@mail.com",
                "time": "1586269223000",
                "parentRevId": "e5358a5f1456aebbf5c436790179fe6b218def81",
                "comment": "some comment",
                "revId": "7583cc0704efd0ef96bbb4689a401d252adea822",
                "changes": [{
                        "type": "edit",
                        "file": "src/…filePath/Example2.java",
                        "renameToFile": null,
                        "commitId": null
                    }
                ]
            }
        ]
}]

Back to top

Check results

If successful, return code 200 is returned.

Make sure the SCM data has been pushed correctly into ALM Octane.

1. Check the response for errors that may have occurred.

2. Check if the commits exist in ALM Octane. For details, see Track changes committed to your Source Control Management system.

Get commit and branch data

You can see existing scm_commits and their IDs using a GET operation:

GET .../api/shared_spaces/<space_id>/workspaces/<workspace_id>/scm_commits

See Examples below.

You can see existing SCM branches and their IDs using a GET operation:

GET .../api/shared_spaces/<space_id>/workspaces/<workspace_id>/scm_repositories

Back to top

Examples

For example, we have in the request:

Example: GET .../api/shared_spaces/<space_id>/workspaces/<workspace_id>/scm_commits/1213269?fields=creation_time,client_lock_stamp,stories,version_stamp,commit_time,revision,workspace_id,repositories,name,workspace_user,risk,comment,last_modified,user,email

Without workspace user, repositories, and stories, the response will be:

Example: GET .../api/shared_spaces/<space_id>/workspaces/<workspace_id>/scm_commits/1213269?fields=creation_time,client_lock_stamp ,version_stamp,commit_time,revision,workspace_id,name,risk,comment,last_modified,user,email

{
    "type": "scm_commit",
    "last_modified": "2020-08-22T22:31:25Z",
    "revision": "53e564566a75fcc073a5ed0dd71bad0f0f588855",
    "creation_time": "2020-08-20T08:34:10Z",
    "user": "userName",
    "risk": false,
    "comment": "user story #1053020. user story 11111111",
    "commit_time": "2020-08-20T08:33:06Z",
    "name": "commit name",
    "workspace_id": 33006,
    "id": "1213269",
    "version_stamp": 14,
    "client_lock_stamp": 1
}

With the SCM data, the response will be:

Example: {
    "type": "scm_commit",
    "last_modified": "2020-08-22T22:31:25Z",
    "revision": "53e564566a75fcc073a5ed0dd71bad0f0f588855",
    "creation_time": "2020-08-20T08:34:10Z",
    "user": "evgene.lock",
    "risk": false,
    "comment": "user story #1053020. user story 11111111",
    "commit_time": "2020-08-20T08:33:06Z",
    "name": "commit name",
    "workspace_id": 33006,
    "id": "1213269",
    "version_stamp": 14,
    "client_lock_stamp": 1,
    "stories": {
            "total_count": 1,
            "data": [{
                           "type": "work_item",
                           "id": "1053020",
                           "name": "US1",
                           "subtype": "story"
                   }
            ]
    },
    "repositories": {
            "total_count": 1,
            "data": [{
                           "type": "scm_repository",
                           "scm_source_view": null,
                           "scm_type": 2,
                           "scm_diff": null,
                           "workspace_id": 33006,
                           "branch": "master",
                           "id": "324004",
                           "name": "repository.git:master",
                           "url": "https://github.com/repository.git"
                   }
            ]
    },
    "workspace_user": {
            "type": "workspace_user",
            "id": "117001",
            "workspace_id": 33006,
            "activity_level": 0,
            "full_name": "User Name",
            "name": "userName@mail.com"
    }
}

Back to top

See also:

• Set up API access
• Track changes committed to your Source Control Management system