monolithprojects.github_actions_runner

GitHub Actions Runner

This tool helps you install, uninstall, or update the GitHub Actions Runner on Linux and macOS systems. It works for different types of runners: Enterprise, Organization, and Repository.

How to Install

You need to add this to your requirements.yml file:

roles:
  - name: monolithprojects.github_actions_runner
    version: 1.21.1
    src: https://github.com/MonolithProjects/ansible-github_actions_runner

Requirements

Your system needs to reach the GitHub API.
You require a Personal Access Token to connect to GitHub. Set this token as an environment variable called PERSONAL_ACCESS_TOKEN.

Note
The token must have specific permissions based on what you're trying to do. You can create a Personal Access Token here.

Warning
Do not store your token in a public GitHub repository. Use GitHub Secrets or another secrets management tool.

You need to have a runner user already set up. For this, use monolithprojects.user_management.
If you're using CentOS, make sure to enable the EPEL repository. You can use robertdebock.epel for this.

Supported CPU Architectures

ARM, ARM64 (Note: This role doesn't cover dependency installation for these architectures)
AMD64, x86_64

Supported Operating Systems

Red Hat Enterprise Linux 7
CentOS 7
Rocky Linux 8+
Fedora 29+
Debian 9+
Ubuntu 16.04+
macOS High Sierra +

Weekly Tested On:

Debian 11
Fedora 39
Rocky Linux 9
Ubuntu 20, 22

Variables You Can Set

Below are some key variables you can customize for your setup:

runner_user: "{{ lookup('env', 'USER') }}"  # User running the local runner
runner_dir: /opt/actions-runner               # Directory for the runner
runner_version: "latest"                      # Version of the Runner
runner_state: "started"                       # State of the runner service (e.g., started, stopped, absent)
reinstall_runner: false                       # Reinstall if already exists
hide_sensitive_logs: true                     # Hide sensitive logs
github_url: "https://github.com"             # GitHub URL
github_api_url: "https://api.github.com"     # GitHub API URL
access_token: "{{ lookup('env', 'PERSONAL_ACCESS_TOKEN') }}"  # Personal access token
runner_org: false                             # Is this for an organization?
runner_labels: []                             # Custom labels for the runner

Example Playbooks

Install Runner for a Repository

- name: Install GitHub Actions Runner
  hosts: all
  user: ansible
  become: yes
  vars:
    - github_account: github-access-user
    - github_repo: my_awesome_repo
  roles:
    - role: monolithprojects.github_actions_runner

Install Runner for an Organization

- name: Install GitHub Actions Runner
  hosts: all
  user: ansible
  become: yes
  vars:
    - github_account: my_awesome_org
    - runner_org: yes
  roles:
    - role: monolithprojects.github_actions_runner

Uninstall the Runner

- name: Uninstall GitHub Actions Runner
  hosts: all
  become: yes
  vars:
    - github_account: github-access-user
    - github_repo: my_awesome_repo
    - runner_state: "absent"
  roles:
    - role: monolithprojects.github_actions_runner

Testing with Molecule

Molecule is a testing framework to validate your Ansible roles.

Prerequisites

Python
Docker
Ansible
Molecule

Installation Steps

Make sure Python, Docker, and Ansible are installed.
Install Molecule and its Docker driver:

pip install molecule[docker]

Running Tests

Go to the role's directory:

cd path/to/monolithprojects.github_actions_runner

Set your environment variables:

export PERSONAL_ACCESS_TOKEN=your_github_pat # Your GitHub Personal Access Token
export GITHUB_ACCOUNT=your_account # Your GitHub Account
export GITHUB_REPO=your_repository # GitHub Repo for the Runner