Improve README and OS prerequisites documentation

Co-authored-by: salmanmkc <32169182+salmanmkc@users.noreply.github.com>
2025-12-15 22:47:01 +00:00 · 2025-08-14 10:30:04 +00:00
parent f11013518c
commit 691793a922
4 changed files with 307 additions and 25 deletions
--- a/README.md
+++ b/README.md
@@ -12,28 +12,31 @@ The runner is the application that runs a job from a GitHub Actions workflow. It

 For more information about installing and using self-hosted runners, see [Adding self-hosted runners](https://help.github.com/en/actions/automating-your-workflow-with-github-actions/adding-self-hosted-runners) and [Using self-hosted runners in a workflow](https://help.github.com/en/actions/automating-your-workflow-with-github-actions/using-self-hosted-runners-in-a-workflow)

-Runner releases:
+## Download and Install

-![win](docs/res/win_sm.png) [Pre-reqs](docs/start/envwin.md) | [Download](https://github.com/actions/runner/releases)  
+![win](docs/res/win_sm.png) **Windows**: [Prerequisites](docs/start/envwin.md) | [Download](https://github.com/actions/runner/releases)  

-![macOS](docs/res/apple_sm.png)  [Pre-reqs](docs/start/envosx.md) | [Download](https://github.com/actions/runner/releases)  
+![macOS](docs/res/apple_sm.png) **macOS**: [Prerequisites](docs/start/envosx.md) | [Download](https://github.com/actions/runner/releases)  

-![linux](docs/res/linux_sm.png)  [Pre-reqs](docs/start/envlinux.md) | [Download](https://github.com/actions/runner/releases)
+![linux](docs/res/linux_sm.png) **Linux**: [Prerequisites](docs/start/envlinux.md) | [Download](https://github.com/actions/runner/releases)

-### Note
+## Documentation and Resources

-Thank you for your interest in this GitHub repo, however, right now we are not taking contributions. 
+- 📖 **[Contributing Guide](docs/contribute.md)** - Development setup, building, and testing
+- 🔧 **[Automation Scripts](docs/automate.md)** - Automate runner setup and configuration  
+- 🏗️ **[Architecture Decision Records](docs/adrs/README.md)** - Important architectural decisions
+- ⚙️ **Platform Prerequisites:** [Linux](docs/start/envlinux.md) | [Windows](docs/start/envwin.md) | [macOS](docs/start/envosx.md)

-We continue to focus our resources on strategic areas that help our customers be successful while making developers' lives easier. While GitHub Actions remains a key part of this vision, we are allocating resources towards other areas of Actions and are not taking contributions to this repository at this time. The GitHub public roadmap is the best place to follow along for any updates on features we’re working on and what stage they’re in.
+## Support and Community

-We are taking the following steps to better direct requests related to GitHub Actions, including:
+Thank you for your interest in this repository. Please note our current contribution and support guidelines:

-1. We will be directing questions and support requests to our [Community Discussions area](https://github.com/orgs/community/discussions/categories/actions)
+**Bug Reports:** You are welcome to report bugs in this repository through Issues.

-2. High Priority bugs can be reported through Community Discussions or you can report these to our support team https://support.github.com/contact/bug-report.
+**Feature Requests:** Please submit feature and enhancement requests on the [GitHub Community Discussions](https://github.com/orgs/community/discussions/categories/actions) page.

-3. Security Issues should be handled as per our [security.md](security.md)
+**Support Questions:** For help and support, please use our [Community Discussions area](https://github.com/orgs/community/discussions/categories/actions).

-We will still provide security updates for this project and fix major breaking changes during this time.
+**Security Issues:** Please report security vulnerabilities following our [security policy](security.md).

-You are welcome to still raise bugs in this repo.
+**High Priority Issues:** Critical bugs can be reported through Community Discussions or our [support team](https://support.github.com/contact/bug-report).
--- a/docs/start/envlinux.md
+++ b/docs/start/envlinux.md
@@ -6,10 +6,21 @@

 Please see "[Supported architectures and operating systems for self-hosted runners](https://docs.github.com/en/actions/reference/runners/self-hosted-runners#linux)."

-## Install .Net Core 3.x Linux Dependencies
+## Quick Setup
+
+The `./config.sh` script will automatically check and guide you through installing .NET dependencies:
+
+```bash
+./config.sh
+# If dependencies are missing, run:
+./bin/installdependencies.sh
+```
+
+## Install .NET Core Linux Dependencies
+
+The `./config.sh` will check .NET Core dependencies during runner configuration.  
+You might see something like this which indicates a dependency is missing:

-The `./config.sh` will check .Net Core 3.x dependencies during runner configuration.  
-You might see something like this which indicate a dependency's missing.
 ```bash
 ./config.sh
    libunwind.so.8 => not found
@@ -17,34 +28,87 @@ You might see something like this which indicate a dependency's missing.
 Dependencies is missing for Dotnet Core 6.0
 Execute ./bin/installdependencies.sh to install any missing Dotnet Core 6.0 dependencies.
 ```
+
 You can easily correct the problem by executing `./bin/installdependencies.sh`.  
 The `installdependencies.sh` script should install all required dependencies on all supported Linux versions  
-> Note: The `installdependencies.sh` script will try to use the default package management mechanism on your Linux flavor (ex. `yum`/`apt-get`/`apt`).

-### Full dependencies list
+> **Note:** The `installdependencies.sh` script will try to use the default package management mechanism on your Linux flavor (ex. `yum`/`apt-get`/`apt`).

-Debian based OS (Debian, Ubuntu, Linux Mint)
+## Manual Dependency Installation

+If the automatic installation doesn't work, you can manually install dependencies using your package manager:
+
+### Debian based OS (Debian, Ubuntu, Linux Mint)
+
+```bash
+sudo apt-get update
+sudo apt-get install -y liblttng-ust1 libkrb5-3 zlib1g libssl1.1 libicu66
+```
+
+**Required packages:**
 - liblttng-ust1 or liblttng-ust0
 - libkrb5-3
 - zlib1g
 - libssl1.1, libssl1.0.2 or libssl1.0.0
 - libicu63, libicu60, libicu57 or libicu55

-Fedora based OS (Fedora, Red Hat Enterprise Linux, CentOS, Oracle Linux 7)
+### Fedora based OS (Fedora, Red Hat Enterprise Linux, CentOS, Oracle Linux 7)

+```bash
+sudo yum install -y lttng-ust openssl-libs krb5-libs zlib libicu
+# Or for newer systems:
+sudo dnf install -y lttng-ust openssl-libs krb5-libs zlib libicu
+```
+
+**Required packages:**
 - lttng-ust
 - openssl-libs
 - krb5-libs
 - zlib
 - libicu

-SUSE based OS (OpenSUSE, SUSE Enterprise)
+### SUSE based OS (OpenSUSE, SUSE Enterprise)

+```bash
+sudo zypper install -y lttng-ust libopenssl1_1 krb5 zlib libicu60_2
+```
+
+**Required packages:**
 - lttng-ust
 - libopenssl1_1
 - krb5
 - zlib
 - libicu60_2

-## [More .Net Core Prerequisites Information](https://docs.microsoft.com/en-us/dotnet/core/linux-prerequisites?tabs=netcore2x)
+## Troubleshooting
+
+### Common Issues
+
+**Permission denied errors:**
+```bash
+sudo chmod +x ./config.sh ./run.sh
+```
+
+**Missing dependencies after installation:**
+```bash
+# Check what's missing
+ldd ./bin/Runner.Listener
+# Reinstall dependencies
+./bin/installdependencies.sh
+```
+
+**SSL/TLS errors:**
+```bash
+# Update certificates
+sudo apt-get update && sudo apt-get install ca-certificates
+# Or for RHEL/CentOS:
+sudo yum update ca-certificates
+```
+
+### Getting Help
+
+- Check our [troubleshooting guide](../checks/README.md)
+- Search [GitHub Community Discussions](https://github.com/orgs/community/discussions/categories/actions)
+- Review [common network issues](../checks/network.md)
+
+## [More .NET Core Prerequisites Information](https://docs.microsoft.com/en-us/dotnet/core/linux-prerequisites?tabs=netcore2x)
--- a/docs/start/envosx.md
+++ b/docs/start/envosx.md
@@ -1,9 +1,136 @@


-# ![osx](../res/apple_med.png) macOS/OS X System Prerequisites
+# ![osx](../res/apple_med.png) macOS System Prerequisites

 ## Supported Versions

 Please see "[Supported architectures and operating systems for self-hosted runners](https://docs.github.com/en/actions/reference/runners/self-hosted-runners#macos)."

-## [More .Net Core Prerequisites Information](https://docs.microsoft.com/en-us/dotnet/core/macos-prerequisites?tabs=netcore30)
+## Quick Setup
+
+1. **Download** the latest runner from [releases](https://github.com/actions/runner/releases)
+2. **Extract** the downloaded archive: `tar xzf actions-runner-osx-x64-*.tar.gz`
+3. **Run** `./config.sh` to configure the runner
+4. **Install** as a service: `sudo ./svc.sh install` and `sudo ./svc.sh start`
+
+## System Requirements
+
+### macOS Version
+- macOS 10.15 (Catalina) or later
+- Both Intel (x64) and Apple Silicon (ARM64) are supported
+
+### Required Tools
+
+#### Homebrew (Recommended)
+Install Homebrew for easy package management:
+```bash
+/bin/bash -c "$(curl -fsSL https://raw.githubusercontent.com/Homebrew/install/HEAD/install.sh)"
+```
+
+#### Development Tools
+```bash
+# Install Xcode Command Line Tools
+xcode-select --install
+
+# Install essential development tools via Homebrew
+brew install git curl wget
+```
+
+### .NET Runtime
+- .NET 6.0 runtime (automatically included with the runner)
+
+## Setup Steps
+
+### 1. Download and Extract
+```bash
+# Create runner directory
+mkdir ~/actions-runner && cd ~/actions-runner
+
+# Download latest release (replace with actual version)
+curl -O -L https://github.com/actions/runner/releases/download/v2.xyz.z/actions-runner-osx-x64-2.xyz.z.tar.gz
+
+# Extract
+tar xzf ./actions-runner-osx-x64-2.xyz.z.tar.gz
+```
+
+### 2. Configure
+```bash
+./config.sh --url https://github.com/YOUR_ORG/YOUR_REPO --token YOUR_TOKEN
+```
+
+### 3. Run as Service (macOS)
+```bash
+# Install as launchd service
+sudo ./svc.sh install
+
+# Start the service
+sudo ./svc.sh start
+
+# Check status
+sudo ./svc.sh status
+```
+
+### 4. Run Interactively (Alternative)
+```bash
+./run.sh
+```
+
+## macOS-Specific Considerations
+
+### Security & Privacy
+- Allow the runner executable through macOS Gatekeeper
+- Grant necessary permissions in System Preferences > Security & Privacy
+
+### Code Signing
+For repositories that build macOS applications:
+```bash
+# Install certificates for code signing
+security import developer_certificates.p12 -k ~/Library/Keychains/login.keychain
+```
+
+### Xcode Integration
+If building iOS/macOS apps:
+```bash
+# Install Xcode from App Store or developer portal
+# Set Xcode path
+sudo xcode-select -s /Applications/Xcode.app/Contents/Developer
+```
+
+## Troubleshooting
+
+### Common Issues
+
+**Permission Denied:**
+```bash
+chmod +x ./config.sh ./run.sh ./svc.sh
+```
+
+**Gatekeeper Issues:**
+```bash
+# Allow unsigned binary to run
+sudo spctl --master-disable
+# Or specifically allow the runner
+sudo spctl --add ./bin/Runner.Listener
+```
+
+**Service Not Starting:**
+```bash
+# Check system logs
+sudo ./svc.sh status
+tail -f ~/Library/Logs/Runner_*.log
+```
+
+**Path Issues:**
+```bash
+# Ensure proper PATH in your shell profile
+echo 'export PATH="/usr/local/bin:$PATH"' >> ~/.zshrc
+source ~/.zshrc
+```
+
+### Getting Help
+
+- Check our [troubleshooting guide](../checks/README.md)
+- Review [common network issues](../checks/network.md)
+- Search [GitHub Community Discussions](https://github.com/orgs/community/discussions/categories/actions)
+
+## [More .NET Prerequisites Information](https://docs.microsoft.com/en-us/dotnet/core/macos-prerequisites?tabs=netcore30)
--- a/docs/start/envwin.md
+++ b/docs/start/envwin.md
@@ -4,4 +4,92 @@

 Please see "[Supported architectures and operating systems for self-hosted runners](https://docs.github.com/en/actions/reference/runners/self-hosted-runners#windows)."

-## [More .NET Core Prerequisites Information](https://docs.microsoft.com/en-us/dotnet/core/windows-prerequisites?tabs=netcore30)
+## Quick Setup
+
+1. **Download** the latest runner from [releases](https://github.com/actions/runner/releases)
+2. **Extract** the downloaded archive to your desired directory
+3. **Run** `config.cmd` as Administrator to configure the runner
+4. **Install** as a service (optional): `svc.sh install` and `svc.sh start`
+
+## System Requirements
+
+### .NET Runtime
+- .NET 6.0 runtime (automatically installed with the runner)
+- Windows PowerShell 5.1 or PowerShell Core 6.0+
+
+### Windows Features
+Windows runners require the following components:
+
+```powershell
+# Enable required Windows features (run as Administrator)
+Enable-WindowsOptionalFeature -Online -FeatureName Microsoft-Windows-Subsystem-Linux
+```
+
+### Visual Studio Build Tools (For builds requiring compilation)
+For repositories that need to compile code, install:
+
+- **Visual Studio 2017 or newer** [Install here](https://visualstudio.microsoft.com)
+- **Visual Studio 2022 17.3 Preview or later** (for ARM64) [Install here](https://docs.microsoft.com/en-us/visualstudio/releases/2022/release-notes-preview)
+
+### Git for Windows
+- **Git for Windows** [Install here](https://git-scm.com/downloads) (required for repository operations)
+
+## Common Setup Steps
+
+### 1. Create Runner Directory
+```cmd
+mkdir C:\actions-runner
+cd C:\actions-runner
+```
+
+### 2. Download and Extract
+```powershell
+# Download latest release
+Invoke-WebRequest -Uri "https://github.com/actions/runner/releases/download/v2.xyz.z/actions-runner-win-x64-2.xyz.z.zip" -OutFile "actions-runner.zip"
+# Extract
+Expand-Archive -Path "actions-runner.zip" -DestinationPath "."
+```
+
+### 3. Configure
+```cmd
+.\config.cmd --url https://github.com/YOUR_ORG/YOUR_REPO --token YOUR_TOKEN
+```
+
+### 4. Run as Service
+```cmd
+# Install service
+.\svc.sh install
+# Start service  
+.\svc.sh start
+```
+
+## Troubleshooting
+
+### Common Issues
+
+**PowerShell Execution Policy:**
+```powershell
+Set-ExecutionPolicy -ExecutionPolicy RemoteSigned -Scope CurrentUser
+```
+
+**Windows Defender/Antivirus:**
+- Add runner directory to antivirus exclusions
+- Exclude `Runner.Listener.exe` and `Runner.Worker.exe`
+
+**Firewall Issues:**
+```powershell
+# Allow runner through Windows Firewall
+New-NetFirewallRule -DisplayName "GitHub Actions Runner" -Direction Inbound -Protocol TCP -LocalPort 443 -Action Allow
+```
+
+**Permission Issues:**
+- Run `config.cmd` as Administrator
+- Ensure the runner user has "Log on as a service" rights
+
+### Getting Help
+
+- Check our [troubleshooting guide](../checks/README.md)
+- Review [common issues](../checks/actions.md)
+- Search [GitHub Community Discussions](https://github.com/orgs/community/discussions/categories/actions)
+
+## [More .NET Prerequisites Information](https://docs.microsoft.com/en-us/dotnet/core/windows-prerequisites?tabs=netcore30)