Category Archives: GitHub

Getting started with jekyll

GitHub pages, by default, uses jekyll and I wanted to get something running locally to test things.

Getting everything up and running

Let’s start by installed Ruby by going to RubyInstaller for Windows Downloads if you don’t already have Ruby and Gem installed.

Now go through the Jekyll Quick-start Instructions – I’ll list them here also.

  • gem install bundler jekyll
  • jekyll new my-awesome-site
  • cd my-awesome-site
  • bundle exec jekyll serve

So if all went well, the last line of these instructions will run up our jekyll site.

Testing our GitHub pages

  • Clone (if you don’t already have it locally) you repository with you GitHub pages
  • Run git checkout master, i.e. or where you store your markdown/html file content (in other words not the gh-pages branch if you’re using the standard master/gh-pages branches).
  • I don’t have a Gemfile, so in the root folder, create a file name Gemfile and here’s the contents (if you have a Gemfile add these two lines) 
    source 'https://rubygems.org'
gem 'github-pages', group: :jekyll_plugins
  • Run bundle install
  • Run bundle exec jekyll serve

Note: You can commit the Gemfile and Gemfile.lock files to your GitHub repository, these are not used by GitHub Pages.

After you’ve run up the server a _site folder will be created, these need not be committed.

Changing the theme

The first thing you might want to try is change the theme to one of the other supported themes. Simply open the _config.yml file and change the name of the theme, i.e.

theme: jekyll-theme-cayman

Other supported themes include

If you change the theme you’ll need to shut the server down and bundle exec jekyll serve which will run jekyll build and update the _site directory.

Adding images to your github README…

Obviously there are several ways to add images to your GitHub README.md or other mark down files in GitHub.

  1. Check them into the repository that includes the README.md
  2. Use a CDN or other file storage outside of GitHub
  3. Attach the image to an issue within your repository

If you are going to use the first option, then there’s an obvious downside, in that the image(s) are now part of your repo. and will add to the overall download, clone, fork etc.

Obviously the second option is great if you have CDN access of other filer space.

The third option is presented on GitHub Tricks: Upload Images & Live Demos and simply requires

  1. Create an issue in your repo
  2. Drag and drop the image from File Explorer (or the likes) into the comment section of the issue
  3. When the link is updated in the comment, i.e. you see the image, copy the link using your browser (i.e. right mouse click, copy link)
  4. Now use this link in your markdown

To use the link in GitHub markdown just use

![You Text](Image Url)

Getting started with GitHub and the .NET Core Action

GitHub actions allows us to add workflows to our projects.

In the previous three posts we looked at using Appveyor, Circleci and Travis CI to create our CI/CD pipelines, now let’s look at using GitHub Actions.

  • From your GitHub project, select the Actions tab
  • GitHub kindly lists a suggested workflow, so as my project is in C# it suggests a .NET Core build action, select Set up this workflow if it suits your needs (it does for this example)
  • You’ll now get to edit the Actions yml configuration, I’ll accept it by clicking Start commit and this will add the dotnet-core.yml to .github/workflows. Just click commit to add it to your repository.
  • From the Actions | .NET Core workflow, press the Create status badge, then Copy status badge Markdown and place this markdown into your README.md

Note: If you’re using the .NET Core workflow and using multi targets (i.e. <TargetFrameworks>netcoreapp3.1;net472</TargetFrameworks> then you may find the build failing because the .NET 4.7.2 frameworks is not installed.

The process described above, demonstrated that we have a YML based DSL for creating our workflow, checkout Workflow syntax for GitHub Actions.

Let’s take a look at a workflow file for one of my projects – in this case .NET core was not suitable, instead I wanted .NET Framework

name: .NET Core

on:
  push:
    branches: [ master ]
  pull_request:
    branches: [ master ]

jobs:
  build:

    runs-on: windows-latest

    steps:
    - uses: actions/checkout@v2
    - name: Setup MSBuild Path
      uses: warrenbuckley/Setup-MSBuild@v1
      
    - name: Setup NuGet
      uses: NuGet/setup-nuget@v1.0.2
     
    - name: Restore NuGet Packages
      run: nuget restore MyApplication.sln
 
    - name: Build
      run: msbuild MyApplication.sln /p:Configuration=Release /p:DeployOnBuild=true

The name is what you’ll see in your list of GitHub actions (via the GitHub project’s Actions tab/button, this workflow monitors pushes and pull requests on master and then has a list of jobs to undertake once this workflow is triggered.

We’re going to run this workflow on Windows as the project is a .NET framework application. The steps of the workflow specify the “parts” required to build and test the project, so require the checkout action and Setup-MSBuild, setup-nuget libraries. Then we run the nuget restore to get all nuget package then build the application.

Note: I’ve not include tests as yet on this workflow, so I’ll leave that to the reader.

As usual we’ll want to create a badge, in the Actions tab in GitHub, select the workflow and on the right of the screen is a button Create status badge. Click this then press the Copy status badge Markdown button and this will place the Markdown into your clipboard. Here’s an example of mine

![.NET Core](https://github.com/putridparrot/MyApplication/workflows/.NET%20Core/badge.svg)

Getting started with Travis CI and GitHub

As I’m seemingly trying out each free tier CI/CD online service I can, let’s look into Travis CI.

  • Create an account, with you preferred authentication provider (from the one’s they have available)
  • Sign-in, if not done so already
  • We need to click on Activate All Repositories using GitHub Apps
  • Then click Approve & Install. You can select specific repos. if you wish before click on this button
  • You’ll be asked to sign in again this will take you to GitHub where you click Authorise travis-pro if you wish to continue
  • You’ll then be redirected to Travis CI

Let’s get started

In your project’s repository add the file .travis.yml an example is shown below

language: csharp

branches:
  only:
  - master

If you’ve read the previous posts, you won’t be surprised to see another .yml file with the Travis CI DSL. If we take a look at Building a C#, F#, or Visual Basic Project we can see that the language for the .travis.yml is csharp for .NET languages C#, F# and VB.NET.

Here’s my .travis.yml for an F# .NET core project

language: csharp
mono: none
dotnet: 3.1
solution: FSharp.Health.sln

script:
  - dotnet build
  - dotnet test

Pretty straight forward, we use the script section for the steps to run the dotnet commands to build and test our code.

Ofcourse we’ll want to add a build badge to the README.md, so from the build within Travis CI simply click on the build badge next to your project name, then select FORMAT Markdown. Here’s an example for my FSharp.Health project

[![Build Status](https://travis-ci.com/putridparrot/FSharp.Health.svg?branch=master)](https://travis-ci.com/putridparrot/FSharp.Health)

Getting started with Circleci and GitHub

In my previous post I talked about using CI/CD along with GitHub and in that post we concentrated on Appveyor. Let’s now look at one of the alternatives, Circleci.

As you’d expect, you need to create an account and I used GitHub authentication as I wanted this CI/CD application working with my GitHub projects. It’s probably not a requirement but certainly everything integrated nicely (I’ve not yet seen if that differs with alternative repositories hosts).

Once you’ve created your account you’ll need to install the Circleci application within GitHub – I actually don’t recall the process but I suspect there’s an “Install Application” button or the likes.

Let’s get started

Due to the GitHub integration you’ll see a list of your projects. Simply press the Set Up Project button. That’s pretty much all there is to it to get started, but we’re probably going to want to customise the process.

In your project’s repository add the file config.yml into the .circleci folder, as below

.circleci/config.yml

This allows us to write the configuration for our Circleci build pipeline using a DSL. Here’s one for an F# project I have in Circleci

 version: 2.1

 orbs:
  win: circleci/windows@2.2.0

 jobs:
   build:
     executor: win/default     
    
     steps:
       - checkout
       - run: dotnet build
       - run: dotnet test Image.Processing.Tests

In this case we’re using the 2.1 (see CircleCI 2.1 Configuration Reference Guide.

The first thing we do (after setting the version of the DSL) is to map to an orb definition. In this case we’re using a predefined orb, we can actually create our own orbs if needed (but we’re not going there at the moment, or maybe ever, we’ll have to wait and see).

Note: An orb is a shareable package of configuration, see Explore Orbs for a whole bunch of different orbs..

Now we supply the jobs. In this case a build job using win/default, basically a Windows image.

Next we set up the build steps. These are self-explanatory, as you’d expect, we need to checkout our code, build the code and then run our tests. There’s a checkout step, the rest can be thought of as simply commands to run.

We’re now going to want to add a badge to the README.md in our project to allow us and others to see the status of our build.

Unlike Appveryor (unless I’m missing something, in which case I’ll update this post later) there’s no copy & paste option for the badge link, instead have a look as Adding Status Badges, here’s the template

[![<ORG_NAME>](https://circleci.com/<VCS>/<ORG_NAME>/<PROJECT_NAME>.svg?style=svg)](<LINK>)

So for my F# Image.Processing project this looks like the following

[![putridparrot](https://circleci.com/gh/putridparrot/Image.Processing.svg?style=svg)](https://circleci.com/gh/circleci/circleci-docs)

At this time, I’m not sure how to link to the specific build (or whether this is possible), I ‘ll add to this post in the future if I find it’s possible.

Note: If you prefer, change style=svg to style=shield for a different looking status image.

That should get you started.

Getting started with Appveyor and GitHub

I wanted to add some CI/CD (more CI than CD) to some of my GitHub projects. There’s several options available for this, including online or on-prem. Two seemed to catch my eye on other GitHub repositories, Appveyor and Circleci.

Both offer free plans which, as you’d expect, have some limitations. However for the most part these are things that don’t matter too much to my projects, i.e. you may be limited to public repositories only (hence they’re supporting OSS), probably only run a single build at a time etc.

Let’s get started

The application we’re going to look into here is AppVeyor.

Simply create an account and I used GitHub authentication to sign in – seemed logical as I was ultimately wanting this to integrate into GitHub.

Once you’ve signed in you’ll be presented with an Install button to install their app. into your GitHub space – I assume this is how it works, I’ve not looked into it further, either way this hooks into your repo. changes and triggers your project’s build.

Next up you go to the Project option in the Appveyor UI and select New Project. To be honest all is pretty obvious. Now with the GitHub integration you’ll get a list of available projects from your GitHub account.

Select Add and you’re done! Well sort of…

You may need to make some configuration changes, either within the Appveyor UI or better still (imho) via their DSL.

All you need to do is add a file named appveyor.yml. Here’s a simple example for a .NET project

version: 1.0.{build}

image: Visual Studio 2019

build:
  verbosity: minimal

before_build:
- cmd: nuget restore

Checkout the appveyor.yml reference for more information.

Basically what we’ve done in the above yml, is created a a build version, this will be displayed within the Appveyor UI when you inspect builds. Next we’ve stated what image we want to use to build our project, obviously Visual Studio 2019 is specified for my .NET projects.

The build can be set to quiet, minimal, normal or detailed. For now mine is minimal.

Finally I’ve added a pre-build step (before_build) and listed the command nuget restore. This was because for the projects I’ve tried, I have to update the nuget packaged first.

We’re not specifying the branches, but we can add a whitelist of branches that should be part of the build like this

branches:
  only:
    - master
    - production

By default Appveyor detects whether there’s tests and can run these automatically, but you might prefer to set a custom test step. For example I found an F# project ran tests fine locally but failed on Appveyor, adding the following solve this (here I’ve specified the assembly to test)

test_script:
- cmd: dotnet test FSharp.Units.Tests

Next up we’ll want to have a badge in our README.md so we can see the state of our build or better still, others can see the state of our build. If you select the project’s settings and then the Badges option, there’s a sample markdown code section where you can just copy the markdown and place in your README.md and it’ll show the build status in a nice little indicator.

Here we’ve looked at the basics for setting up a build with the DSL. Obviously this is a great way of doing things, but whilst setting up your DSL it means for every change, you need to commit and push then wait for the build to complete to see if everything works. In Appveyor you can go to the Setting | General option of your project and click Ignore appveyor.yml and instead set everything up in the Appveyor UI. Then you can go to the Settings | Export YAML option to generate your configuration.

That should get you started.

Deploying React to GitHub Pages

  • Create a new repository on GitHub, so we have something to refer to mine’s called react.io so simply replace this with your repo name within these steps, also the steps will show my GitHub repository at putridparrot, again replace this with your GitHub username.
  • Clone the repository onto your local machine
  • In the parent folder of your cloned repository run 
    yarn create react-app react.io --typescript

    Note: without –typescript if you want plain JavaScript code.

  • cd back into your repo folder and type 
    yarn add gh-pages -D
  • Open your packages.json and add the following (below the “verson” is a good place) 
    "homepage": "http://putridparrot.github.io/react.io",
  • Next up we need to add a predeploy and deploy script within the “scripts” section of the packages.json, so add these 
    "deploy": "gh-pages -d build",
"predeploy": "yarn run build"
  • Run the following from your shell/terminal 
    yarn deploy

When we run yarn deploy the predeploy script is run and will create a gh-pages branch on your GitHub remote repo. Also it will default to this branch and when you go to the Settings page of your repository and scroll to the GithHub Pages section, you should see the source set to gh-pages branch.

As this point my React GitHub pages site should be visible at 

https://putridparrot.github.io/react.io/

You may well want to push the source of your React application to GitHub as well, so simply commit and push to master or another branch, DO NOT overwrite the gh-pages branch, this is basically your deployed site.

To update your GitHub pages, simply run the following each time you’re ready to deploy to gh-pages

yarn deploy

The updated deployment may take up to ten minute to become available.