Skip to content

GitLab CI template for dotnet

This project implements a GitLab CI/CD template to build, test, and analyse your .NET projects.

Usage

This template can be used both as a CI/CD component or using the legacy include:project syntax.

Use as a CI/CD component

Add the following to your .gitlab-ci.yml:

include:
  # 1: include the component
  - component: $CI_SERVER_FQDN/to-be-continuous/dotnet/gitlab-ci-dotnet@1.0.0
    # 2: set/override component inputs
    inputs:
      # ⚠ this is only an example
      build-args: "-c Release"

Use as a CI/CD template (legacy)

Add the following to your .gitlab-ci.yml:

include:
  # 1: include the template
  - project: 'to-be-continuous/dotnet'
    ref: '1.0.0'
    file: '/templates/gitlab-ci-dotnet.yml'

variables:
  # 2: set/override template variables
  # ⚠ this is only an example
  DOTNET_BUILD_ARGS: "-c Release"

Global configuration

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
⚠ set the version required by your project		 mcr.microsoft.com/dotnet/sdk:latest
Trivy Badge
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 (formatted as somename:https://some.nuget.registry/some/repo/index.json anothername:https://another.nuget.registry/another/repo/index.json) none

Jobs

dotnet-build job

This job performs build and tests at once.

It uses the following variable:

Input / Variable Description Default value
build-args / DOTNET_BUILD_ARGS Arguments used by the 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 job none
test-enabled / DOTNET_TEST_ENABLED Set to false to disable tests execution true

Unit Tests and Code Coverage reports

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

ℹ the JunitXml.TestLogger package shall be added to your test projects (see nuget) - Unit Tests report for SonarQube integration is generated with Xunit Test Logger

ℹ the XunitXml.TestLogger package shall be added to your test projects (see nuget)

⚠ only required if you enabled SonarQube analysis - Code Coverage is computed with Coverlet:

ℹ the coverlet.msbuild package shall be added to your test projects (see nuget)

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

Report Format Usage
reports/dotnet-test.junit.xml JUnit test report(s) GitLab integration
reports/dotnet-test.xunitnet.xml xUnit.net v2 test report(s) SonarQube integration
reports/coverage.cobertura.xml Cobertura XML coverage report GitLab integration
reports/coverage.opencover.xml OpenCover coverage report SonarQube integration

dotnet-sonar job

This job performs SonarQube analysis.

It uses the following variable:

Input / Variable Description Default value
sonar-host-url / SONAR_HOST_URL SonarQube server url none (disabled)
🔒 SONAR_TOKEN SonarQube authentication token (depends on your authentication method) none
sonar-extra-args / DOTNET_SONAR_EXTRA_ARGS Extra arguments used by the SonarScanner none

More info:

Secrets management

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

  1. Manage them as project or group CI/CD variables:
    • masked to prevent them from being inadvertently displayed in your job logs,
    • protected 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, simply define its value as the 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.: $ -> $$).