GitLab CI/CD Implementation for .NET Core and Framework

The integration of Continuous Integration and Continuous Deployment (CI/CD) within the .NET ecosystem via GitLab transforms the software development lifecycle from a manual, error-prone process into an automated, streamlined pipeline. In a professional production environment, the objective is to eliminate the manual intervention required to build, test, and deploy applications, thereby ensuring that every commit to the version control system is automatically validated and delivered to the target environment. GitLab facilitates this through the use of Runners—agent applications that execute the instructions defined in a configuration file—allowing developers to maintain a consistent build environment regardless of where the source code originates. By leveraging these tools, organizations can achieve a state where code changes are automatically integrated into the main branch and deployed to servers, such as Internet Information Services (IIS), with minimal latency and maximum reliability.

Fundamental Architecture of GitLab CI/CD for .NET

The foundation of the GitLab CI/CD process lies in the distinction between Continuous Integration (CI) and Continuous Deployment (CD). Continuous Integration is the practice of automatically building and testing code changes every time a commit is pushed to the repository. This ensures that integration errors are caught early in the development cycle, reducing the cost of fixing bugs. Continuous Deployment extends this process by automatically pushing those validated changes into target production or staging environments.

GitLab implements these concepts using a Pipeline, which is a series of Jobs. A Job is a single execution unit that performs a specific task, such as running a build script or executing a suite of unit tests. These jobs are orchestrated by the .gitlab-ci.yml file, a configuration file located in the root of the project repository that defines the stages of the pipeline, the scripts to be executed, and the conditions under which these scripts should run.

The execution of these jobs is handled by the GitLab Runner. Depending on the requirements of the .NET application, different executors are used:

GitLab Shell Executor: This executor runs CI/CD jobs directly on the host machine. It provides superior control over the environment and is particularly useful for .NET Framework applications that require specific Windows-based dependencies and tools.
Docker Executor: This executor runs jobs within isolated containers. It is the preferred method for .NET Core, .NET 5, 6, 7, and 8, as it allows for the use of official .NET SDK docker images, ensuring a clean and reproducible environment for every build.

Environment Configuration for .NET Framework 4.X

Implementing CI/CD for .NET Framework 4.8 and earlier requires a Windows-based environment because these versions are not supported by Linux-based runners. The setup involves preparing a host machine that can act as the build server.

The most efficient way to prepare a .NET build environment is through the installation of Visual Studio. This installation provides the necessary compilers and build tools. However, a critical configuration step is required regarding the system environment variables. MSBuild.exe, the primary build engine for .NET, is not automatically added to the system PATH upon installation. To ensure the GitLab Runner can invoke the build engine, the following path must be manually added to the system PATH:

C:\Program Files\Microsoft Visual Studio\2022\Community\MSBuild\Current\Bin

Beyond the build engine, several other tools are essential for a fully functional pipeline:

Git for Windows: Used for version control and establishing the connection to the GitLab server. This can be the portable version, but git.exe must be present in the system PATH because the GitLab Runner operates as a Windows service.
NuGet.exe: This tool is responsible for managing and restoring dependencies. Its path must be explicitly defined in the YAML configuration to ensure the pipeline can retrieve necessary packages.
MSTest.exe: This utility is used to execute test cases, ensuring the code meets quality standards before deployment.

.NET Core and Modern .NET Implementation

For modern .NET applications (including .NET 6, .NET 8, and later), GitLab provides a specialized CI template designed to build, test, and analyze projects. Unlike the .NET Framework approach, this template is optimized for Linux runners.

The modern .NET pipeline utilizes Docker images for the build environment. While the container image provides a base SDK, the template can install additional .NET SDK versions using manual scripts, including versions pinned in a global.json file. This ensures that the build environment exactly matches the developer's local environment.

The modern pipeline supports several key features:

Dependency Management: Supports SDK-style NuGet <PackageReference> and msbuild-paket, which is auto-detected.
Cross-Compilation: Because the template runs on Linux, it is limited to building executables (AOT/R2R) specifically for the Linux runtime of the runner, such as linux-x64.
Package Publication: The pipeline can publish both .nupkg (package) and .snupkg (symbol) packages if symbol publication is activated.

Input Variable	Description	Default Value
publish-enabled / DOTNETPUBLISHENABLED	Determines if artifacts are published to a NuGet feed	false
nuget-repo / DOTNETNUGETREPO	The target URL of the NuGet package repository	N/A

GitLab Runner Setup and Registration on Windows

To enable the execution of .NET pipelines on a Windows host, the GitLab Runner must be installed and configured as a service.

The installation process begins with downloading the GitLab Runner for Windows. The executable should be saved in a dedicated directory, such as C:\Tools\GitLab-Runner, and renamed to gitlab-runner.exe for consistency.

Once the file is in place, the runner must be registered using an Administrative Command Prompt. The registration process involves the following commands and configurations:

