Add Dotnet Core Workflow to GitHub Project

Posted by on May 22, 2021 in .net, git

Add GitHub Actions

While not really necessary for writing a simple application I like to add GitHub actions to projects. This helps to automate the building and testing of changes to ensure that we don't accidently introduce known defects.

In the root directory of your git repo do the following:

$ git checkout -b workflow
Switched to a new branch 'workflow'
$ git branch
  main
* workflow
$ mkdir -p .github/workflows
$ cd .github/workflows
$

GitHub Actions uses YAML syntax to define all of the necessary elements of a workflow. To enable the workflow they are stored in the .github/workflows direction of the repository.

Create workflow file

For this project we are going to create simple dotnet.yaml to enable a dotnet core workflow which will build and test the project.

First we want to give the workflow a name. This is the name that will appear on the GitHub Actions tab. If no name is provided then GitHub will use the name of the file.

name: .NET CI

The next step is to define some events that will trigger the workflow. I only want to trigger the workflow when changes are pushed to the main branch or when a pull request to the main branch is made.

By running the workflow when there is a pull request I can ensure that the code properly compiles and passes any tests before merging with the main branch.

Once code has been pushed to the main branch we run the workflow as well to make sure that the merges did not break anything.

By limiting the trigger to the main branch changes can be made on feature branches without triggering the workflow. This is useful since GitHub actions is billable by time used and we want to minimize the amount of time spent to only those actions that are important.

on:
  push:
    branches: [ main ]
  pull_request:
    branches: [ main ]

Now that we have determined what will trigger the workflow to run we need to define what the workflow will do. This can be one or more jobs. For this case we only need a single job.

Here we create the job build and give it a more descriptive name of Build and Test. This particular job we want to execute on the latest version of ubuntu.

jobs:
  build:

    name: Build and Test
    runs-on: ubuntu-latest

The last part of our workflow is going to be the steps necessary to execute the job. These steps are executed in the order that they appear. Each step in a job executes on the same environment and the results of each step is available to subsequent steps.

The first line steps is used to group all of the steps for the job.

The next line is the uses keyword. This retrieves another action. It is basically including additional steps from an external source. In this case from the community action actions/checkout@v2. This step will check out the code from the repository so that it is available to the environment.

The next step includes another community action called actions/setup-dotnet@v1. This is used to setup the environment to be able to use the dotnet tools. This step includes a few other keywords also. The first is the name parameter which we have used previously. This simply provides a friendly name for the step. The other keyword is the with keyword. This provides input to the action. In this case it is indicating the version of dotnet to be used.

    steps:
    - uses: actions/checkout@v2
    - name: Setup .NET
      uses: actions/setup-dotnet@v1
      with:
        dotnet-version: 5.0.x

Now that we have the environment setup and ready we can peform the steps necessary to actually build and test the project. Again we have the familiar name keyword used to provide a friendly name to the step.

There are two new keywords that we are using for each of these steps. The run keyword is used to specify a command to be executed. The working-directory is used to set the base directory where the command should be executed.

The dotnet restore command will restore any packages needed to build the project.

dotnet build --no-restore will build the project without attempting to perform the restore. We don't need to restore anything since we completed that in the previous step.

Once the project has been compiled we will want to run any tests to ensure that everything is working as we expect. This is accomplished by executing dotnet test --no-build --verbosity normal.

    - name: Restore dependencies
      run: dotnet restore
      working-directory: ./src
    - name: Build
      run: dotnet build --no-restore
      working-directory: ./src
    - name: Test
      run: dotnet test --no-build --verbosity normal
      working-directory: ./src

Here is the entire file.

name: .NET CI

on:
  push:
    branches: [ main ]
  pull_request:
    branches: [ main ]

jobs:
  build:

    name: Build and Test
    runs-on: ubuntu-latest

    steps:
    - uses: actions/checkout@v2
    - name: Setup .NET
      uses: actions/setup-dotnet@v1
      with:
        dotnet-version: 5.0.x
    - name: Restore dependencies
      run: dotnet restore
      working-directory: ./src
    - name: Build
      run: dotnet build --no-restore
      working-directory: ./src
    - name: Test
      run: dotnet test --no-build --verbosity normal
      working-directory: ./src

Push workflow to repository

Now that the workflow file has been created it is time to push it up to the GitHub repo by performing the following steps.

Verify current branch
Add workflow file
Commit workflow file
Push to remote branch

$ git branch
  main
* workflow
$ git add .github/workflows/dotnet.yaml
$ git status
On branch workflow
Changes to be committed:
  (use "git restore --staged <file>..." to unstage)
    new file:   .github/workflows/dotnet.yml

Untracked files:
  (use "git add <file>..." to include in what will be committed)

$ git commit -m "Add dotnet.yaml workflow"
[workflow 9caee5a] Add dotnet.yaml workflow
 1 file changed, 29 insertions(+)
 create mode 100644 .github/workflows/dotnet.yml
$ git push origin workflow
Enumerating objects: 6, done.
Counting objects: 100% (6/6), done.
Delta compression using up to 16 threads
Compressing objects: 100% (3/3), done.
Writing objects: 100% (5/5), 708 bytes | 708.00 KiB/s, done.
Total 5 (delta 0), reused 0 (delta 0), pack-reused 0
remote: 
remote: Create a pull request for 'workflow' on GitHub by visiting:
remote:      https://github.com/iesoftwaredeveloper/SimpleCmdLine/pull/new/workflow
remote: 
To github.com:iesoftwaredeveloper/SimpleCmdLine.git
 * [new branch]      workflow -> workflow

Create pull request

Now that we have pushed our changes to the remote we will want to create a pull request so that they can be merged into the main branch. This will do a few things.

Initiate the process of merging code
Initiate the new workflow

After initiating the pull request you will see that the workflow is triggered. This is because a pull request to main was made.

Screenshot showing workflow running on "workflow" branch

Once the workflow has completed the status of the workflow will be showed in the pull request. Wait until it shows completed and is green. If for some reason it does not complete successfully you will want to review the code changes and make any necessary updates to get the workflow passing as green.