Commit aad12860 authored by Pierre Smeyers's avatar Pierre Smeyers
Browse files

feat: initial commit 

In this initial version, the .NET template implements 2 jobs:
- build (+unit tests)
- SonarQube analysis
parent edd2a1da

.gitlab/merge_request_templates/new_feature.md

+2 −2
Original line number Diff line number Diff line
@@ -8,8 +8,8 @@ Closes #999 
## Checklist



* General:

    * [ ] use [rules](https://docs.gitlab.com/ee/ci/yaml/#rules) instead of [only/except](https://docs.gitlab.com/ee/ci/yaml/#onlyexcept-advanced)

    * [ ] optimized [cache](https://docs.gitlab.com/ee/ci/caching/) configuration (wherever applicable)

    * [ ] use [rules](https://docs.gitlab.com/ci/yaml/#rules) instead of [only/except](https://docs.gitlab.com/ci/yaml/#onlyexcept-advanced)

    * [ ] optimized [cache](https://docs.gitlab.com/ci/caching/) configuration (wherever applicable)

* Publicly usable:

    * [ ] untagged runners

    * [ ] no proxy configuration but support `http_proxy`/`https_proxy`/`no_proxy`

CONTRIBUTING.md

+1 −1
Original line number Diff line number Diff line
@@ -61,7 +61,7 @@ To contribute: 


1. Create an issue describing the bug or enhancement you want to propose (select the right issue template).

2. Make sure the issue has been reviewed and agreed.

3. Create a Merge Request, from your **own** fork (see [forking workflow](https://docs.gitlab.com/ee/user/project/repository/forking_workflow.html) documentation).

3. Create a Merge Request, from your **own** fork (see [forking workflow](https://docs.gitlab.com/user/project/repository/forking_workflow/) documentation).

   Don't hesitate to mark your MR as `Draft` as long as you think it's not ready to be reviewed.



### Git Commit Conventions

README.md

+47 −61
Original line number Diff line number Diff line
@@ -4,8 +4,8 @@ This project implements a GitLab CI/CD template to build, test, and analyse your 


## Usage



This template can be used both as a [CI/CD component](https://docs.gitlab.com/ee/ci/components/#use-a-component) 

or using the legacy [`include:project`](https://docs.gitlab.com/ee/ci/yaml/index.html#includeproject) syntax.

This template can be used both as a [CI/CD component](https://docs.gitlab.com/ci/components/#use-a-component) 

or using the legacy [`include:project`](https://docs.gitlab.com/ci/yaml/#includeproject) syntax.



### Use as a CI/CD component
@@ -18,7 +18,7 @@ include: 
    # 2: set/override component inputs

    inputs:

      # ⚠ this is only an example

      build-args: "build --with-my-args"

      build-args: "-c Release"

```



### Use as a CI/CD template (legacy)
@@ -35,7 +35,7 @@ include: 
variables:

  # 2: set/override template variables

  # ⚠ this is only an example

  DOTNET_BUILD_ARGS: "build --with-my-args"

  DOTNET_BUILD_ARGS: "-c Release"

```



## Global configuration
@@ -44,7 +44,9 @@ The dotnet template uses some global configuration used throughout all jobs. 


| Input / Variable      | Description                            | Default value     |

| --------------------- | -------------------------------------- | ----------------- |

| `image` / `DOTNET_IMAGE` | The Docker image used to run the .NET SDK<br/>:warning: **set the version required by your project** | `mcr.microsoft.com/dotnet/sdk:latest` |

| `image` / `DOTNET_IMAGE` | The Docker image used to run the .NET SDK<br/>:warning: **set the version required by your project** | `mcr.microsoft.com/dotnet/sdk:latest` <br/>[![Trivy Badge](https://to-be-continuous.gitlab.io/doc/secu/trivy-badge-DOTNET_IMAGE.svg)](https://to-be-continuous.gitlab.io/doc/secu/trivy-DOTNET_IMAGE) |

| `project-dir` / `DOTNET_PROJECT_DIR` | The folder where solution (*.sln) or project (*.csproj) file is located | `.`  _(root project dir)_ |

| `nuget-sources` / `DOTNET_NUGET_SOURCES` | Space separated list of .Net NuGet package [sources](https://learn.microsoft.com/en-us/dotnet/core/tools/dotnet-nuget-add-source) (formatted as `somename:https://some.nuget.registry/some/repo/index.json anothername:https://another.nuget.registry/another/repo/index.json`) | _none_ |



## Jobs
@@ -56,81 +58,65 @@ It uses the following variable: 


| Input / Variable      | Description                              | Default value     |

| --------------------- | ---------------------------------------- | ----------------- |

| `build-args` / `DOTNET_BUILD_ARGS`      | Arguments used by the build job          | `build --with-default-args` |

| `build-args` / `DOTNET_BUILD_ARGS`      | Arguments used by the [build](https://learn.microsoft.com/en-us/dotnet/core/tools/dotnet-build) job          | _none_ |

| `build-dir` / `DOTNET_BUILD_DIR`      | The relative path to the folder where the built files are located          | `bin/Debug`   |

| `test-project-dir` / `DOTNET_TEST_PROJECT_DIR`      | The folder where Unit tests (*.cproj) file is located          | `.`  _(root project dir)_   |

| `test-extra-args` / `DOTNET_TEST_EXTRA_ARGS`      | Extra arguments used by the [test](https://learn.microsoft.com/en-us/dotnet/core/tools/dotnet-test?tabs=dotnet-test-with-vstest) job          | _none_   |

| `test-enabled` / `DOTNET_TEST_ENABLED`      | Set to `false` to disable tests execution          | `true`  |



### SonarQube analysis

#### Unit Tests and Code Coverage reports



If you're using the SonarQube template to analyse your DOTNET code, here are 2 sample `sonar-project.properties` files.

In order to implement the best GitLab and SonarQube integration, the .NET template requires your project to use some specific tools and plugins:



```properties

# see: https://docs.sonarsource.com/sonarqube-server/latest/analyzing-source-code/test-coverage/dotnet-test-coverage/

# set your source directories here (relative to the sonar-project.properties file)

sonar.sources=.

# exclude unwanted directories and files from being analysed

sonar.exclusions=output/**,**/*_test.dotnet

- Unit Tests report for [GitLab integration](https://docs.gitlab.com/ci/yaml/artifacts_reports/#artifactsreportsjunit) is generated with [JUnit Test Logger](https://github.com/spekt/junit.testlogger)

    

# set your tests directories here (relative to the sonar-project.properties file)

sonar.tests=.

sonar.test.inclusions=**/*_test.dotnet

  :information_source: the `JunitXml.TestLogger` package shall be added to your test projects ([see nuget](https://www.nuget.org/packages/JUnitXml.TestLogger))

- Unit Tests report for [SonarQube integration](https://docs.sonarsource.com/sonarqube-server/latest/analyzing-source-code/test-coverage/test-execution-parameters/#sonarcsxunitreportspaths) is generated with [Xunit Test Logger](https://github.com/spekt/xunit.testlogger) 

    

# tests report (TODO)

sonar.dotnet.testExecutionReportPaths=reports/sonar_test_report.xml

# coverage report (TODO)

sonar.dotnet.coverage.reportPaths=reports/coverage.cov

```

  :information_source: the `XunitXml.TestLogger` package shall be added to your test projects ([see nuget](https://www.nuget.org/packages/XunitXml.TestLogger))



More info:

  :warning: only required if you enabled [SonarQube analysis](#dotnet-sonar-job)

- Code Coverage is computed with [Coverlet](https://github.com/coverlet-coverage/coverlet):

  

* [dotnet language support](https://docs.sonarsource.com/sonarqube-server/latest/analyzing-source-code/test-coverage/dotnet-test-coverage/)

* [test coverage](https://docs.sonarsource.com/sonarqube-server/latest/analyzing-source-code/test-coverage/test-coverage-parameters/) & [test execution](https://docs.sonarsource.com/sonarqube-server/latest/analyzing-source-code/test-coverage/test-execution-parameters/) parameters

* [external analyzer reports](https://docs.sonarsource.com/sonarqube-server/latest/analyzing-source-code/importing-external-issues/external-analyzer-reports/)

  :information_source: the `coverlet.msbuild` package shall be added to your test projects ([see nuget](https://www.nuget.org/packages/coverlet.msbuild))



### `dotnet-lint` job

With those packages properly configured, the following reports are generated:



This job performs a [lint](link-to-the-tool) analysis of your code, mapped to the `build` stage.

| Report         | Format                                                                       | Usage             |

| -------------- | ---------------------------------------------------------------------------- | ----------------- |

| `reports/dotnet-test.junit.xml` | [JUnit](https://en.wikipedia.org/wiki/XUnit) test report(s) | [GitLab integration](https://docs.gitlab.com/ci/yaml/artifacts_reports/#artifactsreportsjunit) |

| `reports/dotnet-test.xunitnet.xml` | [xUnit.net v2](https://xunit.net/docs/format-xml-v2) test report(s) | [SonarQube integration](https://docs.sonarsource.com/sonarqube-server/latest/analyzing-source-code/test-coverage/test-execution-parameters/#sonarcsxunitreportspaths) |

| `reports/coverage.cobertura.xml` | [Cobertura XML](https://gcovr.com/en/stable/output/cobertura.html) coverage report | [GitLab integration](https://docs.gitlab.com/ci/yaml/artifacts_reports/#artifactsreportscoverage_report) |

| `reports/coverage.opencover.xml` | [OpenCover](https://github.com/OpenCover/opencover/wiki) coverage report | [SonarQube integration](https://docs.sonarsource.com/sonarqube-server/latest/analyzing-source-code/test-coverage/dotnet-test-coverage/#opencover) |



It uses the following variables:

### `dotnet-sonar` job



| Input / Variable      | Description                                | Default value     |

| --------------------- | ------------------------------------------ | ----------------- |

| `lint-image` / `DOTNET_LINT_IMAGE`      | The Docker image used to run the lint tool | `dotnet-lint:latest` |

| `lint-disabled` / `DOTNET_LINT_DISABLED`   | Set to `true` to disable the `lint` analysis| _none_ (enabled) |

| `lint-args` / `DOTNET_LINT_ARGS`       | Lint [options and arguments](link-to-the-cli-options) | `--serevity=medium` |

This job performs SonarQube analysis. 



### `dotnet-depcheck` job



This job enables a manual [dependency check](link-to-the-tool) analysis of your code, mapped to the `test` stage.



It uses the following variables:

It uses the following variable:



| Input / Variable      | Description                              | Default value     |

| --------------------- | ------------------------------------------ | ----------------- |

| `depcheck-image` / `DOTNET_DEPCHECK_IMAGE`  | The Docker image used to run the dependency check tool | `dotnet-depcheck:latest` |

| `depcheck-args` / `DOTNET_DEPCHECK_ARGS`   | Dependency check [options and arguments](link-to-the-cli-options) | _none_ |



### `dotnet-publish` job



This job is **disabled by default** and performs a publish of your built binaries.

| --------------------- | ---------------------------------------- | ----------------- |

| `sonar-host-url` / `SONAR_HOST_URL` | SonarQube server url                   | _none_ (disabled) |

| :lock: `SONAR_TOKEN`     | SonarQube authentication [token](https://docs.sonarsource.com/sonarqube-server/latest/user-guide/managing-tokens/#using-a-token) (depends on your authentication method) | _none_ |

| `sonar-extra-args` / `DOTNET_SONAR_EXTRA_ARGS`      | Extra arguments used by the [SonarScanner](https://docs.sonarsource.com/sonarqube-server/latest/analyzing-source-code/analysis-parameters/)          | _none_ |



It uses the following variables:

More info:



| Input / Variable      | Description                            | Default value     |

| --------------------- | -------------------------------------- | ----------------- |

| `publish-enabled` / `DOTNET_PUBLISH_ENABLED` | Variable to enable the publish job     | _none_ (disabled) |

| `publish-args` / `DOTNET_PUBLISH_ARGS`    | Arguments used by the publish job      | `publish --with-default-args` |

| :lock: `DOTNET_PUBLISH_LOGIN` | Login to use to publish           | **must be defined** |

| :lock: `DOTNET_PUBLISH_PASSWORD` | Password to use to publish     | **must be defined** |

* [dotnet language support](https://docs.sonarsource.com/sonarqube-server/latest/analyzing-source-code/test-coverage/dotnet-test-coverage/)

* [test coverage](https://docs.sonarsource.com/sonarqube-server/latest/analyzing-source-code/test-coverage/test-coverage-parameters/#csharp) & [test execution](https://docs.sonarsource.com/sonarqube-server/latest/analyzing-source-code/test-coverage/test-execution-parameters/#csharp) parameters

* [external analyzer reports](https://docs.sonarsource.com/sonarqube-server/latest/analyzing-source-code/importing-external-issues/external-analyzer-reports/#external-dotnet-issues)



### Secrets management



Here are some advices about your **secrets** (variables marked with a :lock:):



1. Manage them as [project or group CI/CD variables](https://docs.gitlab.com/ee/ci/variables/#define-a-cicd-variable-in-the-ui):

    * [**masked**](https://docs.gitlab.com/ee/ci/variables/#mask-a-cicd-variable) to prevent them from being inadvertently

1. Manage them as [project or group CI/CD variables](https://docs.gitlab.com/ci/variables/#define-a-cicd-variable-in-the-ui):

    * [**masked**](https://docs.gitlab.com/ci/variables/#mask-a-cicd-variable) to prevent them from being inadvertently

      displayed in your job logs,

    * [**protected**](https://docs.gitlab.com/ee/ci/variables/#protect-a-cicd-variable) if you want to secure some secrets

    * [**protected**](https://docs.gitlab.com/ci/variables/#protect-a-cicd-variable) if you want to secure some secrets

      you don't want everyone in the project to have access to (for instance production secrets).

2. In case a secret contains [characters that prevent it from being masked](https://docs.gitlab.com/ee/ci/variables/#mask-a-cicd-variable), 

2. In case a secret contains [characters that prevent it from being masked](https://docs.gitlab.com/ci/variables/#mask-a-cicd-variable), 

  simply define its value as the [Base64](https://en.wikipedia.org/wiki/Base64) encoded value prefixed with `@b64@`:

  it will then be possible to mask it and the template will automatically decode it prior to using it.

3. Don't forget to escape special characters (e.g.: `$` -> `$$`).

kicker.json

+48 −47
Original line number Diff line number Diff line
@@ -15,69 +15,70 @@ 
    },

    {

      "name": "DOTNET_BUILD_ARGS",

      "description": "Arguments used by the build job",

      "default": "build --with-default-args",

      "description": "Arguments used by the [build](https://learn.microsoft.com/en-us/dotnet/core/tools/dotnet-build) job",

      "advanced": true

    }

  ],

  "features": [

    },

    {

      "id": "lint",

      "name": "DOTNET lint",

      "description": "[DOTNET lint](link-to-the-tool) analysis",

      "disable_with": "DOTNET_LINT_DISABLED",

      "variables": [

      "name": "DOTNET_PROJECT_DIR",

      "description": "The folder where solution (*.sln) or project (*.csproj) file is located",

      "default": ".",

      "advanced": true

    },

    {

          "name": "DOTNET_LINT_IMAGE",

          "description": "The Docker image used to run the lint tool",

          "default": "docker.io/dotnet-lint:latest"

      "name": "DOTNET_BUILD_DIR",

      "description": "The relative path to the folder where the built files are located",

      "default": "bin/Debug",

      "advanced": true

    },

    {

          "name": "DOTNET_LINT_ARGS",

          "description": "Lint [options and arguments](link-to-the-cli-options)",

          "default": "--serevity=medium",

      "name": "DOTNET_NUGET_SOURCES",

      "description": "Space separated list of .Net NuGet package [sources](https://learn.microsoft.com/en-us/dotnet/core/tools/dotnet-nuget-add-source) (formatted as `somename:https://some.nuget.registry/some/repo/index.json anothername:https://another.nuget.registry/another/repo/index.json`)",

      "advanced": true

        }

      ]

    },

    {

      "id": "depcheck",

      "name": "DOTNET dependency check",

      "description": "[DOTNET dependency check](link-to-the-tool) analysis",

      "variables": [

      "name": "DOTNET_TEST_ENABLED",

      "description": "Set to false to disable tests execution",

      "default": "true",

      "type": "boolean",

      "advanced": true

    },

    {

          "name": "DOTNET_DEPCHECK_IMAGE",

          "description": "The Docker image used to run the dependency check tool",

          "default": "docker.io/dotnet-depcheck:latest"

      "name": "DOTNET_TEST_PROJECT_DIR",

      "description": "The folder where Unit tests (*.cproj) file is located",

      "default": "."

    },

    {

          "name": "DOTNET_DEPCHECK_ARGS",

          "description": "Dependency check [options and arguments](link-to-the-cli-options)",

      "name": "DOTNET_TEST_EXTRA_ARGS",

      "description": "Extra arguments used by the [test](https://learn.microsoft.com/en-us/dotnet/core/tools/dotnet-test?tabs=dotnet-test-with-vstest) job",

      "advanced": true

    }

      ]

    },

  ],

  "features": [

    {

      "id": "publish",

      "name": "Publish",

      "description": "Publish your package to a repository",

      "enable_with": "DOTNET_PUBLISH_ENABLED",

      "id": "dotnet-sonar",

      "name": "dotnet sonar",

      "description": "[Dotnet Sonar](https://docs.sonarsource.com/sonarqube-server/latest/analyzing-source-code/scanners/dotnet/using) analysis",

      "variables": [

        {

          "name": "DOTNET_PUBLISH_ARGS",

          "description": "Arguments used by the publish job",

          "default": "publish --with-default-args",

          "name": "SONAR_HOST_URL",

          "description": "SonarQube server url",

          "mandatory": true,

          "advanced": true

        },

        {

          "name": "DOTNET_PUBLISH_LOGIN",

          "description": "Login to use to publish",

          "secret": true

          "name": "SONAR_PROJECT_KEY",

          "description": "SonarQube Project Key",

          "advanced": true

        },

        {

          "name": "DOTNET_PUBLISH_PASSWORD",

          "description": "Password to use to publish",

          "name": "SONAR_TOKEN",

          "description": "SonarQube authentication token (see https://docs.sonarsource.com/sonarqube-server/latest/user-guide/managing-tokens/) - depends on your authentication method",

          "secret": true

        },

        {

          "name": "DOTNET_SONAR_EXTRA_ARGS",

          "description": "Extra arguments used by the [SonarScanner](https://docs.sonarsource.com/sonarqube-server/latest/analyzing-source-code/analysis-parameters/)",

          "advanced": true

        }

      ]

    }

templates/gitlab-ci-dotnet.yml

+153 −121

File changed.

Preview size limit exceeded, changes collapsed.