vaggeliskls / windows-github-custom-runner

A robust, cost-effective solution to deploy containerized custom GitHub Runners in a Windows OS environment on a Linux server. This project utilizes Vagrant VM, libvirt, and docker-compose, providing a seamless, plug-and-play approach that significantly enhances the CI/CD pipeline experience. No prior knowledge of VM creation required

🏃 Windows Github Custom Runner

Explore an innovative, efficient, and cost-effective approach to deploying a custom GitHub Runner that runs in a containerized Windows OS (x64) environment on a Linux system. This project leverages the robust capabilities of Vagrant VM, libvirt, and docker-compose which allows for seamless management of a Windows instance just like any Docker container. The added value here lies in the creation of a plug-and-play solution, significantly enhancing convenience, optimizing resource allocation, and integrating flawlessly with existing workflows. This strategy enriches CI/CD pipeline experiences in various dev-ops environments, providing a smooth and comprehensive approach that does not require prior knowledge of VM creation.

📋 Prerequisites

• docker version 24 or higher.
• docker-compose version 1.18 or higher.

🚀 Deployment Guide

1. Create/Update the environmental file .env

• PAT: Personal access token from GitHub
• RUNNER_URL: The URL of the GitHub that the runner connects to
• RUNNERS: Number of runners
• MEMORY: Amount of memory for the Vagrant image (in MB)
• CPU: Number of CPUs for the Vagrant image
• DISK_SIZE: Disk size for the Vagrant image (in GB)

# Runner settings
PAT=<Replace with your personal access token>
RUNNER_URL=<runner url>
RUNNERS=1
# Vagrant image settings
MEMORY=8000 # 8GB
CPU=4
DISK_SIZE=100

2. Create docker-compose.yml

version: "3.9"

services:
  win10:
    image: ghcr.io/vaggeliskls/windows-github-custom-runner:latest
    env_file: .env
    stdin_open: true
    tty: true
    privileged: true
    volumes:
      - /sys/fs/cgroup:/sys/fs/cgroup
    ports:
      - 3389:3389

3. Run: docker-compose up -d

The PAT token needs Read and Write access to organization self-hosted runners

🌐 Access via Remote Desktop

For debugging purposes or testing you can always connect to the VM with remote desktop softwares.

Some software that used when developed was

1. Linux: rdesktop rdesktop <ip>:3389 or remina
2. MacOS: Windows remote desktop
3. Windows: buildin Remote Windows Connection

🔑 User Login

The default users based on vagrant image are

1. Administrator
   • Username: Administrator
   • Password: vagrant
2. User
   • Username: vagrant
   • Password: vagrant

📚 Further Reading and Resources

• Windows in docker container
• Windows Vagrant Tutorial
• Vagrant image: peru/windows-server-2022-standard-x64-eval
• Vagrant by HashiCorp
• Windows Virtual Machine in a Linux Docker Container