Teamscale Docs

Appearance

How to Request the Findings Churn for a Commit via the REST API ​

Teamscale calculates the finding churn for each commit of the repository. This article shows you how you can query this information using Teamscale's REST API, so that you can, for example, include it in your build logs. It makes the following assumptions:

  • You already have a running Teamscale instance.
  • You know the revision of your commit, e.g., the Git commit hash or SVN revision number.
  • You want to query the API using the command line (or generate a client in your programming language of choice from the OpenAPI specification).

REST API Authentication

Details on authentication is explained in the REST API article.

Step 1: Resolve Revision to Branch & Timestamp ​

Internally, Teamscale stores commit-related data as a pair of branch and timestamp (in milliseconds since the Unix epoch), e.g., master:1234567890. To query this tuple with for a given revision (variable COMMIT_REVISION), you can perform a GET query to the revision endpoint:

bash
RESPONSE="$(curl \
  --user ${USER_NAME}:${ACCESS_KEY} \
  --header 'Accept: application/json' \
  "${TEAMSCALE_URL}/api/projects/${PROJECT_ID}/revision/${COMMIT_REVISION}/commits")"

The value of the RESPONSE variable will look like this:

json
[
  {
    "branchName": "master",
    "timestamp": 1581410860000
  }
]

You need to store the values of branchName and timestamp for the follow-up server call.

Accessing JSON on Command Line

To access JSON properties on the command line, you can, e.g., use jq.

bash
BRANCH="$(echo "${RESPONSE}" | jq --raw-output '.[0].branchName')"
TIMESTAMP="$(echo "${RESPONSE}" | jq '.[0].timestamp')"

Step 2: Load Findings for Commit ​

Assuming you stored BRANCH and TIMESTAMP from the response of the first step, you can now query the findings churn for the commit at hand:

bash
curl \
  --user ${USER_NAME}:${ACCESS_KEY} \
  --header 'Accept: application/json' \
  "${TEAMSCALE_URL}/api/projects/${PROJECT_ID}/finding-churn/list/?t=${BRANCH}%3A${TIMESTAMP}"

A sample (shortened) response with one removed finding looks like this:

json
{
  "addedFindings": [],
  "findingsAddedInBranch": [],
  "findingsInChangedCode": [],
  "removedFindings": [
    {
      "groupName": "Bad practice",
      "categoryName": "Code Anomalies",
      "message": "Method `console.log` should not be called",
      "assessment": "RED",
      // ...
    }
    // ...
  ]
}

As you can see, the response contains four lists of findings:

  • addedFindings: the findings that were added with this commit
  • findingsAddedInBranch: in case of a merge commit, the findings that are now present on the target branch but originated from the source branch
  • findingsInChangedCode: the findings that were already present in touched code, but were not resolved with this commit
  • removedFindings: the findings that were removed with this commit

Step 3: Example Use Case: Counting the Findings ​

In case you want to count the findings, you can use the aforementioned jq tool again. Assuming you stored the response from Step 2 in a file using --output findings-churn.json, you can determine the number of findings in various lists like this:

bash
ADDED_FINDINGS=$(jq '.addedFindings | length' findings-churn.json)
REMOVED_FINDINGS=$(jq '.removedFindings | length' findings-churn.json)
FINDINGS_IN_CHANGED_CODE=$(jq '.findingsInChangedCode | length' findings-churn.json)

Combining all the information gathered for the commit at hand, you can the build a link to the Commit Detail view in Teamscale that spells out the finding churn in its link text:

html
<a href="${TEAMSCALE_URL}/activity.html#details/${PROJECT_ID}/?t=${BRANCH}%3A${TIMESTAMP}">
  Commit ${COMMIT_REVISION} added ${ADDED_FINDINGS}, ignored ${FINDINGS_IN_CHANGED_CODE}, and removed ${REMOVED_FINDINGS} findings
</a>