Installation

Build Toolchain

The project uses the .NET 10 SDK with the Microsoft.NET.Sdk.Worker project type. Deterministic builds with locked NuGet restore (packages.lock.json).

Build & Publish

# Restore (locked mode — requires packages.lock.json)
dotnet restore -p:RestoreLockedMode=true

# Run tests
dotnet test -c Release

# Publish optimized self-contained single-file executable
dotnet publish src/JenkinsAsService `
    --nologo --configuration Release `
    -p:RestoreLockedMode=true `
    --runtime win-x64 --self-contained true `
    --output publish/x64/ `
    -p:PublishSingleFile=true `
    -p:IncludeNativeLibrariesForSelfExtract=true `
    -p:EnableCompressionInSingleFile=true `
    -p:PublishReadyToRun=true `
    -p:OptimizationPreference=Speed `
    -p:UseSharedCompilation=true `
    -p:DebuggerSupport=false `
    -p:MetadataUpdaterSupport=false `
    -p:Deterministic=true `
    -p:DebugType=Embedded `
    -p:DebugSymbols=true `
    -p:InformationalVersion="1.0.0" `
    /v:q /clp:ErrorsOnly

# Build MSI installer (requires WiX v5 SDK — auto-restored via NuGet)
dotnet build src/JenkinsAsService.Installer -c Release -p:PublishDir=../../publish/x64/ -p:Version=1.0.0

Publish Flags

The published output:

• JenkinsAsService.exe — Self-contained executable (~42MB, no .NET runtime needed)
• appsettings.json — Configuration template

NuGet Dependencies

Main Project

Test Project

MSI Installer

The project includes a WiX v5 MSI installer (src/JenkinsAsService.Installer/) that:

• Installs to C:\Program Files\Jenkins (customizable via install directory dialog or INSTALLFOLDER property)
• Registers the Jenkins Windows Service (LocalSystem, Automatic start)
• Configures Windows-level service recovery automatically (util:ServiceConfig — restart on all 3 failures after 10s, reset daily)
• Starts the service after install
• Stops and removes the service on uninstall
• Supports in-place upgrades (same UpgradeCode across versions)
• Shows BSD 3-Clause license agreement during install
• Default secret protection mode: EnvironmentVariable (reads from JENKINS_SECRET)

MSI Dialog Flow

LicenseAgreementDlg → InstallDirDlg → JenkinsConfigDlg → SecurityOptionsDlg → VerifyReadyDlg

MSI Structure

The installer project is excluded from the solution build (Build=false). Build it explicitly after publishing.

Installation

MSI (Recommended)

1. Download the .msi for your architecture from Releases
2. Run the installer — it walks through install path, Jenkins URL, agent secret, and secret protection mode
3. Done — the service registers and starts automatically

Silent Install

For automated deployments, use msiexec with public properties:

msiexec /i JenkinsAsService_1.0.4_x64.msi /qn `
    INSTALLFOLDER="D:\Jenkins" `
    JENKINS_URL="https://jenkins.example.com:8443" `
    JENKINS_SECRET="your-secret" `
    JENKINS_SECRET_MODE="EnvironmentVariable" `
    JENKINS_AGENT_NAME="" `
    JENKINS_JAVA_PATH=""

Portable (Archive)

For environments where MSI installation isn't possible, download the .7z or .rar archive from Releases:

1. Extract to a folder of your choice (e.g. D:\Jenkins)
2. Edit appsettings.json — fill in JenkinsURL, AgentSecret, and any other settings
3. Register and start the service:

sc.exe create Jenkins binPath= "D:\Jenkins\JenkinsAsService.exe" start= auto obj= LocalSystem
sc.exe failure Jenkins reset= 86400 actions= restart/10000/restart/10000/restart/10000
sc.exe start Jenkins

To configure secret protection, run the CLI before starting:

.\JenkinsAsService.exe update-secret --secret "your-secret" --url "https://jenkins:8443" --mode Dpapi --silent

To uninstall:

sc.exe stop Jenkins
sc.exe delete Jenkins

Automated Release

The GitHub Actions release workflow (.github/workflows/release.yml):

1. Push a tag matching v* (e.g., v1.0.4)
2. Runs tests, publishes optimized self-contained executables for x64 and x86
3. Builds MSI installers for both architectures via WiX v5
4. Creates .7z (LZMA2, max compression) and .rar (RAR5 with 5% recovery record) archives
5. Generates checksums.json with SHA256 hashes for all artifacts
6. Creates GitHub Release with auto-generated release notes

Release Artifacts

For a tag v1.0.4:

Service Recovery (Windows-Level)

The MSI installer configures Windows service recovery automatically via util:ServiceConfig:

• First / Second / Third failure: Restart the Service (after 10 seconds)
• Reset fail count after: 1 day