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.
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.
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.
Wth a successful completion of the workflow you can complete the pull request.
Your done. You have successfully added a simple dotnet workflow to your github project.