What are Github Actions and how to set them up

I hadn't dabbled much with GitHub Actions (GHA), until I set up a project using GHA for a project I was working on about 8 months ago.

GHA workflows are a means to automate code builds in the dev, testing and deployment pipelines and is one of several continuous integration and continuous delivery (CI/CD) tools.

GHA allows developers to run workflows based on events.
An event is a specific activity in a code repository that triggers a workflow run.

For example, activity can originate from GitHub when someone creates a pull request (PR), opens an issue, or pushes a commit to a repository.

You can run a workflow to automatically add the appropriate labels whenever someone creates a new issue in your repository.

A workflow contains one or more jobs which can run in sequentially or in parallel.

Each job will run inside its own virtual machine runner, or inside a container. The job has one or more steps that either run a script that you define or run in an action.

Setting up GHA configuration or config files

GHA requires a yml.config file to configure local actions to a cloud-based platform. These config files need to be in the root directory and placed in a folder which is a .github folder to be parsed (read).

In the subfolder of workflows you can determine as many config files as you require.

For example, .github/workflows/config1.yml outlines the first set of rules to configure. To add multiple configs for different jobs, all you need to do is to append another file in the same folder for these additional config rules - .github/workflows/config2.yml - and add the required configs.

You can also add a template for how the PR should look in a markdown or .md file, in a pr_template.md file as well as a similar template to report issues.

The difference between issues and PRs

An issue is a discussion topic that does not change the code base.

A pull request triggers the peer-review process, where other developers review the PR making suggestions to change and sanitise the code base making it cleaner, more efficient and maintainable.

The config.yml file

GHA requires a config.yml to connect local configurations to the GHA cloud.

What is YAML?

Yml, or YAML (an acronym for Y Aint Markup Language), is a human-friendly data serialisation language that is language agnostic. It’s a strict superset of JavaScript Object Notation or JSON, with completely different syntax.

YAML is lighter and more flexible than JSON and is considered great for config files. JSON is more inflexible and therefore is considered better for data interchanges.

Fields in the config.yml file

The config.yml file has the following fields

-name - Name for this config - eg: PR Checks

• on - Where the GitHub action takes place as in the example in the code below.

on:
  pull_request:
    branches:
    - name of branch

• jobs - Lists jobs to be run during the process (work flow), in this example, the PR checks

A job is a set of steps in a workflow that is executed on the same runner.

Each step is either a shell script that will be executed, or an action that will be run.

Steps are executed in order and are dependent on each other.

Since each step is executed on the same runner, you can share data from one step to another.

For example, you can have a step that builds your application followed by a step that tests the application that was built. In the example below are a jobs config

jobs:
test:
name:  job name (eg: Check formatting with Prettier)
runs-on: system (eg: ubuntu-ltest)

<!-- steps: (list of steps, uses, with and run commands) -->

steps: - name: Checkout
uses: actions/checkout@v3 - uses: actions/setup-node@v2
with:
node-version: "16" - name: name of commands that will run (eg: Ensure Prettier Formatting Passes)

<!-- run: these are the commands that will run the code checks -->

run: |
npm ci
npm run prettier-check

How to protect your main or master branch with GHA

You can configure a GHA workflow to be triggered when an event occurs in your repository, such as a PR being opened or an issue being created.

Workflows in Github refer to the process of software development and maintaining control over versions over several iterations and changes to the code base.

A workflow configures an automated process that will run one or more jobs.

To maintain this control over version control in Github, you can take actions to protect your key branches. The main branch - formerly known as the master branch, is usually is the production ready-branch.

Additionally each branch you create can be sanitised with GHA, leading to cleaner and more efficient merges of branches into the main branch from development, integration or test environments.

These steps allow for continuous integration, of the app into the production branch and continuous delivery. CI-CD, as it is referred to, keeps the main branch ready for release on a continuous basis as well as continuous deployment. New features/ bug-fixes can be released into production and making these features available to customers as soon as they are tested and production-ready reducing time-to-market.

Workflows are defined by a .yml file and will run automatically, or they can be triggered manually, or at a defined schedule.

The most important branch to protect is the main branch.

• No direct changes can be made to main (best practice)
• Branches must be made from main (the first branch therefore production ready)
• Only named people can merge a branch into main (improve security)
• This can be done by clicking the protect-this-branch on your repository in GitHub and checking the boxes that you would like depending on what rules you want to set to protect the branch

How to protect sub-branches with GHA

Each branch or sub-branch (from an integration or development branch head) also needs to be protected so that code is sanitised before it reaches the main branch and merged into master.

Some best practices:

• Commit history - clean messages and description of reason for change
• PR required before branch can be merged - to discuss and make changes
• Tests written must pass in the PR environment
• A minimum number of people required to review code before merging
• Named people review code
• Security and best practice - the person who writes the code, changes the code and merges the code into master
• Stale branches - changes already made on master pulled into branch and updated before merging
• Conflicts - all merge conflicts to be cleared before merging
• A PR format
• An issues format

I hope this will help you set up GHA in a project without feeling too intimidated to experiment!

Photo Credit: Photo by Campaign Creators on Unsplash