📃 Role overview

github_runner_setup

Description: Sets up a self-hosted GitHub Actions runner on a Linux machine.

Field	Value
Readme update	2026/05/13

Vars

These are variables with higher priority

File: vars/main.yml

Var	Type	Value
gh_runner_version	str	2.334.0
runner_directory	str	/home/{{ ansible_user }}/.actions-runner
runner_download_url	str	https://github.com/actions/runner/releases/download/v{{ gh_runner_version }}/actions-runner-linux-x64-{{ gh_runner_version }}.tar.gz
scopes	list	[]
scopes.0	str	repository
scopes.1	str	organization
gh_runner_arch	str	x64
gh_scope	str	repository
gh_api	str	https://api.github.com
gh_api_token	str
repo_name	str
gh_owner	str
gh_org	str
runner_labels	str	self-hosted,linux
runner_name	str	{{ ansible_hostname }}-gha-runner

Tasks

File: tasks/create-registration-token.yml

Name	Module	Has Conditions
Check runner scope	ansible.builtin.assert	False
Set runner scope registration URL	ansible.builtin.set_fact	False
Create GitHub Actions runner registration token	ansible.builtin.uri	True

File: tasks/download-github-runner-package.yml

Name	Module	Has Conditions
Download github runner package	ansible.builtin.get_url	True
Ensure destination directory exists	ansible.builtin.file	False
Extract github runner package	ansible.builtin.unarchive	False

File: tasks/install-dependencies.yml

Name	Module	Has Conditions
Install the dependencies for the github runner	ansible.builtin.command	False

File: tasks/install-service.yml

Name	Module	Has Conditions
Install and start github runner as a systemd service	block	False
Install and start github runner as a systemd service	ansible.builtin.command	False

File: tasks/main.yml

Name	Module	Has Conditions
Create registration token	ansible.builtin.include_tasks	False
Download github runner package	ansible.builtin.include_tasks	False
Register the github runner and start the service	ansible.builtin.include_tasks	False

File: tasks/register-github-runner.yml

Name	Module	Has Conditions
Validate and check github runner and start service	block	False
Check if GitHub Actions runner is already configured	ansible.builtin.stat	False
Register the github runner	ansible.builtin.command	True
Install and start github runner as a systemd service	block	False
Install the service after a successful registration on the first attempt	ansible.builtin.include_tasks	True

Playbook

# SPDX-License-Identifier: GPL-3.0
- hosts: allgather_facts: trueroles:
- github_runner_setup

Author Information

opscontainer

License

GPL-3.0

Minimum Ansible Version

2.20.0

Platforms

• AlmaLinux: ['all']
• Ubuntu: ['all']
• Debian: ['all']

Dependencies

No dependencies specified.

TODO's

• Pre-commit configuration
• Github Workflows
• SBOM
• Security scanning

Contributing

See the CONTRIB.md guide for contribution instructions.