Self-Hosted Runners in GitHub Actions, Customizing Your CI/CD Environment

Table of Contents

Introduction

GitHub Actions provides powerful automation capabilities for your software development workflows. While GitHub-hosted runners are sufficient for most cases, there are scenarios where you might need more control over the environment in which your jobs run. This is where self-hosted runners come into play.

In this article, we’ll explore:

• The differences between GitHub-hosted and self-hosted runners.
• The benefits and considerations of using self-hosted runners.
• How to set up a self-hosted runner.
• Configuring workflows to use self-hosted runners.
• Security best practices.

1. Understanding GitHub Runners

What is a Runner?

A runner is an application that listens for available jobs, runs them, and reports the results back to GitHub. It can be hosted by GitHub or self-hosted by you.

• GitHub-Hosted Runners: Managed by GitHub. They come pre-configured with commonly used software, tools, and packages.
• Self-Hosted Runners: Managed by you. You have full control over the hardware, operating system, and software.

2. Why Use Self-Hosted Runners?

While GitHub-hosted runners are suitable for most workflows, there are scenarios where self-hosted runners provide advantages.

2.1 Hardware Customization

• GitHub-Hosted Runners:

  • Limited to specific hardware configurations.
  • Examples:
    • 2-core CPU
    • 7 GB RAM
    • 14 GB SSD

• Self-Hosted Runners:

  • Customize hardware according to your needs.
  • Benefits:
    • Allocate more CPU cores for resource-intensive tasks.
    • Increase RAM for memory-heavy operations.
    • Expand storage for large datasets.

2.2 Operating System Choices

• GitHub-Hosted Runners:

  • Limited to Ubuntu Linux, macOS, and Windows Server.

• Self-Hosted Runners:

  • Use any operating system supported by the runner application.
  • Examples:
    • Specific Linux distributions (e.g., CentOS, Red Hat Enterprise Linux).
    • Different versions of Windows.
    • Custom or legacy operating systems.

2.3 Custom Software and Tools

• GitHub-Hosted Runners:

  • Pre-installed with a wide range of software.
  • Limited to what GitHub provides.

• Self-Hosted Runners:

  • Install any software, SDKs, or tools you need.
  • Benefits:
    • Use proprietary or licensed software.
    • Maintain specific versions of tools.
    • Avoid setup steps in workflows.

2.4 Persistent Environment

• GitHub-Hosted Runners:

  • Ephemeral environments. Each job runs on a fresh VM.
  • Ensures clean state but may increase setup time.

• Self-Hosted Runners:

  • Persistent environment across jobs.
  • Benefits:
    • Cache dependencies locally to speed up builds.
    • Retain artifacts between jobs.
  • Considerations:
    • Potential for state leakage between jobs.
    • Requires careful management to avoid side effects.

3. Setting Up a Self-Hosted Runner

3.1 Prerequisites

• A Machine to Host the Runner:

  • Physical or virtual machine.
  • Any hardware that meets your performance needs.

• Operating System:

  • Supported OS for the runner application.
  • Check GitHub’s documentation for supported systems.

• Network Requirements:

  • Outbound connectivity to github.com.
  • No inbound ports required.

3.2 Configuring the Runner

Step 1: Access Repository Settings

• Navigate to your GitHub repository.
• Click on Settings.
• In the sidebar, select Actions > Runners.

Step 2: Add a New Self-Hosted Runner

• Click New self-hosted runner.
• Choose your operating system (e.g., Linux).
• Follow the provided instructions.

Step 3: Install the Runner Application

SSH into your machine and execute the commands provided by GitHub:

# Download the latest runner package
$ curl -o actions-runner-linux-x64-2.296.1.tar.gz -L https://github.com/actions/runner/releases/download/v2.296.1/actions-runner-linux-x64-2.296.1.tar.gz

# Extract the installer
$ tar xzf ./actions-runner-linux-x64-2.296.1.tar.gz

# Configure the runner
$ ./config.sh --url https://github.com/your-username/your-repo --token YOUR_RUNNER_TOKEN

Replace https://github.com/your-username/your-repo with your repository URL. Replace YOUR_RUNNER_TOKEN with the token provided.

Step 4: Start the Runner

• Option 1: Run Interactively

$ ./run.sh

• Option 2: Run as a Service

# Install the service
$ sudo ./svc.sh install

# Start the service
$ sudo ./svc.sh start

4. Using Self-Hosted Runners in Workflows

To assign jobs to your self-hosted runner, update the runs-on field in your workflow YAML file.

Basic Example

jobs:
  build:
    runs-on: self-hosted
    steps:
      - uses: actions/checkout@v3
      - name: Build Project
        run: make build

Using Labels

If you have multiple self-hosted runners with different capabilities, you can assign labels during configuration and target them in your workflows.

Assigning Labels During Configuration

When configuring your runner, you’ll be prompted to enter labels:

Enter any additional labels (ex: label-1,label-2):

# For example, enter:
custom-runner,high-memory

Using Labels in Workflow

jobs:
  build:
    runs-on: [self-hosted, custom-runner, high-memory]
    steps:
      - uses: actions/checkout@v3
      - name: Build Project
        run: make build

5. Security Considerations

Using self-hosted runners introduces security risks that you need to manage.

Key Points

• Use with Private Repositories: Avoid using self-hosted runners with public repositories.
• Access Control: Ensure only trusted collaborators can trigger workflows.
• Runner Security:
  • Regularly update the runner application.
  • Keep the operating system and software up to date.
• Isolation:
  • Consider using virtual machines or containers to isolate runners.
  • Avoid running other services on the runner machine.
• Prevent Unauthorized Access:
  • Secure SSH access.
  • Use firewalls and security groups.

Read more: Refer to GitHub’s Security hardening for GitHub Actions for detailed guidelines.

6. Conclusion

Self-hosted runners offer flexibility and control over your CI/CD environment in GitHub Actions. By customizing hardware, operating systems, and software, you can tailor the execution environment to meet your specific needs.

Benefits

• Customization: Full control over the runner environment.
• Performance: Allocate resources as needed.
• Flexibility: Use specific OS versions and software.

Considerations

• Maintenance: You’re responsible for updates and security.
• Security Risks: Must implement best practices to protect your environment.

By understanding how to set up and use self-hosted runners securely, you can enhance your workflows and better meet the demands of your projects.