CCS-4 Enhance jira and Sonar evidence extraction and add documentation

Author: carmithersh

.github/workflows/sonar-evidence-example.yml

@@ -59,9 +59,9 @@ jobs:
             -Dsonar.host.url=https://sonarcloud.io \
             -Dsonar.java.jdkHome=$JAVA_HOME \
             -Dsonar.verbose=true \
-            -Dsonar.token=$SONAR_TOKEN -X
+            -Dsonar.token=$SONAR_TOKEN
           # create evidence from sonar-scan analysis
-          ./examples/sonar-scan-example/bin/sonar-scan-extractor-linux-amd64  $PWD/.scannerwork/report-task.txt > predicate.json
+          ./examples/sonar-scan-example/bin/sonar-scan-extractor-linux-amd64  --reportTaskFile=$PWD/.scannerwork/report-task.txt --FailOnAnalysisFailure > predicate.json
 
       - name: Log in to Artifactory Docker Registry
         uses: docker/login-action@v3

examples/jira-transition-example/bin/jira-transition-checker-darwin-arm64

@@ -16,6 +16,7 @@ import (
     "tasks": [
         {
         "jira_id": "<jira-id>",
+        "summary": "<summary>",
         "transition_found": "<true/false>"
         "author": "<user display name>",
         "author_user_name": "<user email>",
@@ -36,6 +37,7 @@ type TransitionCheckResponse struct {
 
 type JiraTransitionResult struct {
 	JiraId           string `json:"jira_id"`
+	Summary          string `json:"summary"`
 	TransitionFound  bool   `json:"transition_found"`
 	Author           string `json:"author"`
 	AuthorEmail   string `json:"author_user_name"`
@@ -92,6 +94,7 @@ func main() {
          // adding the jira result to the list of results
         jiraTransitionResult := JiraTransitionResult{
             JiraId: jiraId,
+            Summary: issue.Fields.Summary,
         }
 
         if len(issue.Changelog.Histories) > 0 {

examples/jira-transition-example/bin/jira-transition-checker-linux-amd64

@@ -0,0 +1,46 @@
+# Create Sonar Scan Evidence predicate from the build CI and attach it to the build info
+Sonar is a code scanning tool that helps to identify bugs, vulnerabilities, and code smells in your code. 
+It is important to track the code quality and security of the code changes done and released. 
+To allow automation of proper code quality and security checks, we create an evidence of the Sonar scan results
+during the build with confirmation that the code quality and security checks passed before the code was committed.
+using the `FailOnAnalysisFailure` argument the customer can decide if to create the sonar scan evidence if the scan did not pass 
+sonar quality gates, or fail the predicate creation with exist status 1.
+If the Analysis status is not 'OK', but `FailOnAnalysisFailure` was not set, then the predicate is created with analysis.status = 'ERROR' which 
+should be checked using a policy.
+
+## Environment variables
+- `SONAR_TOKEN` - The sonar server token.
+
+## Arguments
+--reportTaskFile=<path> - The path to the sonar report task file.
+--FailOnAnalysisFailure - Fail with exit code 1 if the sonar analysis failed in sonar quality gate.
+
+
+## The example is based on the following steps:
+1. set sonar token as an environment variable
+2. call sonar scan
+for example:
+``
+$PWD/sonar-scanner-6.2.1.4610/bin/sonar-scanner \
+            -Dsonar.projectKey=my-sonar-project-key \
+            -Dsonar.organization=my-sonar-org \
+            -Dsonar.host.url=https://sonarcloud.io \
+            -Dsonar.java.jdkHome=$JAVA_HOME \
+            -Dsonar.verbose=true \
+            -Dsonar.token=$SONAR_TOKEN
+``
+3. call the jira-transition-checker utility (use the binary for your build platform) with these arguments: "transition name" JIRA-ID [,JIRA-ID]
+for example:
+ ``./examples/sonar-scan-example/bin/sonar-scan-extractor-linux-amd64  --reportTaskFile=$PWD/.scannerwork/report-task.txt --FailOnAnalysisFailure > predicate.json
+``               
+4. call the evidence create cli with the predicate.json file
+for example:
+``
+jf evd create \
+            --build-name $GITHUB_WORKFLOW \
+            --build-number "${{ github.run_number }}" \
+            --predicate ./predicate.json \
+            --predicate-type https://jfrog.com/evidence/sonar-scan/v1 \
+            --key "${{ secrets.JIRA_TEST_PKEY }}" \
+            --key-alias ${{ vars.JIRA_TEST_KEY }}
+``

examples/jira-transition-example/bin/jira-transition-checker-linux-arm64

@@ -92,8 +92,21 @@ func main() {
 ///home/runner/work/Evidence-Examples/Evidence-Examples/.scannerwork/report-task.txt
     //get the sonar report file location or details to .scannerwork/.report-task.txt
     reportTaskFile := ".scannerwork/.report-task.txt"
+    failOnAnalysisFailure := false
     if len(os.Args) > 0 {
-        reportTaskFile = os.Args[1]
+        // loop over all args
+        for i, arg := range os.Args {
+            if i == 0 {
+                continue
+            }
+            if strings.HasPrefix(arg, "--reportTaskFile=") {
+                reportTaskFile = strings.TrimPrefix(arg, "--reportTaskFile=")
+            } else if strings.HasPrefix(arg, "--FailOnAnalysisFailure") {
+                failOnAnalysisFailure = true
+            }
+        }
+        logger.Println("reportTaskFile:", reportTaskFile)
+        logger.Println("FailOnAnalysisFailure:", failOnAnalysisFailure)
      }
     // fmt.Println("reportTaskFile: ", reportTaskFile)
     // Open the reportTaskFile
@@ -156,6 +169,10 @@ func main() {
         logger.Println("Error getting sonar analysis report: ", err)
         os.Exit(1)
     }
+    if analysis.ProjectStatus.Status != "OK" && failOnAnalysisFailure {
+        logger.Println("Sonar analysis failed, exiting according to failOnAnalysisFailure argument")
+        os.Exit(1)
+    }
 
     response := SonarResponse{
         Task: taskResponse.Task,