GitHub Actions and .NET

Article
12/14/2023

In this overview, you'll learn what role GitHub Actions play in .NET application development. GitHub Actions allow your source code repositories to automate continuous integration (CI) and continuous delivery (CD). Beyond that, GitHub Actions expose more advanced scenarios—providing hooks for automation with code reviews, branch management, and issue triaging. With your .NET source code in GitHub you can leverage GitHub Actions in many ways.

GitHub Actions

GitHub Actions represent standalone commands, such as:

actions/checkout - This action checks-out your repository under $GITHUB_WORKSPACE, so your workflow can access it.
actions/setup-dotnet - This action sets up a .NET CLI environment for use in actions.
dotnet/versionsweeper - This action sweeps .NET repos for out-of-support target versions of .NET.

While these commands are isolated to a single action, they're powerful through workflow composition. In workflow composition, you define the events that trigger the workflow. Once a workflow is running, there are various jobs it's instructed to perform. Each job defines any number of steps. The steps delegate out to GitHub Actions, or alternatively call command-line scripts.

For more information, see Introduction to GitHub Actions. Think of a workflow file as a composition that represents the various steps to build, test, and/or publish an application. Many .NET CLI commands are available, most of which could be used in the context of a GitHub Action.

Custom GitHub Actions

While there are plenty of GitHub Actions available in the Marketplace, you may want to author your own. You can create GitHub Actions that run .NET applications. For more information, see Tutorial: Create a GitHub Action with .NET

Workflow file

GitHub Actions are utilized through a workflow file. The workflow file must be located in the .github/workflows directory of the repository, and is expected to be YAML (either *.yml or *.yaml). Workflow files define the workflow composition. A workflow is a configurable automated process made up of one or more jobs. For more information, see Workflow syntax for GitHub Actions.

Example workflow files

There are many examples of .NET workflow files provided as tutorials and quickstarts. Here are several good examples of workflow file names:

Workflow file name

Description

build-validation.yml

Compiles (or builds) the source code. If the source code doesn't compile, this will fail.

build-and-test.yml

Exercises the unit tests within the repository. In order to run tests, the source code must first be compiled—this is really both a build and test workflow (it would supersede the build-validation.yml workflow). Failing unit tests will cause workflow failure.

publish-app.yml

Packages, and publishes the source code to a destination.

codeql-analysis.yml

Analyzes your code for security vulnerabilities and coding errors. Any discovered vulnerabilities could cause failure.

Encrypted secrets

To use encrypted secrets in your workflow files, you reference the secrets using the workflow expression syntax from the secrets context object.

${{ secrets.MY_SECRET_VALUE }} # The MY_SECRET_VALUE must exist in the repository as a secret

Secret values are never printed in the logs. Instead, their names are printed with an asterisk representing their values. For example, as each step runs within a job, all of the values it uses are output to the action log. Secret values render similar to the following:

MY_SECRET_VALUE: ***

Important

The secrets context provides the GitHub authentication token that is scoped to the repository, branch, and action. It's provided by GitHub without any user intervention:

${{ secrets.GITHUB_TOKEN }}

For more information, see Using encrypted secrets in a workflow.

Events

Workflows are triggered by many different types of events. In addition to Webhook events, which are the most common, there are also scheduled events and manual events.

Example webhook event

The following example shows how to specify a webhook event trigger for a workflow:

name: code coverage

on:
  push:
    branches:
      - main
  pull_request:
    branches:
      - main, staging

jobs:
  coverage:

    runs-on: ubuntu-latest

    # steps omitted for brevity

In the preceding workflow, the push and pull_request events will trigger the workflow to run.

Example scheduled event

The following example shows how to specify a scheduled (cron job) event trigger for a workflow:

name: scan
on:
  schedule:
  - cron: '0 0 1 * *'
  # additional events omitted for brevity

jobs:
  build:
    runs-on: ubuntu-latest

    # steps omitted for brevity

In the preceding workflow, the schedule event specifies the cron of '0 0 1 * *' which will trigger the workflow to run on the first day of every month. Running workflows on a schedule is great for workflows that take a long time to run, or perform actions that require less frequent attention.

Example manual event

The following example shows how to specify a manual event trigger for a workflow:

name: build
on:
  workflow_dispatch:
    inputs:
      reason:
        description: 'The reason for running the workflow'
        required: true
        default: 'Manual run'
  # additional events omitted for brevity

jobs:
  build:
    runs-on: ubuntu-latest

    steps:
      - name: 'Print manual run reason'
        if: ${{ github.event_name == 'workflow_dispatch' }}
        run: |
          echo 'Reason: ${{ github.event.inputs.reason }}'

    # additional steps omitted for brevity

In the preceding workflow, the workflow_dispatch event requires a reason as input. GitHub sees this and its UI dynamically changes to prompt the user into provided the reason for manually running the workflow. The steps will print the provided reason from the user.

For more information, see Events that trigger workflows.

.NET CLI

The .NET command-line interface (CLI) is a cross-platform toolchain for developing, building, running, and publishing .NET applications. The .NET CLI is used to run as part of individual steps within a workflow file. Common command include:

For more information, see .NET CLI overview