GitHub Actions is a powerful automation tool for CI/CD workflows. While GitHub-hosted runners offer convenience, they have limitations. This is where self-hosted runners come into play. By setting up a self-hosted runner, you gain complete control, customization, and cost efficiency in your CI/CD pipelines.
In this guide, we will explore what self-hosted runners are, why they are beneficial, and how to set them up for GitHub Actions.
What is a Self-Hosted Runner?
A self-hosted runner is a machine that you manage and configure to execute GitHub Actions workflows. Unlike GitHub-hosted runners, which are provisioned on demand by GitHub, self-hosted runners allow complete control over the environment, dependencies, and hardware. These runners can be virtual machines (VMs), physical servers, or even personal computers.
By using self-hosted runners, organizations can optimize workflows for specific use cases and reduce dependency on cloud-hosted environments.
Why Choose a Self-Hosted Runner?
1. Tailored Environment
With self-hosted runners, you can pre-install all necessary dependencies, custom tools, and configurations. This eliminates the repeated downloading of packages during each workflow, significantly cutting down execution time.
2. Cost Savings
Running CI/CD pipelines on cloud-hosted services can become expensive, especially for resource-intensive builds. Self-hosted runners help reduce costs by utilizing your existing infrastructure efficiently.
3. Improved Security
Keeping sensitive credentials, proprietary code, and confidential data within a private network strengthens security. Self-hosted runners ensure better control over access and compliance with internal security policies.
If these benefits align with your needs, setting up a self-hosted runner is a great option. Let’s go through the process step by step.
Setting Up a Self-Hosted Runner for GitHub Actions
1. Preparing Your Machine
Before adding a self-hosted runner, ensure the machine meets GitHub’s minimum requirements. It can be a Linux, Windows, or macOS system. Update the OS and install necessary dependencies based on the workflow’s needs.
2. Adding the Runner to GitHub
To register the runner with GitHub:
- Go to Settings in your repository.
- Navigate to Actions > Runners.
- Click Add Runner, select the OS, and copy the provided script.
- Run the script on your machine to register the runner.
3. Configuring the Runner
Execute the script, follow the instructions, and authenticate using the token provided by GitHub. Once configured, a runsvc.sh file will be created.
For Linux users, ensure the script has the correct SELinux context for execution:
chcon -t bin_t /home/your-user/actions-runner/svc.sh
If access issues occur due to SELinux policies, temporarily set SELinux to permissive mode for debugging:
setenforce 0
Note: Setenforce 0 should only be used for debugging. Once the issue is identified, apply proper SELinux policies:
semanage fcontext -a -t bin_t "/home/your-user/actions-runner(/.*)?"
restorecon -R /home/your-user/actions-runner
4. Updating Your Workflow
Modify your GitHub Actions workflow file (.github/workflows/your-workflow.yml) to use the self-hosted runner:
jobs:
build:
runs-on: self-hosted
steps:
- name: Checkout code
uses: actions/checkout@v3
- name: Run a script
run: echo "Hello from self-hosted runner!"
After committing these changes, trigger the workflow to verify that it runs successfully on the self-hosted runner.
Best Practices for Managing Self-Hosted Runners
To keep self-hosted runners efficient and secure, follow these best practices:
- Keep Runners Updated: Regularly update the runner to ensure compatibility with new GitHub Actions features.
- Use Labels for Organization: Assign labels to runners based on their role (e.g.,
build-runner,test-runner). This helps in routing jobs to the right machine. - Monitor System Resources: Track CPU, memory, and disk usage to avoid performance bottlenecks.
- Automate Cleanup: Periodically remove temporary files and old build artifacts to free up storage.
- Secure Access: Limit runner access, use strong authentication tokens, and restrict network exposure.
Conclusion
Setting up self-hosted runners for GitHub Actions provides enhanced control, efficiency, and security. By following this guide, you can configure a self-hosted runner and integrate it into your CI/CD pipelines.
