Quickstart with GitHub Actions
Tags: github, csharp, actions, nuget
Published: 2020-04-20 03:12:28

> This post has been written in 08/17/2019 on medium, I've been migrating all posts from medium to dev.to.

Hello everyone! Recently I’ve subscribed to the beta of GitHub Actions.
I was really excited to try it out, since I was getting kinda confused with Travis-CI, which, in my opinion was the best option for C# coders until now.

Well, finally the time has come! And I’ve already did my integration with GitHub Actions on a REAL project.
Explaining with mocked examples and test projects usually are a bit far from the reality of a real project. So I’ve decided to make it with my [OpenProtocolInterpreter](https://github.com/Rickedb/OpenProtocolInterpreter) project.

---

# **Project Scenario**

This project is a .net standard 2.0 solution, so I must run a **dotnet** command to build and test. Moreover I need to pack my **.nupkg** and publish on **NuGet**.

I’ve tried to use **Ubuntu** and **Mac OS** environment but, unfortunately, it’s just throwing up random errors, somehow it just doesn’t works by now. But windows works very well for the case!
> _Yes, I’ve already opened an issue about that_

# First things first

You need to create your workflow `.yml` file and it should be placed on **.github/workflows** folder, so GitHub can access it to run. Or, if you want, click in the **Action** tab and it will show you a screen with some templates to create your workflow. _(unfortunately I haven’t found a C# template right now)_

{% gist https://gist.github.com/Rickedb/be2d23ad48680e90cdc7f3f0fda83dba %}

Above you have my yml file and right below I will try to explain each section:

* `name`: means the name of your workflow, this is also the name that will be shown at our badge on readme file, so I do prefer using “master”;

* `on`: means what will trigger our workflow, for example: push, pull_request, etc;

* `push`: means that it will trigger when someone pushes a commit into our branch;

* `branches`: this section you can filter which branches you want to execute this workflow when the trigger happens _(no, you cannot trigger another branch which is not the one that you’re pushing in)_;

* `jobs`: jobs we will execute on this workflow;

* `build`: just the name of my job;

* `runs-on`: which environment we will run our job? Windows, Ubuntu or Mac? _(you can also specify the version)_;

* `steps`: dividing by steps our job workflow, which is nice to separate and to result in a better visualization when we look at GitHub Actions UI;

* `uses`: this one I will explain in the below section, since I think it worth to write about it. But think of it like a import or a list of functionalities;

* `steps.name`: the name of our step;

* `with`: right below it we will write our parameters that our `uses` will need _(or maybe optional parameters)_;

* `with.dotnet-version`: of course, the dotnet SDK version we want to use. When looking at [.Net Core list of SDKs](https://dotnet.microsoft.com/download/dotnet-core/3.0) always take the middle column name. Such as **3.0.100-rc1–014190** and **3.0.100-preview9–014004**;

* `run` : the command that you want to run _(Yeah, the CLI one)_.

# Talking about `uses` section

Think about it like an IMPORT section, maybe like a `using` when talking about C#, that will import everything that is in our **dll** and provide us common methods or for actions: **steps/jobs**.

We have 3 `uses` in our `yml`, they are: `actions/checkout@master`, `actions/setup-dotnet@master` and `warrenbuckley/Setup-Nuget@v1`.

All of them refers to a repository on GitHub that contains a yml with our imported functions that will be ran.
For example [actions/setup-dotnet](https://github.com/actions/setup-dotnet), if you take a look at their [action.yml](https://github.com/actions/setup-dotnet/blob/master/action.yml) file you will notice our `dotnet-version` parameter as an input param there.

So, in a few words, we use them to make our life easier.

* `actions/checkout`: help us to checkout our repository;

* `actions/setup-dotnet`: help us to download our .net core SDK into our virtual environment;

* `warrenbuckley/Setup-Nuget`: help us download NuGet environment **NuGet CLI** features. _(a big shout out to warrenbuckley for sharing this)_

> _Oh, and the `{repo}@master` means which branch you want to use._

# **Run commands**

> _This part might be the easier, since you probably know more about dotnet CLI commands._

We have 3 `run` commands, which respectively do the following:

1. Build my project on release configuration;
2. Build and test my unit tests project;
3. Publish our generated NuGet package to NuGet API.

> _Notice that the pipe `|` allow us to run multiple commands_

# **Using secrets**

You might have a key that cannot be shown to everyone in your yaml, such as my **NuGet API key**, for that you must register your secret at **Settings > Secrets** and accessing it by typing `${{ secrets.my_var }}`, in my case, it’s name is `NUGET_API_KEY`.

# **Adding badge on README**

To add the badge you need to use the url: `https://github.com/<OWNER>/<REPOSITORY>/workflows/<WORKFLOW_NAME>/badge.svg`

* `OWNER`: your username _(Rickedb)_;
* `REPOSITORY`: your repo _(OpenProtocolInterpreter)_;
* `WORKFLOW_NAME`: the name of your workflow, which I’ve mentioned it’s the first `name` parameter _(master)_.

Mine results in:
`https://github.com/rickedb/openprotocolinterpreter/workflows/master/badge.svg`

# **The final result**

At **Actions** tab you can see it live:

![Actions build log tab](https://miro.medium.com/max/700/1*c2p8QIF7f1cpRLQo8srZqw.png)

README:

![README Badge](https://miro.medium.com/max/556/1*8Xqo3GQ9Yjvc55XAXqYuZA.png)

# **References**

https://help.github.com/en/articles/about-github-actions

https://github.com/Rickedb/OpenProtocolInterpreter

https://github.com/actions

https://github.com/warrenbuckley/Setup-Nuget