Quickstart: Create a build validation GitHub workflow
In this quickstart, you will learn how to create a GitHub workflow to validate the compilation of your .NET source code in GitHub. Compiling your .NET code is one of the most basic validation steps that you can take to help ensure the quality of updates to your code. If code doesn't compile (or build), it's an easy deterrent and should be a clear sign that the code needs to be fixed.
Prerequisites
- A GitHub account.
- A .NET source code repository.
Create a workflow file
In the GitHub repository, add a new YAML file to the .github/workflows directory. Choose a meaningful file name, something that will clearly indicate what the workflow is intended to do. For more information, see Workflow file.
Important
GitHub requires that workflow composition files to be placed within the .github/workflows directory.
Workflow files typically define a composition of one or more GitHub Action via the jobs.<job_id>/steps[*]
. For more information, see, Workflow syntax for GitHub Actions.
Create a new file named build-validation.yml, copy and paste the following YML contents into it:
name: build
on:
push:
pull_request:
branches: [ main ]
paths:
- '**.cs'
- '**.csproj'
env:
DOTNET_VERSION: '6.0.401' # The .NET SDK version to use
jobs:
build:
name: build-${{matrix.os}}
runs-on: ${{ matrix.os }}
strategy:
matrix:
os: [ubuntu-latest, windows-latest, macOS-latest]
steps:
- uses: actions/checkout@v3
- name: Setup .NET Core
uses: actions/setup-dotnet@v3
with:
dotnet-version: ${{ env.DOTNET_VERSION }}
- name: Install dependencies
run: dotnet restore
- name: Build
run: dotnet build --configuration Release --no-restore
In the preceding workflow composition:
The
name: build
defines the name, "build" will appear in workflow status badges.name: build
The
on
node signifies the events that trigger the workflow:on: push: pull_request: branches: [ main ] paths: - '**.cs' - '**.csproj'
- Triggered when a
push
orpull_request
occurs on themain
branch where any files changed ending with the .cs or .csproj file extensions.
- Triggered when a
The
env
node defines named environment variables (env var).env: DOTNET_VERSION: '6.0.401' # The .NET SDK version to use
- The environment variable
DOTNET_VERSION
is assigned the value'6.0.401'
. The environment variable is later referenced to specify thedotnet-version
of theactions/setup-dotnet@v3
GitHub Action.
- The environment variable
The
jobs
node builds out the steps for the workflow to take.jobs: build: name: build-${{matrix.os}} runs-on: ${{ matrix.os }} strategy: matrix: os: [ubuntu-latest, windows-latest, macOS-latest] steps: - uses: actions/checkout@v3 - name: Setup .NET Core uses: actions/setup-dotnet@v3 with: dotnet-version: ${{ env.DOTNET_VERSION }} - name: Install dependencies run: dotnet restore - name: Build run: dotnet build --configuration Release --no-restore
There is a single job, named
build-<os>
where the<os>
is the operating system name from thestrategy/matrix
. Thename
andruns-on
elements are dynamic for each value in thematrix/os
. This will run on the latest versions of Ubuntu, Windows, and macOS.The
actions/setup-dotnet@v3
GitHub Action is required to set up the .NET SDK with the specified version from theDOTNET_VERSION
environment variable.(Optionally) Additional steps may be required, depending on your .NET workload. They're omitted from this example, but you may need additional tools installed to build your apps.
- For example, when building an ASP.NET Core Blazor WebAssembly application with Ahead-of-Time (AoT) compilation you'd install the corresponding workload before running restore/build/publish operations.
- name: Install WASM Tools Workload run: dotnet workload install wasm-tools
For more information on .NET workloads, see
dotnet workload install
.The
dotnet restore
command is called.The
dotnet build
command is called.
In this case, think of a workflow file as a composition that represents the various steps to build an application. Many .NET CLI commands are available, most of which could be used in the context of a GitHub Action.
Create a workflow status badge
It's common nomenclature for GitHub repositories to have a README.md file at the root of the repository directory. Likewise, it's nice to report the latest status for various workflows. All workflows can generate a status badge, which are visually appealing within the README.md file. To add the workflow status badge:
From the GitHub repository select the Actions navigation option.
All repository workflows are displayed on the left-side, select the desired workflow and the ellipsis (...) button.
- The ellipsis (...) button expands the menu options for the selected workflow.
Select the Create status badge menu option.
Select the Copy status badge Markdown button.
Paste the Markdown into the README.md file, save the file, commit and push the changes.
For more, see Adding a workflow status badge.
Example build workflow status badge
Passing | Failing | No status |
---|---|---|
See also
Next steps
Feedback
https://aka.ms/ContentUserFeedback.
Coming soon: Throughout 2024 we will be phasing out GitHub Issues as the feedback mechanism for content and replacing it with a new feedback system. For more information see:Submit and view feedback for