actions · Copilot · Aug 14, 2025 · Aug 14, 2025 · Aug 14, 2025 · Aug 14, 2025
@@ -12,28 +12,33 @@ 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. 
+- 📚 **[Complete Documentation Index](docs/README.md)** - Comprehensive guide to all documentation
+- 📖 **[Contributing Guide](docs/contribute.md)** - Development setup, building, and testing
+- 🔧 **[Automation Scripts](docs/automate.md)** - Automate runner setup and configuration  
+- 🛠️ **[Troubleshooting Guides](docs/checks/README.md)** - Common issues and solutions
+- 🏗️ **[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).
@@ -0,0 +1,61 @@
+# GitHub Actions Runner Documentation
+
+Welcome to the GitHub Actions Runner documentation. This guide will help you get started with self-hosted runners, contribute to the project, and troubleshoot common issues.
+
+## 🚀 Getting Started
+
+### Installation and Setup
+- **[Linux Prerequisites](start/envlinux.md)** - Complete setup guide for Linux systems
+- **[Windows Prerequisites](start/envwin.md)** - Complete setup guide for Windows systems  
+- **[macOS Prerequisites](start/envosx.md)** - Complete setup guide for macOS systems
+
+### Quick Start
+1. Download the [latest runner release](https://github.com/actions/runner/releases)
+2. Follow the platform-specific prerequisites guide above
+3. Configure your runner with `./config.sh` (Linux/macOS) or `.\config.cmd` (Windows)
+4. Start the runner with `./run.sh` (Linux/macOS) or `.\run.cmd` (Windows)
+
+## 🔧 Administration and Automation
+
+- **[Automation Scripts](automate.md)** - Automate runner deployment and management
+- **[Troubleshooting Guides](checks/)** - Common issues and solutions
+
+## 🏗️ Development and Contributing
+
+- **[Contributing Guide](contribute.md)** - Development setup, building, and testing
+- **[Architecture Decision Records](adrs/README.md)** - Important architectural decisions and design patterns
+
+## 📋 Reference Materials
+
+### System Checks and Troubleshooting
+- **[Network Connectivity](checks/network.md)** - Troubleshoot network issues
+- **[Git Configuration](checks/git.md)** - Git-related problems
+- **[Actions Troubleshooting](checks/actions.md)** - Action-specific issues
+- **[SSL Certificate Issues](checks/sslcert.md)** - Certificate and TLS problems
+- **[Node.js Issues](checks/nodejs.md)** - Node.js runtime problems
+- **[Internet Connectivity](checks/internet.md)** - General connectivity issues
+
+### Development Resources
+- **[Visual Studio Code Setup](contribute/vscode.md)** - IDE configuration for development
+- **[Design Documentation](design/)** - Technical design documents
+
+## 🆘 Getting Help
+
+### Community Support
+- **[GitHub Community Discussions](https://github.com/orgs/community/discussions/categories/actions)** - Ask questions and get help from the community
+- **[GitHub Support](https://support.github.com/contact/bug-report)** - Report critical bugs or get professional support
+
+### Reporting Issues
+- **Bug Reports**: Open an issue in this repository
+- **Feature Requests**: Use [GitHub Community Discussions](https://github.com/orgs/community/discussions/categories/actions-and-packages)
+- **Security Issues**: Follow our [security policy](../security.md)
+
+## 📖 Additional Resources
+
+- **[GitHub Actions Documentation](https://docs.github.com/en/actions)** - Official GitHub Actions documentation
+- **[Self-hosted Runners Guide](https://docs.github.com/en/actions/hosting-your-own-runners)** - GitHub's official self-hosted runner documentation
+- **[Runner Releases](https://github.com/actions/runner/releases)** - Download the latest runner versions
+
+---
+
+> **Note**: This documentation is maintained by the GitHub Actions team and the community. If you find any issues or have suggestions for improvement, please open an issue or contribute a pull request.
@@ -76,3 +76,76 @@ Repo level one-liner.  NOTE: replace with yourorg/yourrepo (repo level) or just
 ```bash
 curl -s https://raw.githubusercontent.com/actions/runner/main/scripts/delete.sh | bash -s yourorg/yourrepo runnername
 ```
+
+## Troubleshooting
+
+### Common Issues
+
+#### Permission Denied
+```bash
+# Ensure scripts have execute permissions
+chmod +x ./config.sh ./run.sh
+```
+
+#### PAT Token Issues
+```bash
+# Verify your PAT has the correct scopes:
+# - repo (for repository-level runners)
+# - admin:org (for organization-level runners)
+export RUNNER_CFG_PAT=your_token_here
+echo $RUNNER_CFG_PAT  # Verify it's set
+```
+
+#### Network Connectivity
+```bash
+# Test GitHub connectivity
+curl -H "Authorization: token $RUNNER_CFG_PAT" https://api.github.com/user
+
+# For GitHub Enterprise Server
+curl -H "Authorization: token $RUNNER_CFG_PAT" https://your-github-enterprise/api/v3/user
+```
+
+#### Service Installation Fails
+```bash
+# Check if running as appropriate user
+whoami
+
+# For Linux - ensure systemd is available
+systemctl --version
+
+# For macOS - ensure launchd is available
+launchctl version
+```
+
+#### Runner Registration Fails
+```bash
+# Check if runner already exists
+curl -H "Authorization: token $RUNNER_CFG_PAT" \
+  "https://api.github.com/repos/OWNER/REPO/actions/runners"
+
+# Remove existing runner if needed
+./config.sh remove --token $RUNNER_CFG_PAT
+```
+
+### Getting Help
+
+- **Configuration Issues**: Check the [Prerequisites](start/envlinux.md) for your platform
+- **Network Problems**: Review [network troubleshooting guide](checks/network.md)
+- **General Support**: Visit [GitHub Community Discussions](https://github.com/orgs/community/discussions/categories/actions)
+
+### Advanced Examples
+
+#### Organization-level Runner with Custom Labels
+```bash
+export RUNNER_CFG_PAT=your_org_pat
+curl -s https://raw.githubusercontent.com/actions/runner/main/scripts/create-latest-svc.sh | \
+  bash -s -- -s myorg -n prod-runner-1 -l production,linux,docker
+```
+
+#### Repository-level Runner for GitHub Enterprise
+```bash
+export RUNNER_CFG_PAT=your_ghe_pat
+curl -s https://raw.githubusercontent.com/actions/runner/main/scripts/create-latest-svc.sh | \
+  bash -s -- -s myorg/myrepo -g github.company.com -n build-server -u builder
+```
+```
@@ -0,0 +1,66 @@
+# Troubleshooting Guides
+
+This directory contains troubleshooting guides for common issues you might encounter when setting up or running GitHub Actions self-hosted runners.
+
+## Quick Reference
+
+| Issue Type | Guide | Description |
+|------------|-------|-------------|
+| 🌐 **Network** | [network.md](network.md) | Connection issues, proxy, firewall problems |
+| 🔒 **SSL/TLS** | [sslcert.md](sslcert.md) | Certificate and TLS handshake issues |
+| 📦 **Git** | [git.md](git.md) | Git configuration and repository access |
+| ⚡ **Actions** | [actions.md](actions.md) | Action-specific runtime issues |
+| 🟢 **Node.js** | [nodejs.md](nodejs.md) | Node.js runtime and npm issues |
+| 🌍 **Internet** | [internet.md](internet.md) | General internet connectivity |
+
+## Common First Steps
+
+Before diving into specific guides, try these general troubleshooting steps:
+
+### 1. Check Basic Connectivity
+```bash
+# Test GitHub API access
+curl -I https://api.github.com/
+
+# For GitHub Enterprise Server
+curl -I https://your-github-enterprise.com/api/v3/
+```
+
+### 2. Verify Runner Status
+```bash
+# Check if runner service is running
+./svc.sh status
+
+# View recent logs
+tail -f _diag/Runner_*.log
+```
+
+### 3. Test Runner Configuration
+```bash
+# Re-run configuration
+./config.sh
+
+# Test connection without running
+./run.sh --check
+```
+
+## Getting Additional Help
+
+If these guides don't resolve your issue:
+
+1. **Search existing issues** in the [runner repository](https://github.com/actions/runner/issues)
+2. **Check GitHub Status** at [githubstatus.com](https://githubstatus.com)
+3. **Ask the community** in [GitHub Community Discussions](https://github.com/orgs/community/discussions/categories/actions)
+4. **Contact support** for critical issues via [GitHub Support](https://support.github.com/contact)
+
+## Contributing
+
+Found a solution to a common problem not covered here? Consider contributing:
+
+1. Create a new `.md` file for the issue type
+2. Follow the format of existing guides
+3. Submit a pull request with your improvements
+
+---
+
+💡 **Tip**: Always check the `_diag/` directory for detailed log files when troubleshooting issues.
@@ -1,5 +1,24 @@
 # Contributions
 
+## Table of Contents
+
+- [Getting Started](#getting-started)
+- [Issues](#issues)
+- [Enhancements and Feature Requests](#enhancements-and-feature-requests)
+- [Required Dev Dependencies](#required-dev-dependencies)
+- [Quickstart: Run a Job from a Real Repository](#quickstart-run-a-job-from-a-real-repository)
+- [Development Life Cycle](#development-life-cycle)
+  - [Clone Repository](#clone-repository)
+  - [Build Layout](#build-layout)
+  - [Test Layout](#test-layout)
+  - [Configure Runner](#configure-runner)
+  - [Run Runner](#run-runner)
+  - [View Logs](#view-logs)
+- [Editors](#editors)
+- [Styling](#styling)
+
+## Getting Started
+
 We welcome contributions in the form of issues and pull requests. We view the contributions and the process as the same for github and external contributors. Please note the runner typically requires changes across the entire system and we aim for issues in the runner to be entirely self contained and fixable here. Therefore, we will primarily handle bug issues opened in this repo and we kindly request you to create all feature and enhancement requests on the [GitHub Feedback](https://github.com/community/community/discussions/categories/actions-and-packages) page. 
 
 > IMPORTANT: Building your own runner is critical for the dev inner loop process when contributing changes.  However, only runners built and distributed by GitHub (releases) are supported in production.  Be aware that workflows and orchestrations run service side with the runner being a remote process to run steps.  For that reason, the service can pull the runner forward so customizations can be lost.
@@ -124,8 +143,8 @@ cd runner/_layout
 ./config.(sh/cmd) # configure your custom runner
 ```
 
-You will need your the name of your repository and a runner registration token.
-Check [Quickstart](##Quickstart:-Run-a-job-from-a-real-repository) if you don't know how to get this token.
+You will need the name of your repository and a runner registration token.
+Check the [Quickstart section](#quickstart-run-a-job-from-a-real-repository) if you don't know how to get this token.
 
 These can also be passed down as arguments to `config.(sh/cmd)`:
 ```bash