Navigate to the runner directory.
Execute the registration command:
gitlab-runner.exe register
Provide the GitLab URL (e.g., http://gitlab.example.com).
Enter the Registration Token, which is located in the GitLab interface under Repository > Settings > CI/CD > Runners.
Provide a description for the runner to identify it within the GitLab UI.
Assign tags if necessary.
Select the executor; for .NET Framework and local Windows deployments, the "shell" executor is selected.

After registration, the runner service must be started:
gitlab-runner start

The status of the runner can be verified in the GitLab UI. A green indicator signifies the runner is active and ready to pick up jobs, while a gray indicator indicates the runner has not started or is inactive.

Common management commands for the Windows Runner include:

gitlab-runner.exe register: Used to register a new runner.
gitlab-runner.exe start: Starts the runner service.
gitlab-runner.exe stop: Stops the runner service.
gitlab-runner status: Checks the current state of the runner.

Automated Deployment to IIS via PowerShell

A primary goal of .NET CI/CD is the automation of the publishing process to Internet Information Services (IIS). In a manual scenario, a developer would build the project, publish the binaries, stop the website and application pool, transfer the files, and restart the services. GitLab CI/CD automates this entire sequence using PowerShell scripts within the pipeline.

The automation process relies on specific variables to define the environment:

$application_pool_name: The name of the IIS application pool that must be managed.
$publish_path: The temporary location where the published files are stored during the build.
$iis_worker_path: The final destination directory where the application runs on the IIS server.

The deployment sequence is executed through a series of PowerShell commands:

dotnet build: Compiles the project.
dotnet publish -c Release: Creates the deployment-ready binaries.
Stop-WebSite -Name $application_pool_name: Halts the website to prevent file-locking issues.
Stop-WebAppPool -Name $application_pool_name: Stops the application pool to ensure a clean overwrite.
Copy-Item $publish_path -Destination $iis_worker_path -Force: Transfers the new binaries to the production folder.
Start-WebAppPool -Name $application_pool_name: Restarts the pool.
Start-WebSite -Name $application_pool_name: Restarts the website.

Pipeline Configuration and .gitlab-ci.yml Analysis

The .gitlab-ci.yml file is the blueprint for the automation process. For a .NET Core project targeting IIS, the configuration is structured into stages: build, tests, and deploy.

The build stage handles the preparation of the application:
yaml build: stage: build script: - dotnet restore - dotnet build --no-restore - dotnet publish .\DotNetDocs\DotNetDocs.csproj -c Release -o $publish_path artifacts: paths: - $publish_path expire_in: '1 hrs' tags: - dotnet only: - develop - master
In this stage, dotnet restore ensures all dependencies are present. The dotnet publish command outputs the binaries to a path defined by the pipeline ID to avoid collisions between concurrent builds. Artifacts are preserved for one hour to be used by subsequent stages.

The testing stage ensures the code is functional:
yaml unit-test: stage: tests script: - dotnet test --no-build --verbosity normal tags: - dotnet only: - master - develop needs: [build]
The needs: [build] keyword ensures that tests only run if the build stage completes successfully.

The deployment stage handles the IIS integration:
yaml production: stage: deploy script: - | if((Get-WebSiteState -Name $application_pool_name).Value -ne 'Stopped'){ Write-Output ('Stopping WebSite: {0}' -f $application_pool_name) Stop-WebSite -Name $application_pool_name } - | if((Get-WebAppPoolState -Name $application_pool_name).Value -ne 'Stopped'){ Write-Output ('Stopping Application Pool: {0}' -f $application_pool_name) Stop-WebAppPool -Name $application_pool_name } - "Copy-Item $published_data_path -Destination $iis_worker_path -Force" - "Start-Sleep -s 5"
The use of conditional logic in PowerShell ensures that the pipeline does not fail if the website is already stopped. The Start-Sleep command provides a buffer to ensure the system has fully released file locks before the next operation.

NuGet Integration and Package Registry

For projects that produce libraries rather than executable applications, GitLab provides integration with the GitLab Package Registry. This allows for the distribution of NuGet packages without requiring an external server.

Authentication is handled automatically using the CI_JOB_TOKEN, which is a predefined variable provided by GitLab. This eliminates the need for manual secret configuration for internal registries. However, if the project needs to publish to an external repository such as nuget.org, a custom variable DOTNET_NUGET_API_KEY must be configured in the project's CI/CD settings.

The publication process supports:
- .nupkg files: The standard NuGet package format.
- .snupkg files: Symbol packages used for debugging.

Execution rules for publication are typically configured to run automatically on tagged release pipelines that are not pre-releases, while remaining manual for other pipeline instances to prevent accidental production releases.

Detailed Analysis of Implementation Strategies

The choice between a Shell Executor on Windows and a Docker Executor on Linux represents a fundamental strategic decision in .NET CI/CD. For legacy .NET Framework 4.x applications, the Shell Executor is an absolute requirement. This is due to the dependency on the Windows API and the MSBuild environment provided by Visual Studio. The impact for the user is a higher maintenance overhead, as the build server must be manually updated and configured.

In contrast, the Docker-based approach for .NET Core and .NET 6/8 offers a "stateless" build environment. Every job starts with a fresh container, eliminating the "it works on my machine" problem. The impact is a significantly more scalable architecture; multiple runners can be deployed across a cluster without worrying about local environment drift.

The use of PowerShell for IIS deployment demonstrates the power of integrating shell scripts into the CI/CD pipeline. By automating the stop-copy-start sequence, organizations reduce the downtime associated with deployments. The use of the $CI_PIPELINE_ID in the publish path is a critical detail; it prevents different pipeline runs from overwriting each other's binaries, which is essential for maintaining a history of deployments and enabling rollbacks.

Finally, the integration of the GitLab Package Registry through CI_JOB_TOKEN simplifies the developer experience. By removing the need to manage API keys for internal package sharing, the friction of dependency management is reduced. This creates a dense web of automation where code is committed, tested, packaged, and deployed with virtually no manual intervention, embodying the true essence of DevOps.