CodeSonar Analysis in a GitHub Workflow on Microsoft Windows

The following instructions are for Microsoft Windows.

We provide separate instructions for other environments:

These instructions assume you are using CodeSonar 7.3 or later, where the codesonar analyze -remote-archive option is supported.

These instructions are also suitable for use with CodeSonar 7.2 and 7.1, provided that your hub has one or more associated remote analysis launch daemons that you can use to perform remote-managed analyses (with codesonar analyze -remote).

Prerequisites

These instructions assume that you have satisfied the prerequisites as described in the setup overview document. In particular, make sure you have access to the following.

A CodeSonar hub.
A GitHub server.
This can be an on-premises GitHub Enterprise server or the cloud GitHub.com.
A developer workstation.
- You will set up your example project and define your build workflow on this machine, so Git must be installed.
A CI builder machine, which will host a GitHub runner to build your software project and perform the CodeSonar analysis.
Unless you are using CodeSonar SaaS, or your hub already has suitable associated remote analysis launch daemons, an analysis data server machine: a machine suitable for setting up and running an "analysis data server".
In most cases this is likely to be different to the "CI builder" machine, in particular because there are additional resource requirements associated with running an archiving launch daemon. However, there is no requirement that the two machines be different.

Overview

The instructions below will assume that you are using PowerShell. Many of these tasks can also be performed with a Windows Command Prompt, but you will need to be sure to substitute appropriate syntax and commands. In particular, PowerShell variables are prefixed by a $ character, but Command Prompt variables are enclosed by % characters.

There are seven main steps.

A. Prepare an example project (zlib)
B. Create and install an analysis data server
C. Create and install a workflow build runner
D. Create a basic workflow that can build your code
E. Install CodeSonar and integration tools in CI builder environment
F. Update workflow job definition to perform CodeSonar analysis
G. Incremental Analysis workflow setup

A. Prepare an example project (zlib)

