Streamlining Development Workflows with GitHub Actions and Self-Hosted Runners

Introduction:

GitHub Actions is a powerful automation platform provided by GitHub that allows developers to build, test, and deploy their code directly from repositories. It provides a wide range of pre-built actions and workflows, making it easier to automate various tasks in your software development process. In this blog, we will explore GitHub Actions and walk you through the process of setting up a self-hosted runner, enabling you to customize your workflow environment to meet specific needs.

What are GitHub Actions?

GitHub Actions is a flexible and customizable workflow automation platform built into GitHub. It enables you to automate various tasks, such as building, testing, and deploying your applications, directly from your repositories. With GitHub Actions, you can define workflows as code, triggering them based on specific events or schedules. This allows for seamless integration with your existing development process.

To get a full picture of what Github Actions is, it helps to break it down into its several components:

→ Events
An event is anything that can happen on a Github repository. This goes from pushing a code, creating a branch, opening a pull request, and even commenting on an issue.
The list of triggers is much longer: you can check it out here.

→ Workflows
A workflow is an automated process composed of a series of jobs that gets executed when it’s triggered by an event.
Workflows are defined in YAML files and are stored in a .github/workflows directory at the root of the repository. A repository can also have multiple workflows.

→ Jobs
A job is a series of tasks that gets executed in a workflow upon being triggered by an event. Each step is either a script or a Github action.
A workflow can have multiple jobs that run in parallel.

→ Runners
Runners are processes on a server that run the workflow when it’s triggered. Each runner is responsible for executing a given job.
Runners are hosted in the cloud but they can also be self-hosted in custom cloud environments.

→ Actions
Actions are individual tasks: they are called inside a job. Actions are used to perform complex tasks that you may call multiple times and import into your workflows. Some examples of actions are: publishing a Python package to PyPi, sending a notification email, setting Python to a specific version before running a script, etc.

Why use Self-Hosted Runners?

While GitHub provides virtual environments for executing workflows, there may be cases where you need more control over the execution environment. Self-hosted runners allow you to run workflows on your own infrastructure, enabling customization and integration with internal systems. This is particularly useful for projects with specific dependencies, security requirements, or resource constraints.

Setting up a Self-Hosted Runner:

Let's walk through the process of setting up a self-hosted runner for your GitHub Actions workflows.

Step 1: Prepare the Environment:

1. Set up a machine or virtual machine that meets the system requirements for your project.

2. Install the required dependencies for your project, such as programming languages, build tools, and libraries.

Step 2: Create a Personal Access Token:

To authenticate the self-hosted runner with your GitHub repository, you need to generate a personal access token. Here's how:

1. Go to your GitHub account settings and navigate to "Developer settings" -> "Personal access tokens."

2. Click on "Generate new token" and provide a meaningful description.

3. Select the necessary scopes or permissions based on your project requirements.

4. Click on "Generate token" and make a note of the generated token. **Note: Treat this token as a secret and keep it secure.**

Step 3: Configure the Self-Hosted Runner:

1. Download the self-hosted runner package suitable for your operating system from the GitHub repository's "Settings" -> "Actions" -> "Runners" section.

2. Extract the package on your machine and navigate to the extracted directory.

3. Run the following command to configure the self-hosted runner:

After this selection, you will get shown a detailed set of instructions / commands, you will need to run on your designated runner VM or host. What’s not explicitly named is, that you must not be root to configure the runner. I recommend you to create specific “runner” user.

```

useradd -s /bin/bash -m -d /home/runner -G sudo runner

su - runner

A the time of writing, for a Linux runner, the set of commands is the following:

# Download

# Create a folder

$ mkdir actions-runner && cd actions-runner

# Download the latest runner package

$ curl -o actions-runner-linux-x64-2.290.1.tar.gz -L https://github.com/actions/runner/releases/download/v2.290.1/actions-runner-linux-x64-2.290.1.tar.gz

# Optional: Validate the hash

$ echo "2b97bd3f4639a5df6223d7ce728a611a4cbddea9622c1837967c83c86ebb2baa  actions-runner-linux-x64-2.290.1.tar.gz" | shasum -a 256 -c

# Extract the installer

$ tar xzf ./actions-runner-linux-x64-2.290.1.tar.gz

# Configuration

# Create the runner and start the configuration experience

$ ./config.sh --url https://github.com/thedatabaseme/somerepo --token XXXXXXXXXXXXXXXXXXXXXXXXXXXXX

./config.sh --url https://github.com/your-username/your-repo --token <your-personal-access-token>

```

Replace `https://github.com/your-username/your-repo` with the URL of your repository and `<your-personal-access-token>` with the personal access token generated in the previous step.

4. Follow the prompts to provide additional configuration details, such as the runner name and labels. Labels can be useful for categorizing runners based on their capabilities or usage.

Step 4: Start the Self-Hosted Runner:

Once the runner is configured, start it by running the following command:

```

./run.sh

During the configuration step, you will get asked some questions (e.g. how the runner should be named).

--------------------------------------------------------------------------------

|        ____ _ _   _   _       _          _        _   _                      |

|       / ___(_) |_| | | |_   _| |__      / \   ___| |_(_) ___  _ __  ___      |

|      | |  _| | __| |_| | | | | '_ \    / _ \ / __| __| |/ _ \| '_ \/ __|     |

|      | |_| | | |_|  _  | |_| | |_) |  / ___ \ (__| |_| | (_) | | | \__ \     |

|       \____|_|\__|_| |_|\__,_|_.__/  /_/   \_\___|\__|_|\___/|_| |_|___/     |

|                                                                              |

|                       Self-hosted runner registration                        |

|                                                                              |

--------------------------------------------------------------------------------

# Authentication

√ Connected to GitHub

# Runner Registration

Enter the name of the runner group to add this runner to: [press Enter for Default]

Enter the name of runner: [press Enter for ubuntu2004]

This runner will have the following labels: 'self-hosted', 'Linux', 'X64'

Enter any additional labels (ex. label-1,label-2): [press Enter to skip] 

√ Runner successfully added

√ Runner connection is good

# Runner settings

Enter name of work folder: [press Enter for _work]

√ Settings Saved.

```

Your self-hosted runner is now active and ready to execute workflows.

Example: Running a Workflow with Self-Hosted Runner:

Let's consider an example where we want to build and deploy a Node.js application using a self-hosted runner. Here's a simple workflow YAML file:

```

name: Node.js CI

on:

  push:

    branches:

      - main

jobs:

  build:

    runs-on: self-hosted

    steps:

      - name: Checkout code

        uses: actions/checkout@v2

      - name: Setup Node.js

        uses: actions/setup-node@v2

        with:

          node-version: '14'

      - name: Install dependencies

        run: npm install

      - name: Run tests

        run: npm test

      - name: Deploy

        run: npm run deploy

```

In this workflow, the `runs-on` field is set to `self-hosted`, indicating that the job will run on a self-hosted runner. The remaining steps involve typical tasks such as checking out the code, setting up Node.js, installing dependencies, running tests, and deploying the application.

Conclusion:

GitHub Actions provides a powerful automation platform for streamlining your development workflows. By setting up a self-hosted runner, you can tailor the workflow environment to your specific needs, enabling greater customization and integration with internal systems. Follow the steps outlined in this blog to configure and utilize a self-hosted runner in your GitHub Actions workflows, enhancing the efficiency and flexibility of your software development process.