NDepend GitHub Action

Send us an email at devops@ndepend.com for product and sales questions.

This GitHub Action lets run an NDepend analysis after each rebuild and explore results in a shared interactive HTML+js report (see some sample reports here). Reports generated by the GitHub action contain links to code source hosted by GitHub.

This Action can also fail the build upon some Quality Gate(s) failure and provide code quality estimations for each build or each pull-request.

With a Developer license, the standalone app VisualNDepend.exe or the NDepend Visual Studio extension can download the NDepend Github Action analysis results locally for further exploration.

See the action on the GitHub marketplace here.

Activate the 28-Day Trial For your Repository

Get the trial activation data from this page. Then go to the Settings of your repository:

From the left side bar goto Secrets > Actions, create a new secret named NDependLicense and paste the trial activation data obtained.

License Activation

The NDepend GitHub Action license activation is similar to the trial activation explained above. Associate your license key XYZ with your GitHub account from this url: https://www.ndepend.com/activation_githubaction?license=XYZ

From there you obtain a textual activation data. Then go to the Settings of your GitHub repository. From the left side bar goto Secrets > Actions, create a new secret named NDependLicense and paste the textual activation data obtained.

Usage

The ndepend action must be added after your build and unit testing actions, note that only the license parameter is mandatory.

- name: NDepend
    uses: ndepend/ndepend-action@v1
    with:
      GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }}  
      license: ${{ secrets.NDependLicense }}

After the analysis, the ndepend result is stored as an artifact of your build, and to explore it you have two options:

• Download the zipped ndepend artifact from your build summary, and open the generated HTML + js report it contains.
• Access the result from VisualNDepend or the Visual Studio extension as explained below.

Fail the Build upon Quality Gate Violation

A quality gate is a code quality goal. Such quality goal must be enforced before releasing and eventually, before committing to source control.

A quality gate can be seen as a PASS/FAIL criterion for software quality.

A dozen of default quality gates are proposed by NDepend. They are related to measures like technical debt amount, code coverage or amount of issues with particular severity. NDepend makes it easy to modify existing quality gates or create your own ones. This is explained here.

To break the build if at least one quality gate failed, just specify the stopIfQGFailed parameter:

- name: NDepend
    uses: ndepend/ndepend-action@v1
    with:
      GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }}  
      license: ${{ secrets.NDependLicense }}
      stopIfQGFailed: true

If the build fails because of a quality gate failure and this option stopIfQGFailed, this is explained with an annotation:

The detail of which quality gate(s) fail is then shown in the build summary (see the screenshot below in the next section).

Build Summary

An NDepend summary is available in your build summary to show the Quality Gates and issues status. Quality Gates are explained in the section above.

Pull Request Quality Check

When an analysis is done after the creation of a Pull Request, the NDepend action adds a comment to your PR. This comment contains the quality gates status and the number of issues per severity, same presentation as the Build Summary in the screenshot above. And to have more details you can click on the link provided in the comment.

The Action Options

Custom NDepend Configuration

An NDepend project file (.ndproj extension) can be provided to the action through the parameter customconfig. This is the way to provide custom settings, custom rules and custom quality gates (embedded in the project). The project.ndproj file must be uploaded to your repository, its path is relative to your repository root, and it can have any file name (but still a .ndproj extension).

- name: NDepend
    uses: ndepend/ndepend-action@v1
    with:
      GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }}  
      license: ${{ secrets.NDependLicense }}
      customconfig: project.ndproj

This parameter is optional and if no project is provided, the ndepend action uses the default settings and the default rule-set.

Define the Visual Studio Solution Analyzed

By default the ndepend action parse the solution file (.sln extension) existing in your repository. However, if more than one .sln file are found, you have to specify which solution to parse. The solution parameter can then be used :

- name: NDepend
    uses: ndepend/ndepend-action@v1
    with:
      GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }}  
      license: ${{ secrets.NDependLicense }}
      solution: src/mysolution.sln

