build-and-test-dotnet.yml

name: Build and Test .NET solution

on:
  workflow_call:
    secrets:
      CHECKOUT_TOKEN:
        required: false
        description: >
          The GitHub token to authenticate checkout with. Pass in a GitHub personal access token if authenticated
          submodules are used.
      ENVIRONMENT_VARIABLES_JSON:
        required: false
        description: >
          A JSON string containing key-value pairs of environment variables to be set. You can use this to pass in
          arbitrary environment variables that can be used to e.g. customize the build or test execution. Example:
          ENVIRONMENT_VARIABLES_JSON: |
            {
              "MY_ENV_VAR": "value of environment variable",
              "MY_ENV_VAR2": "value of environment variable"
            }

    inputs:
      cancel-in-progress-for-this-pr:
        description: >
          When set to "true", it will cancel the already running workflow for this pull request. See the concurrency
          settings of the job for more details.
        type: string
        default: 'true'
      parent-job-name:
        description: >
          An optional technical identifier that is used to construct the concurrency key to be able to distinguish
          different jobs in the same parent workflow calling this one. This is necessary if you build multiple solutions
          (as separate jobs) in the same workflow for these jobs not to conflict with each other.
        type: string
        default: parent-job
        required: false
      cancel-workflow-on-failure:
        description: When set to "true", it will cancel the current workflow run with all jobs if this workflow fails.
        type: string
        default: 'true'
      # This needs to be stringified JSON because inputs don't support arrays, see
      # https://github.qkg1.topmunity/t/reusable-workflow-with-strategy-matrix/205676/2.
      machine-types:
        type: string
        default: '["ubuntu-24.04"]'
        description: >
          Stringified JSON array with the name of the type of machine(s) to run the workflow under, e.g.
          '["ubuntu-24.04"]' or '["ubuntu-24.04", "windows-2025"]'.
      repository:
        description: >
          Repository name with owner to git checkout, if not the current repository. E.g. "Lombiq/GitHub-Actions".
          Defaults to the current repository.
        type: string
        default: ${{ github.repository }}
      repository-ref:
        description: >
          The branch, tag or SHA to checkout. When checking out the repository that triggered the workflow, this
          defaults to the reference or SHA for that event. Otherwise, uses the default branch.
        type: string
        default: ''
      free-up-space:
        type: string
        default: 'false'
        description: >
          Frees up storage space on the runner by deleting files unnecessary for .NET projects. Since it takes time and
          can break prepared images, this is disabled by default. Enable it if the workflow fails with errors suggesting
          that the runner has insufficient storage space.
      dotnet-version:
        type: string
        default: 10.0.302
        description: Version of the .NET SDK to set up.
      node-version:
        type: string
        default: 24.10.0
        description: >
          The Node.js version. Can be a specific version number or other notations, see the documentation of
          https://github.com/actions/setup-node.
      node-package-manager-cache:
        type: string
        default: 'false'
        description: >
          Set to true to enable automatic caching based on the package manager field in package.json. By default,
          caching is disabled for this workflow (which is different from the underlying action's default behavior), to
          improve stability and backwards compatibility.
      blame-hang-timeout:
        type: string
        default: ''
        description: >
          Run the tests in blame mode and collects a hang dump when a test exceeds the given timeout. See
          https://learn.microsoft.com/en-us/dotnet/core/tools/dotnet-test for details on available values.
      build-directory:
        type: string
        default: .
        description: Path to the directory where a solution file can be found.
      build-configuration:
        type: string
        default: Release
        description: Configuration parameter for dotnet build, e.g. Release (default) or Debug.
      build-solution-path:
        type: string
        default: '*.sln?'
        description: >
          The path of the solution or project file to be built. If there's exactly one .sln or .slnx file in the build
          directory then this can be omitted. For further information, see the documentation of the build-dotnet action.
      build-verbosity:
        type: string
        default: quiet
        description: Verbosity parameter for dotnet build.
      build-enable-code-analysis:
        type: string
        default: 'true'
        description: Indicates whether to enable static code analysis during dotnet build.
      build-enable-nuget-caching:
        type: string
        default: 'false'
        description: >
          If set to "true", the NuGet packages will be cached by GitHub. This is faster if you have a lot of NuGet
          packages, but negligible or even slower if you only have a handful. When run on BuildJet, it will use the
          BuildJet cache instead of GitHub's, which is faster.
      build-enable-npm-caching:
        type: string
        default: 'false'
        description: >
          If set to "true", the NPM packages will be cached by GitHub. This is faster if you have a lot of NPM packages,
          packages, but negligible or even slower if you only have a handful. When run on BuildJet, it will use the
          BuildJet cache instead of GitHub's, which is faster.
      build-cache-version:
        type: string
        default: '0'
        description: >
          Change this to any other value to alter the cache key, effectively invalidating the latest cache. This is an
          alternative to clearing the cache manually, see
          https://docs.github.com/en/actions/using-workflows/caching-dependencies-to-speed-up-workflows#managing-caches.
      build-create-binary-log:
        type: string
        default: 'false'
        description: >
          Configures MSBuild to create a binary log. This is useful to inspect and debug builds. See
          https://github.com/dotnet/msbuild/blob/main/documentation/wiki/Binary-Log.md for details.
      build-binary-log-artifact-retention-days:
        type: string
        default: '14'
        description: >
          Duration in days after which the artifact of the build's binary log (if any) will expire. See
          https://github.com/actions/upload-artifact#retention-period for more details.
      build-fail-on-pending-changes:
        type: string
        default: 'true'
        description: >
          If set to "true", the workflow fails when the checked out repository has pending Git changes immediately
          after the build step.
      dotnet-test-process-timeout:
        required: false
        type: number
        default: -1
        description: Run the dotnet test process with the given timeout in milliseconds. -1 means no timeout.
      test-disable:
        type: string
        default: 'false'
        description: Disables test execution completely if set to "true".
      test-filter:
        type: string
        description: >
          Filter expression for dotnet test. See:
          https://learn.microsoft.com/en-us/dotnet/core/testing/selective-unit-tests.
      test-artifact-retention-days:
        type: string
        default: '7'
        description: >
          Duration in days after which the artifacts of testing (e.g. hang dump, diagnostic logs, if any) will expire.
          See https://github.com/actions/upload-artifact#retention-period for more details.
      xunit-max-parallel-threads:
        type: string
        default: '0'
        description: >
          Sets the maxParallelThreads configuration in all available xUnit xunit.runner.json configuration files. See
          https://xunit.net/docs/configuration-files#maxParallelThreads for details on available values.
      enable-test-diagnostic-mode:
        type: string
        default: 'false'
        description: >
          Enables diagnostic mode for `dotnet test` with the `--diag` flag and writes diagnostic messages to log files,
          to be uploaded as artifacts. See https://learn.microsoft.com/en-us/dotnet/core/tools/dotnet-test for details.
      test-show-time-remaining-until-timeout:
        type: string
        default: 'false'
        description: >
          Enables the output of a "Until timeout: Ns" type message every second during test execution. This can be
          helpful if you need an idea about the timing of the test outputs.
      ui-test-retry-interval-seconds:
        type: string
        required: false
        default: '30'
        description: >
          Interval in seconds to wait between retries of UI tests. Configuring a non-zero interval increases the chance
          that retries will be successful, due to load on the runner changing.
      timeout-minutes:
        type: number
        default: 360
        description: Configuration for the timeout-minutes parameter of the workflow. 360 is GitHub's default.
      verify-dotnet-consolidation:
        type: boolean
        default: true
        description: >
          When set to true, it will be verified whether the NuGet packages of the .NET solution are consolidated, i.e.
          the same version of a given package is used in all projects.
      dotnet-consolidation-exclude-version-regex:
        type: string
        required: false
        default: \-(alpha|preview)
        description: >
          A regular expression to match package versions that will be skipped during NuGet package consolidation. See
          the dotnet consolidate docs for details: https://github.com/olsh/dotnet-consolidate?tab=readme-ov-file#usage.
      dotnet-consolidation-exclude-project-path:
        type: string
        required: false
        default: src/*.Web/*.csproj
        description: >
          A path expression referring to the projects that should be temporarily removed from the solution before NuGet
          package consolidation. These are restored after the fact by resetting the git repository. The expression is
          passed to the Get-Item cmdlet as-is, so you can use wildcard characters and even specify multiple paths by
          separating them with a comma.
      warnings-as-errors:
        type: string
        default: 'true'
        description: >
          Whether compiler warnings should be treated as errors during the build process. The default value is "true",
          the compiler flag "-warnaserror" will be used, causing the build to fail if any warnings are generated. If set
          to "false", the flag "-warnaserror" will not be used, allowing warnings to be generated without causing the
          build to fail.
      collect-workflow-telemetry:
        type: string
        default: 'true'
        description: >
          If "true" (the default), detailed telemetry about the workflow run will be collected with
          https://github.com/catchpoint/workflow-telemetry-action.

jobs:
  # While the below steps seem suitable to DRY with build-and-test-orchard-core, since reusable workflows can't call
  # other workflows, they'd need to be encapsulated in a composite action. That, however, will result in a single step
  # being shown under the build details with all below steps mushed together.
  build-and-test:
    runs-on: ${{ matrix.machine-type }}
    name: Build and Test
    strategy:
      # The parameters added to the strategy matrix should also be used to construct the concurrency key.
      matrix:
        machine-type: ${{ fromJson(inputs.machine-types) }}
    timeout-minutes: ${{ inputs.timeout-minutes }}
    concurrency:
      # If "cancel-in-progress-for-this-pr" is set to "true" and this run is for a pull request, then the concurrency
      # key will be constructed from a handful of parameters to produce a value that would evaluate to the same value on
      # a subsequent push (while still allowing different solutions to be built with the same configuration), causing
      # the already running job (with the same strategy) for this pull request to be cancelled. Otherwise it will be the
      # ID of the workflow run combined with the strategy parameters, making it more unique so that parallel runs of
      # this job aren't kept waiting. This workflow's technical name is also included in both cases, so that it doesn't
      # conflict with other jobs calling a different workflow that are started by the same caller workflow. The caller
      # job's technical name is optionally included in the concurrency key, so that different jobs in the same parent
      # workflow calling this one don't conflict with each other.
      group: |
        ${{
          inputs.cancel-in-progress-for-this-pr == 'true' && github.event_name == 'pull_request'
            && format('{0}_build-and-test-dotnet_{1}_{2}_{3}', github.workflow, inputs.parent-job-name, matrix.machine-type, github.ref)
            || format('{0}_build-and-test-dotnet_{1}_{2}', github.run_id, inputs.parent-job-name, matrix.machine-type)
        }}
      cancel-in-progress: ${{ inputs.cancel-in-progress-for-this-pr == 'true' }}
    steps:
      # This has to be the first step so it can collect data about the whole workflow run.
      - name: Collect Workflow Telemetry
        if: inputs.collect-workflow-telemetry == 'true'
        uses: Lombiq/GitHub-Actions/.github/actions/workflow-telemetry@dev
        with:
          github_token: ${{ secrets.CHECKOUT_TOKEN }}

      - name: Set Environment Variables
        uses: Lombiq/GitHub-Actions/.github/actions/set-environment-variables@dev
        env:
          ENVIRONMENT_VARIABLES_JSON: ${{ secrets.ENVIRONMENT_VARIABLES_JSON }}

      - name: Free up Space
        if: inputs.free-up-space == 'true'
        uses: Lombiq/GitHub-Actions/.github/actions/free-up-space-for-dotnet@dev

      - name: Checkout
        uses: Lombiq/GitHub-Actions/.github/actions/checkout@dev
        with:
          repository: ${{ inputs.repository }}
          ref: ${{ inputs.repository-ref }}
          token: ${{ secrets.CHECKOUT_TOKEN }}

      - name: Verify that .NET packages are consolidated
        if: ${{ inputs.verify-dotnet-consolidation }}
        uses: Lombiq/GitHub-Actions/.github/actions/verify-dotnet-consolidation@dev
        with:
          directory: ${{ inputs.build-directory }}
          exclude-version-regex: ${{ inputs.dotnet-consolidation-exclude-version-regex }}
          exclude-project-path: ${{ inputs.dotnet-consolidation-exclude-project-path }}

      - name: Set up .NET
        uses: Lombiq/GitHub-Actions/.github/actions/setup-dotnet@dev
        with:
          dotnet-version: ${{ inputs.dotnet-version }}

      - name: Set up Node.js
        uses: Lombiq/GitHub-Actions/.github/actions/setup-node@dev
        with:
          node-version: ${{ inputs.node-version }}
          package-manager-cache: ${{ inputs.node-package-manager-cache }}

      - name: Build and Static Code Analysis
        uses: Lombiq/GitHub-Actions/.github/actions/build-dotnet@dev
        with:
          directory: ${{ inputs.build-directory }}
          configuration: ${{ inputs.build-configuration }}
          verbosity: ${{ inputs.build-verbosity }}
          enable-code-analysis: ${{ inputs.build-enable-code-analysis }}
          enable-nuget-caching: ${{ inputs.build-enable-nuget-caching }}
          enable-npm-caching: ${{ inputs.build-enable-npm-caching }}
          cache-version: ${{ inputs.build-cache-version }}
          solution-or-project-path: ${{ inputs.build-solution-path }}
          create-binary-log: ${{ inputs.build-create-binary-log }}
          binary-log-artifact-retention-days: ${{ inputs.build-binary-log-artifact-retention-days }}
          warnings-as-errors: ${{ inputs.warnings-as-errors }}

      - name: Verify Git Status is Clean
        if: inputs.build-fail-on-pending-changes == 'true'
        uses: Lombiq/GitHub-Actions/.github/actions/verify-git-status-clean@dev
        with:
          ignored-paths: |
            global.json
            build.binlog

      - name: Tests
        if: inputs.test-disable == 'false'
        uses: Lombiq/GitHub-Actions/.github/actions/test-dotnet@dev
        with:
          blame-hang-timeout: ${{ inputs.blame-hang-timeout }}
          build-directory: ${{ inputs.build-directory }}
          dotnet-test-process-timeout: ${{ inputs.dotnet-test-process-timeout }}
          solution-path: ${{ inputs.build-solution-path }}
          test-verbosity: ${{ inputs.build-verbosity }}
          test-filter: ${{ inputs.test-filter }}
          artifact-retention-days: ${{ inputs.test-artifact-retention-days }}
          xunit-max-parallel-threads: ${{ inputs.xunit-max-parallel-threads }}
          enable-diagnostic-mode: ${{ inputs.enable-test-diagnostic-mode }}
          show-time-remaining-until-timeout: ${{ inputs.test-show-time-remaining-until-timeout }}
          ui-test-retry-interval-seconds: ${{ inputs.ui-test-retry-interval-seconds }}

      - name: Cancel Workflow on Failure
        if: failure() && inputs.cancel-workflow-on-failure == 'true'
        uses: Lombiq/GitHub-Actions/.github/actions/cancel-workflow@dev
        env:
          GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }}