public

GitHub Actions - Quickstart Guide

GitHub Actions is a system built into GitHub for automating software development workflows right inside of the repository. These Actions can be very useful to help speed up development, and reduce manual effort. With more efficient workflows developers can then spend more time writing code!

5 months ago

Latest Post NEW - ByteUnits Membership by Tyler Moon public

GitHub Actions is a system built into GitHub for automating software development workflows right inside of the repository. These Actions can be very useful to help speed up development, and reduce manual effort. With more efficient workflows developers can then spend more time writing code!

Prerequisites

Create A Repository

Head on over to GitHub and create a new repository called Linter-GitHub-Action-Example (or whatever you would like as the name does not really matter). Then clone the new repository to your local machine.

Add Basic HTML and JS

In order to have something to work with we are going to create a very basic website with a short HTML file and a little sprinkling of JavaScript. In the newly cloned repository add files called index.html and timeof.js. Then go ahead and push this up to your main branch (which used to be called the masterbranch by default but has now been changed to main).

Next add the following basic HTML and JS which will create a simple site that displays the current date and time.

index.html

<html>
    <head>
        <script src="timeof.js"></script>
    </head>
    <body>
        <div>
            <h2>The current datetime is:</h2><div id="timeslot"></div>
        </div>
    </body>
</html> 

timeof.js

window.onload = function() {
    var d =  new Date();
    document.getElementById("timeslot").innerHTML = d;
} 

Launching the index.html file in a browser should show something like the following:

Now that we have a basic site up and running go ahead and commit that to the repo. Next we can start writing some Actions!

Hello World Action

Creating GitHub Actions is quite simple. All Actions are configured via YAML (Yet Another Markup Language) in the .github/workflows directory of a repository. To get started create said directory in the example repository.

For our first Action lets create one that just outputs "Hello World" to the Actions console. Create a file .github/workflows/helloworld.yml and add the following content:

# This is a basic workflow to help you get started with Actions

name: Hello World

# Controls when the action will run. 
on:
  # Triggers the workflow on push or pull request events but only for the main branch
  push:
    branches: [ main ]
  pull_request:
    branches: [ main ]

  # Allows you to run this workflow manually from the Actions tab
  workflow_dispatch:

# A workflow run is made up of one or more jobs that can run sequentially or in parallel
jobs:
  # This workflow contains a single job called "build"
  build:
    # The type of runner that the job will run on
    runs-on: ubuntu-latest

    # Steps represent a sequence of tasks that will be executed as part of the job
    steps:
      # Checks-out your repository under $GITHUB_WORKSPACE, so your job can access it
      - uses: actions/checkout@v2

      # Runs a single command using the runners shell
      - name: Run a one-line script
        run: echo Hello, world!

      # Runs a set of commands using the runners shell
      - name: Run a multi-line script
        run: |
          echo Add other actions to build,
          echo test, and deploy your project.

Commit this to the repository and head over to www.github.com. Once in your repo click on the "Actions" tab and you should see an Action labeled "Hello World" running.

Clicking on "build" on the left side will open up the output, and then clicking "Run a one-line script" and "Run a multi-line script" will show the "Hello World" outputs.

And there you have it the first GitHub Action!

Create a Linter Action

Our first Action did not do very much other than output to the console. To really show how useful Actions can be lets create one that lints our repository and shows us any suggestions. These suggestions are not always required for the code to run but are more conforming to syntax best practices.

Create a new file .github/workflows/linter.yml and add the following content:

name: Super-Linter

# Run this workflow every time a new commit pushed to your repository
on: push

jobs:
  # Set the job key. The key is displayed as the job name
  # when a job name is not provided
  super-lint:
    # Name the Job
    name: Lint code base
    # Set the type of machine to run on
    runs-on: ubuntu-latest

    steps:
      # Checks out a copy of your repository on the ubuntu-latest machine
      - name: Checkout code
        uses: actions/checkout@v2

      # Runs the Super-Linter action
      - name: Run Super-Linter
        uses: github/super-linter@v3
        env:
          DEFAULT_BRANCH: main
          GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }}

Commit this file to the repo and a second Action should appear on the Actions tab in GitHub.

This time the Action should show red as it has failed. While our simple site technically works it does not follow some syntax style standards. Scrolling through the output of the "Run Super-Linter" section will list out what its recommending to be fixed.

In this case there are a few errors in both the HTML and JavaScript files.

Index.html Errors

Timeof.js Errors

Lets jump back into the code and fix these errors. Update the files to match the following:

index.html

<!DOCTYPE html>
<html>
    <head>
        <title>Simple Site</title>
    </head>
    <body>
        <div>
            <h2>The current datetime is:</h2><div id="timeslot"></div>
            <script src="timeof.js"></script>
        </div>
    </body>
</html>

timeof.js

window.onload = function () {
  const d = new Date()
  document.getElementById('timeslot').innerHTML = d
}

Commit both of these files and the linter Action should automatically trigger again. This time it should show green as all of the linter errors have been fixed!

There you have it an automatic linter working in your repository every time a commit to main is made! Neat!

Summary

In this article, we saw how to start utilizing GitHub Actions to automate software development workflows. Obviously there is a lot more that Actions can do but hopefully this helped getting started!

Tyler Moon

Published 5 months ago