For the sake of an easy but realistic example, we will assume you want to build and analyze zlib (https://github.com/madler/zlib) version 1.2.9.

On your developer workstation, clone the zlib repository from github.com.
```
git clone https://github.com/madler/zlib
```
Create a new GitHub repository project named "zlib" (or similar) in your GitHub server instance with the following properties:
- Private or Internal visibility (not public).
- Do not initialize with a README or a ".gitignore" file.
Follow the instructions provided by the GitHub repository page to "push an existing repository" in order to push your local zlib repository clone to your GitHub server.
Enable GitHub Advanced Security Testing (GHAS) (if available). See the Settings > Security & analysis page.

After following the GitHub instructions, your local zlib repository should be configured so that its "origin" is on your GitHub server, and not the original GitHub.com location.

You should now have an example zlib repository in your GitHub server. You will build and analyze this in the steps that follow.
Create and push a branch called example for Git tag 'v1.2.9'.
```
git branch example v1.2.9
git push origin -u example
git checkout example
```
This new branch will serve as your example "main" branch. You will use it as a base branch for further branches in the steps below.

The instructions in this document were tested with zlib versions 1.2.9 and 1.2.12.

Note that zlib version 1.2.13 introduced GitHub Action workflows intended to be used on GitHub.com. Since those Action workflows will conflict with the Action workflows we want to demonstrate here, it is easiest to test with older versions of zlib such as 1.2.9.

B. Create and install an analysis data server

NOTE If you plan to analyze your code using a remote-managed or SaaS analysis service, then you do not need to install an analysis data server and you can skip this section. Go on to C. Create and install a workflow build runner.

Otherwise, set up an analysis data server now.

C. Create and install a build workflow runner

If needed, create a CodeSonar CI hub user.

You will need a CodeSonar hub user account that can be used for automated CI workflow jobs. If you previously created a hub user for an analysis data server, then you can use that account here too. Otherwise, create a new hub user account.

The instructions will assume that the hub user name is cshub_ci.
If you have not already done so, identify a suitable CI builder host machine.

You will need administrative access to a machine that can run pipeline jobs to build and analyze your code. This can be a physical machine or a virtual machine. This "CI builder" machine is distinct from the "analysis data server" machine from part B.
Log in to your CI builder machine as Administrator.
Install compilers and build tools.

In general, your CI builder machine must have all compilers and tools required to build your project(s). The CI builder machine must also have Git, since it is required for all GitHub runners.

zlib can be built with a variety of compilers and build tools. We will assume that you want to build zlib using the Microsoft Visual C++ compiler with NMake. However, it is relatively easy to substitute GCC and GNU Make in the steps below.
1. Install Microsoft Visual Studio, GCC, or whatever build tools you intend to use for building the example project, if they are not already installed.
2. Install Git, if it is not already installed. Git is available for download from https://git-scm.com.
Create a local Windows user account for CI build processes.

The CI user will be responsible for building your code and running the CodeSonar analysis.

The remainder of these instructions will refer to this account as ci_runner or $CI_USER.
Log in to your CI builder machine as your new CI user (ci_runner).
Download, register, and run the GitHub Runner software.

Instructions for installing, registering, and running the runner software can be found on your GitHub server. See the GitHub documentation on self-hosted runners for additional information: https://docs.github.com/en/actions/hosting-your-own-runners/about-self-hosted-runners.
1. In your web browser go to the Settings > Actions page for your GitHub repository.
2. Click the Add Runner button.
  
  This will open a new page that provides instructions for installing the runner software and registering the runner instance.
3. Follow the instructions to install the runner on your CI builder machine.
4. Register the runner.
  - Assign it the default labels self-hosted and Windows.
  - Add another label named MSVC.
    
    The "MSVC" label is intended to indicate that the runner has Microsoft Visual C++ compilers installed. Your workflow will use this "MSVC" label to find a runner that can compile the zlib code.
    
    If you are using gcc instead of Visual C++, add a GCC label instead.
  If you aren't able to add new labels when registering the runner, you can add the label in the GitHub Actions Settings web page after the runner has been registered.

D. Create a basic workflow that can build your code

Before introducing analysis, we will define a workflow job that simply builds the code.

The workflow definition is specified in a YAML file saved in a .github/workflows/ directory in the root of your code repository. For information about the GitHub Actions workflow YAML file syntax, see https://docs.github.com/en/actions/using-workflows/workflow-syntax-for-github-actions.

If you are not familiar with YAML format, you may want to read about it at https://yaml.org/spec/1.2/spec.html#Preview. Note that YAML is very sensitive to indentation.

Check out the example branch that you created in part A.
```
git checkout example
```
Create the .github\workflows directory in your local repository clone.
```
mkdir .github\workflows
```
Create a new workflow YAML file and save it as .github\workflows\build.yml.

Insert the YAML code below into .github\workflows\build.yml and edit it as needed.

Notice the use of the "example" branch in the on:push:branches and on:pull_request:branches items. This code assumes that you have pushed your example branch to your GitHub server (as described previously).

name: Build
on:
  push:
    branches:
      - master
      - example    # the 'example' branch you have set up
  pull_request:
    branches:
      - master
      - example    # the 'example' branch you have set up
jobs:
  build:
    runs-on:
      - self-hosted
      - Windows
      - MSVC
    timeout-minutes: 360
    env:
      # Your runner's Microsoft Visual Studio install directory.
      VSDIR: 'C:\Program Files (x86)\Microsoft Visual Studio\2019\Professional'
    steps:
      - uses: actions/checkout@v2
      - name: Compile using Microsoft Visual C++
        run: >
          Import-Module $Env:VSDIR\Common7\Tools\Microsoft.VisualStudio.DevShell.dll ;
          Enter-VsDevShell -VsInstallPath $Env:VSDIR ;
          nmake /f win32\Makefile.msc

Create a new repository branch named example_build (or whatever else you prefer) where you can save your new CI workflow definition file. Add your workflow to the branch.
```
git checkout -b example_build
git add .github\workflows\build.yml
```

Commit and push your workflow file to your GitHub server.

git commit -m "Add CI workflow configuration"
git push -u origin example_build

Test the workflow.
1. Create a pull request for the branch you just pushed.
  
  The git push command from the previous step may print a URL to help you create a pull request. You can also use the GitHub GUI directly to create a new pull request associated with your new branch.
  
  Important: Be sure to set the example branch (created previously) as the base branch for your pull request.
  
  When you create a new pull request for your new branch, GitHub will notice the workflow definition file and will use it to execute the workflow jobs on your CI builder machine.
2. Verify that the workflow executed successfully.
  
  Use the GitHub "Pull request" web page to find the status of your repository code "check" actions. If everything works correctly, you should see that your workflow action executed and if you inspect the actions log, you should see that the code was successfully compiled.
  
  If the workflow did not execute successfully, fix it before moving on to the next step.
Merge your pull request into the example base branch.

If your workflow executed successfully, merge the pull request. This will merge your example_build branch into the example base branch. Merging your pull request will add the new build.yml file to your example branch.
Check out the example branch again and pull the newly merged changes.
```
git checkout example
git pull origin
```

E. Install CodeSonar and integration tools in the CI builder environment

At this stage, you should have a workflow that successfully compiles your code. The next task is to install CodeSonar tools on your CI builder machine so that you can execute a CodeSonar analysis.

Log in to your CI builder machine as Administrator.
Install CodeSonar on your CI builder machine.
1. Download the CodeSonar Windows installer (e.g. codesonar-8.0p0.20231117-x86_64-pc-win64.exe).
  
  Make sure you download the correct installer for your operating system: there are both 32-bit and 64-bit versions.
2. Execute the installer to install CodeSonar.
  
  Make a note of the directory where you have installed CodeSonar. We will refer to this directory as $CSONAR.
Install the CodeSonar-GitHub integration tools.
1. You will need a tool such as tar to extract the CodeSonar-GitHub integration tools. If you're not sure whether tar is available on your system, check now:
```
where.exe tar
```
  If tar is not available, you will need an alternative program capable of extracting a file in .tar.gz format. One option is 7-Zip.
2. Download the CodeSonar-GitHub integration tools package (e.g. codesonar-github-integration-1.3p0.tar.gz).
3. Extract the package to a system-level location. (If you don't have access to tar, use the equivalent extraction command for your local tool.)
```
cd "$Env:ProgramFiles\CodeSecure"
tar -xzf "\Path\To\codesonar-github-integration-1.3p0.tar.gz"
```
4. Rename the extracted directory to make pipeline scripting simpler.
```
Move-Item "codesonar-github-integration-1.3p0" "codesonar-github-integration"
```
The example commands above will install CodeSonar-GitHub integration tools to C:\Program Files\CodeSecure\codesonar-github-integration.
Log in to your CI builder machine as your CI user ($CI_USER).
[HTTPS hubs only] Ensure that CodeSonar trusts your hub's HTTPS certificate.

If your CodeSonar hub uses plain HTTP (and not secure HTTPS), skip this step.

This step must be performed by the same OS user that executes the GitHub runner process. If you have been following these steps exactly, then this will be your CI user ($CI_USER) on your CI builder machine.
1. Execute the following script, which includes a codesonar get command. This codesonar get command fetches a list of projects from your CodeSonar hub. When contacting your hub it will also check the HTTPS certificate.
  
  Script variables. You may need to adjust one or more variable settings before executing the script.
  
  Variable Setting
  
  CSONAR_HUB Your hub location.
  
  CSONAR Your CodeSonar installation.
  
  Script. Adjust variable settings as described in the table above, then execute this script.
```
$CSONAR="$Env:ProgramFiles\CodeSecure\CodeSonar"
$CSONAR_HUB="https://codesonar.example.com:7340"

& "$CSONAR\codesonar\bin\codesonar" get "$CSONAR_HUB/index.csv" -o -
```
2. If CodeSonar does not recognize and trust your certificate, then it will prompt you to confirm that you trust the certificate.
  
  Assuming the correct certificate is received, then you should select "(T)rust certificate forever and connect" at the prompt. This will ensure that when CodeSonar is executed in future workflow jobs, it will always trust your hub's HTTPS certificate.
See the Troubleshooting document for additional information about this procedure as well as for alternatives.
In the GitHub settings for your CI builder runner, add a new label named CodeSonar.

This tag will help ensure workflow jobs which require CodeSonar will be executed on a runner host that has CodeSonar installed.
1. Open the appropriate GitHub page.
  - If you created a repository-specific runner, open the GitHub repository project page.
  - If you created an organization level runner, open the GitHub organization page.
2. Select Settings > Actions > Self-hosted runners to view self-hosted runners.
3. Find the entry for your runner. A list of labels is shown underneath.
4. Click the "down arrow" next to the label list and create a new "CodeSonar" label.

Variable	Setting
`CSONAR_HUB`	Your hub location.
`CSONAR`	Your CodeSonar installation.

F. Update the workflow definition to perform CodeSonar analysis

Most of the steps that follow should be performed in your local example (zlib) repository on your developer workstation.

Generate a CodeSonar hub user certificate and key.

If you already have a suitable hub user certificate and private key, you do not need to generate new ones. When you set up CODESONAR_HUB_USER_CERT_FILE and CODESONAR_HUB_USER_KEY_FILE later, use your existing files. Go on to Download a copy of your GitHub server's HTTPS root certificate.

In this example we will configure the workflow to perform certificate-based hub authentication.

If you cannot use certificate-based authentication (for example, because your hub is not configured for HTTPS), skip this step: you will modify the authentication-related command elements in later steps.

Certificate generation requires the CodeSonar command line tools. If you don't have CodeSonar installed on your developer workstation, then you may prefer to perform these steps on your "CI builder machine".

Execute the following script, which includes a codesonar generate-hub-cert command.

Script variables. You may need to adjust one or more variable settings before executing the script.

Variable	Setting
`CSONAR`	Your CodeSonar installation.
`CSONAR_HUB`	Your hub location.
`CSONAR_HUBUSER`	Your hub user account. Note that the command below uses this as both the username of the account that is authorizing certificate generation and the username of the account that is the subject of the certificate.

Script. Adjust variable settings as described in the table above, then execute this script

$CSONAR="C:\Program Files\CodeSecure\CodeSonar"
$CSONAR_HUB="https://codesonar.example.com:7340"
$CSONAR_HUBUSER="cshub_ci"
$CSONAR_HUBCERT="$CSONAR_HUBUSER.cert"
$CSONAR_HUBKEY="$CSONAR_HUBUSER.key"

& "$CSONAR\codesonar\bin\codesonar" generate-hub-cert `
   -foruser "$CSONAR_HUBUSER" `
   -auth password -hubuser "$CSONAR_HUBUSER" `
   -out "$CSONAR_HUBCERT" `
   -outkey "$CSONAR_HUBKEY" `
   "$CSONAR_HUB"

Provide the hub user account password when prompted.

New files $CSONAR_HUBUSER.cert and $CSONAR_HUBUSER.key will be created, where $CSONAR_HUBUSER is the name of your hub CI user account. These files contain your certificate and private key, respectively.

Configure GitHub Secrets for your CodeSonar hub credentials.

Add the certificate and key file contents to your GitHub repository's Secrets store. This will permit your analysis job to authenticate with your CodeSonar hub without an interactive password prompt.

If you need to authenticate with a password instead of a hub user certificate, set up a password secret instead.

Copy the entire contents of the hub certificate and key files that you created in the previous step into separate GitHub Secret entries. Some example Secrets are shown below.

The CodeSonar hub user associated with the CODESONAR_HUB_USER_CERT Secret must have permissions to create a new analysis for your project.

Name of Secret	Example Value	Notes
`CODESONAR_HUB_USER_CERT`	`-----BEGIN CERTIFICATE-----\nMIIEabcdefghi ...`	For certificate-based authentication only: the entire contents of your hub user certificate. You do not need to escape newline characters when entering the secret value in the GitHub Secret value form. The '\n' characters in the example are not intended to be copied literally.
`CODESONAR_HUB_USER_KEY`	`-----BEGIN PRIVATE KEY-----\nMIIEjklmnopqr ...`	For certificate-based authentication only: the entire contents of the private key associated with your hub user certificate. You do not need to escape newline characters when entering the secret value in the GitHub Secret value form. The '\n' characters in the example are not intended to be copied literally.

[HTTPS hubs only] Download a copy of your GitHub server's HTTPS root certificate.

In some cases, CodeSonar's Python interpreter will refuse to communicate with your GitHub server since it does not trust your GitHub server's HTTPS certificate. This may happen if your GitHub server uses a recently-issued certificate. In order to avoid a potential problem later, you can provide a copy of the certificate to CodeSonar in your workflow configuration.

See the Troubleshooting document for additional information about how to download this file. We will assume you have saved the root certificate file to the .github directory in your local repository as .github\github.root.cacert.
1. Download a copy of the root authority certificate for your GitHub Server's HTTPS certificate.
2. Save this root certificate to your repository working directory in Base-64 ASCII text format (often called "PEM" format).

Configure your workflow to use CodeSonar.

Create a new text file named analyze.yml and save it in your repository .github\workflows subdirectory.

You will use this file to define a new "analyze" workflow job in order to analyze your code.

Copy the example workflow file shown below into your new analyze.yml file and modify it as follows.

Update variable settings as required.

Variable	Setting
`CODESONAR`	The path to the `codesonar.exe` binary in your CodeSonar installation.
`CSPYTHON`	The path to the `cspython.exe` binary in your CodeSonar installation.
`GITHUB_CAFILE`	The path to your GitHub Server's HTTPS root authority certificate file (which you downloaded in the previous step).
`CSONAR_HUB_URL`	Your hub location (protocol://host:port).
`CODESONAR_GITHUB`	The path to the `\distro-image\codesonar-github` subdirectory of your CodeSonar-GitHub integration tools installation.
`CODESONAR_REMOTE_LAUNCHDS`	The set of remote launch daemons to use with `remote-archive` or `remote`. If you have followed these instructions exactly, this will be `"/analysis-data-server/"`. For SaaS analyses, set to `"/saas/"`.
`VSDIR`	Your runner's Microsoft Visual Studio install directory.

Other variables in the file are set to values that have already been set up.

CODESONAR_HUB_USER_CERT and CODESONAR_HUB_USER_KEY are set using the certificate-related GitHub secrets that you configured above.
GITHUB_TOKEN is set using secrets.GITHUB_TOKEN, which is always available.
Various variables are set to values in the github.event.* space: these are set by default in a GitHub action. For more information, see https://docs.github.com/en/actions/learn-github-actions/variables.

To provide a different name for your analysis, modify the -name value.

For CodeSonar SaaS or other remote-managed analysis, replace

-remote-archive  "$CODESONAR_REMOTE_LAUNCHDS"

with

-remote  "$CODESONAR_REMOTE_LAUNCHDS"

For password-based authentication, perform the additional steps below.
Ensure that the runner labels after the runs-on keyword match the runner that will run your CodeSonar analysis.
The -property arguments to codesonar analyze are used for adding additional, searchable data to your CodeSonar analysis. They are included here since they are often helpful for searching for analyses related to specific code commits. You may want to add more -property arguments in order to retain more searchable data for the analysis.
Note the use of PowerShell collection-to-scalar comparison syntax used to "coalesce" variables to the first non-empty value. Some versions of CodeSonar do not allow -property values to be empty. The workflow example shown below uses collection-to-scalar comparisons to try and ensure properties are not assigned to empty values. An example comparison is:
```
$COMMIT=("$Env:PULL_REQUEST_SHA", "$Env:GITHUB_SHA" -ne "")[0]
```
This will set the variable COMMIT to $Env:PULL_REQUEST_SHA if $Env:PULL_REQUEST_SHA is defined and non-empty, otherwise COMMIT will be set to the value of $Env:GITHUB_SHA, which is assumed to be defined.

Example workflow:

name: Analyze
on:
  push:
    branches:
      - master
      - example    # example main branch
  pull_request:
    branches:
      - master
      - example    # example main branch
jobs:
  analyze:
    runs-on:
      - self-hosted
      - Windows
      - MSVC
      - CodeSonar
    env:
      VSDIR: 'C:\Program Files (x86)\Microsoft Visual Studio\2019\Professional'
      GITHUB_CAFILE: '.github\github.root.cacert'
      GITHUB_TOKEN: '${{ secrets.GITHUB_TOKEN }}'
      PULL_REQUEST_ID: "${{ github.event.pull_request.number }}"
      PULL_REQUEST_SHA: "${{ github.event.pull_request.head.sha }}"
      PROJECT_NAME: "${{ github.event.repository.name }}"
      CODESONAR_PROJECT: "${{ github.event.repository.name }}"
      CODESONAR_PROJECT_FILE: "${{ github.event.repository.name }}"
      # Your CodeSonar hub base URL
      CODESONAR_HUB_URL: "https://codesonar.example.com:8443"
      CODESONAR_HUB_USER_CERT: "${{ secrets.CODESONAR_HUB_USER_CERT }}"
      CODESONAR_HUB_USER_KEY: "${{ secrets.CODESONAR_HUB_USER_KEY }}"
      CODESONAR_HUB_USER_CERT_FILE: "codesonar.hub.user.cert"
      CODESONAR_HUB_USER_KEY_FILE: "codesonar.hub.user.key"
      # Your CodeSonar remote launchd group
      CODESONAR_REMOTE_LAUNCHDS: "/analysis-data-server/*"
      CODESONAR: 'C:\Program Files\CodeSecure\CodeSonar\codesonar\bin\codesonar.exe'
      CSPYTHON: 'C:\Program Files\CodeSecure\CodeSonar\codesonar\bin\cspython.exe'
      CODESONAR_GITHUB: 'C:\Program Files\CodeSecure\codesonar-github-integration\distro-image\codesonar-github'
    timeout-minutes: 360
    steps:
      - uses: actions/checkout@v2
      - name: Create Hub Credential Files
        run: >
          echo "$Env:CODESONAR_HUB_USER_CERT" | Out-File -Encoding Default "$Env:CODESONAR_HUB_USER_CERT_FILE" ;
          echo "$Env:CODESONAR_HUB_USER_KEY" | Out-File -Encoding Default "$Env:CODESONAR_HUB_USER_KEY_FILE"
      - name: Compile and Analyze the Code
        run: >
          Import-Module $Env:VSDIR\Common7\Tools\Microsoft.VisualStudio.DevShell.dll ;
          Enter-VsDevShell -VsInstallPath $Env:VSDIR ;
          $BRANCH=("$Env:GITHUB_HEAD_REF", "$Env:GITHUB_REF_NAME", "$Env:GITHUB_REF" -ne "")[0] ;
          $TARGET=("$Env:GITHUB_BASE_REF", "$Env:GITHUB_REF_NAME", "$Env:GITHUB_REF" -ne "")[0] ;
          $COMMIT=("$Env:PULL_REQUEST_SHA", "$Env:GITHUB_SHA" -ne "")[0] ;
          & "$Env:CODESONAR" analyze
          "$Env:CODESONAR_PROJECT_FILE"
          -no-services
          -wait
          -remote-archive "$Env:CODESONAR_REMOTE_LAUNCHDS"
          -auth certificate -hubcert "$Env:CODESONAR_HUB_USER_CERT_FILE" -hubkey "$Env:CODESONAR_HUB_USER_KEY_FILE"
          -project "$Env:CODESONAR_PROJECT"
          -name "github-ci ref=$BRANCH os=$Env:RUNNER_OS job=$Env:GITHUB_JOB.$Env:GITHUB_RUN_NUMBER commit=$COMMIT"
          -property branch "$BRANCH"
          -property commit "$COMMIT"
          -property target "$TARGET"
          -property os "$Env:RUNNER_OS"
          -property ci_url "$Env:GITHUB_SERVER_URL/$Env:GITHUB_REPOSITORY/actions/runs/$Env:GITHUB_RUN_ID"
          -property ci_job "$Env:GITHUB_JOB"
          -property ci_run "$Env:GITHUB_RUN_NUMBER"
          -property ci_run_id "$Env:GITHUB_RUN_ID"
          "$Env:CODESONAR_HUB_URL"
          nmake /f win32\Makefile.msc
      - name: Pull Analysis Results from CodeSonar Hub
        run: >
          & "$Env:CODESONAR" dump_warnings.py
          -o warnings.sarif
          --hub "$Env:CODESONAR_HUB_URL"
          -auth certificate -hubcert "$Env:CODESONAR_HUB_USER_CERT_FILE" -hubkey "$Env:CODESONAR_HUB_USER_KEY_FILE"
          --project-file "$Env:CODESONAR_PROJECT_FILE"
          --sarif
          --src-root "$Env:GITHUB_WORKSPACE"
          -t 7200
      - name: Cleanup Credential files
        run: del "$Env:CODESONAR_HUB_USER_CERT_FILE", "$Env:CODESONAR_HUB_USER_KEY_FILE"
      - name: Push Analysis results to GitHub
        uses: github/codeql-action/upload-sarif@v1
        with:
          sarif_file: warnings.sarif
      - name: Generate Summary Report
        run: >
          & "$Env:CSPYTHON" "$Env:CODESONAR_GITHUB\sarif_summary.py"
          warnings.sarif
          "$Env:CODESONAR_HUB_URL"
          "$Env:PROJECT_NAME"
          --title "CodeSonar Analysis (Windows)"
          -o summary.md
      - name: Push Summary Report
        if: ${{ github.event.pull_request }}
        run: >
          & "$Env:CSPYTHON" "$Env:CODESONAR_GITHUB\push_github_pr_comment.py"
          --api-url "$Env:GITHUB_API_URL"
          --cafile "$Env:GITHUB_CAFILE"
          "$Env:GITHUB_REPOSITORY"
          "$Env:PULL_REQUEST_ID"
          GITHUB_TOKEN
          summary.md

For full details of the codesonar analyze command, see the CodeSonar manual: Using CodeSonar > Building and Analyzing Projects > Command Line Build/Analysis

Create a new branch named example_analysis1 from your example branch.

This branch will introduce your analysis workflow to GitHub, and will result in your first analysis of your Git repository.
```
git checkout example
git checkout -b example_analysis1
```
Add and commit your updated files to your Git repository and push the changes to GitHub.

If you need to add the GitHub server certificate file to your repository, you should do that here too.

For example:
```
git add .github/github.root.cacert
git add .github/workflows/analyze.yml
git commit -m "Add CodeSonar analysis workflow"
git push -u origin example_analysis1
```
Follow GitHub instructions to open a pull request targeting your analysis base branch.

Important: When opening the new pull request, be sure to set example as the base branch.
After the analysis completes, refresh the pull request Checks tab page to see the analysis results.
- You should see a Code scanning results item which can be expanded to reveal a CodeSonar item.
Click the CodeSonar item to show the analysis results.
- The analysis page will say "1 analysis not found". This is expected.
- Notice that the page shows a table of "Analyses". The row for the analyze.yml file will show "Not found" in the "Base branch" column.
  
  This is because we have not previously run an analysis on the example branch, yet GitHub wants to compare the analysis for your example_analysis1 branch against a previous analysis for the example branch. This condition always occurs when you run your first analysis on a base branch.
View your pull request Conversation page.

It will show a message with a summary of analysis results.
- The number of warnings, grouped into high/medium/low severity rankings.
- The most frequent warnings, by warning class.
Fix any errors with the analysis workflow or the summary content before going on to the next step.
Merge your example_analysis1 pull request.
- This will add the new analyze.yml file to your example branch.
- It will also cause GitHub to remember the analysis result from your pull request and use it as a "base" analysis for comparing "incremental" changes made later.

G. Incremental Analysis workflow setup

Pull the new merge commit for the example branch, then create a new branch named example_analysis2 from the example branch.
```
git checkout example
git pull origin
git checkout -b example_analysis2
```
Change the code and commit it.

Ordinarily, you would make changes to your code and commit the changes before pushing them to the GitHub server. To simulate making changes to the code for this zlib example we will merge a newer version of the zlib code into your branch. This will allow you to analyze the new version of the code and to let GitHub show you the differences.

We will merge version v1.2.12 of the zlib code by using the v1.2.12 git tag stored in the zlib repository.
```
git merge v1.2.12
```
The merge command should open a text editor asking you for a commit message. Accept the default message by saving and closing the text editor.
Push your changes to the GitHub server.
```
git push origin -u example_analysis2
```
Open a pull request that targets the example branch.

When opening the pull request for your new example_analysis2 branch, be sure to set example as the base branch.
Wait for the analysis workflow to complete, then check results.

The Code scanning results for your new pull request will highlight the differences between the first analysis and the second.

CONGRATULATIONS! You have finished setting up the workflow!

Notes

Modifications for password-based authentication

If you need to authenticate your CodeSonar commands with a password instead of with a certificate, make the following changes.

Instead of configuring GitHub secrets for a hub user certificate and corresponding private key, configure a secret for your hub user account password.

Name of Secret Example Value

CODESONAR_HUBUSER cshub_ci

CODESONAR_HUB_PASSWD mYpAssw0rd123

Name of Secret	Example Value
`CODESONAR_HUBUSER`	`cshub_ci`
`CODESONAR_HUB_PASSWD`	`mYpAssw0rd123`

When you are setting up the analyze.yml file, make the following additional changes.

Replace

     CODESONAR_HUB_USER_CERT: "${{ secrets.CODESONAR_HUB_USER_CERT }}"
     CODESONAR_HUB_USER_KEY: "${{ secrets.CODESONAR_HUB_USER_KEY }}"
     CODESONAR_HUB_USER_CERT_FILE: codesonar.hub.user.cert
     CODESONAR_HUB_USER_KEY_FILE: codesonar.hub.user.key

with

     CODESONAR_HUBUSER: "${{ secrets.CODESONAR_HUBUSER }}"
     CODESONAR_HUB_PASSWD: "${{ secrets.CODESONAR_HUB_PASSWD }}"
     CODESONAR_HUBPWFILE: codesonar.hub.user.passwd

Replace

        echo "$Env:CODESONAR_HUB_USER_CERT" | Out-File -Encoding Default "$Env:CODESONAR_HUB_USER_CERT_FILE" ;
        echo "$Env:CODESONAR_HUB_USER_KEY" | Out-File -Encoding Default "$Env:CODESONAR_HUB_USER_KEY_FILE"

with

        echo "$Env:CODESONAR_HUB_PASSWD" | Out-File -Encoding Default "$Env:CODESONAR_HUBPWFILE"

Replace each occurrence of

        -auth certificate -hubcert "$Env:CODESONAR_HUB_USER_CERT_FILE" -hubkey "$Env:CODESONAR_HUB_USER_KEY_FILE"

with

         -auth password -hubuser "$Env:CODESONAR_HUBUSER" -hubpwfile "$Env:CODESONAR_HUBPWFILE"

(note that there are multiple occurrences).

Replace each occurrence of

      run: del "$Env:CODESONAR_HUB_USER_CERT_FILE", "$Env:CODESONAR_HUB_USER_KEY_FILE"

with

      run: del "$Env:CODESONAR_HUBPWFILE"