The solution path is relative to your repository root.

Define the Baseline

NDepend can report Code diff & Quality diff since a baseline. To define such baseline the baseline parameter must be specified :

- name: NDepend
    uses: ndepend/ndepend-action@v1
    with:
      GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }}  
      license: ${{ secrets.NDependLicense }}
      baseline: recent

The baseline parameter can have one of these values:

• recent : to compare with the most recent build analyzed by the action.
• {branchname}_recent : To compare with the most recent build of the branch with name branchname. For example, to compare with the recent build of the branch named mydev.

  - name: NDepend
  uses: ndepend/ndepend-action@v1
  with:
    GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }}  
    license: ${{ secrets.NDependLicense }}
    baseline: mydev_recent
  

• {run_number} : The run number of a build already analyzed by the action. For example, to compare with the build with run number 30 :

  - name: NDepend
      uses: ndepend/ndepend-action@v1
      with:
        GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }}  
        license: ${{ secrets.NDependLicense }}
        baseline: 30
  

Import Code Coverage Data

Code coverage data is imported from coverage result files generated by the coverage tools. To import coverage data, you have to specify the coveragefolder parameter :

- name: NDepend
    uses: ndepend/ndepend-action@v1
    with:
      GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }}  
      license: ${{ secrets.NDependLicense }}
      coveragefolder: ${{ env.GITHUB_WORKSPACE }}/CoverageOut

This way the NDepend default rules about code coverage will be executed. See this documentation about coverage technologies and formats supported by NDepend and other code coverage data usage.

NDepend Result Artifact Retention

The NDepend action store the analysis result as artifact . However, to optimize the storage of your GitHub account you can use the retention-days parameter to specify the retention period of the NDepend artifacts.

- name: NDepend
    uses: ndepend/ndepend-action@v1
    with:
      GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }}  
      license: ${{ secrets.NDependLicense }}
      retention-days: 10

For an artifact that is meant to be used for a while - like a run result used as baseline - it is important to make sure its retention period is appropriate.

Download and Use Results from GitHub

Downloading an NDepend project from GitHub

It is possible to download an NDepend project from the NDepend Visual Studio extension or VisualNDepend.exe. Up to 3 items are downloaded locally:

• The NDepend project file (.ndproj extension). This project references one or several Visual Studio solution(s) (see the Project Properties > Code to Analyze panel). To run an analysis locally from such project downloaded from GitHub, the solution(s) referenced must be available locally in the proper relative directory precised in the NDepend project.
• Any analysis result produced during a GitHub run. The corresponding report is also downloaded locally and can be opened from the View Report NDepend UI menu. Such report contains links to hosted source code in the GitHub repo.
• If the project baseline is defined with a specific GitHub run number (see explanations below), the baseline analysis result is downloaded too and all diff features are available.

To download a project from GitHub 3 items must be provided:

• The GitHub PAT (GitHub Personal Access Token)
• The GitHub Account
• The GitHub Repository

The "Download Project from GitHub menu" is shown side-by-side with all occurrences of "Open local project" menu.

Defining the GitHub PAT (Personal Access Token)

Here is the GitHub documentation that explains how to create a PAT (Personal Access Token). Such PAT is needed to download any NDepend GitHub action result locally.

The GitHub PAT can be stored in a crypted file locally. This can be achieved either:

• Manually: through the NDepend Options :
• Or automatically: through NDepend.Console.exe /RegGitHubPAT XYZ :

Defining the GitHub Account and Repo of an NDepend project

In the NDepend Project Properties > GitHub panel, the GitHub Account and Repository corresponding to the project can be precised:

The GitHub Run# Used for Baseline

Defining the GitHub Account and Repo of an NDepend project is useful to download some analysis results from GitHub, and especially the baseline analysis result:

Here is how to define a particular Run analysis result as the baseline of a project:

If the PAT is registered locally and if the account and repository are defined in a project, when analyzing it the baseline can then be downloaded automatically: