@htekdev/actions-debugger 1.0.22 → 1.0.24

package/errors/runner-environment/node20-removed-toolcache-default-node22.yml

@@ -0,0 +1,104 @@
+id: runner-environment-062
+title: "Node.js 20 Removed from Toolcache — Default Node.js Changed to 22"
+category: runner-environment
+severity: error
+tags:
+  - nodejs
+  - node20
+  - node22
+  - toolcache
+  - eol
+  - setup-node
+  - runner-images
+patterns:
+  - regex: "node: not found"
+    flags: "i"
+  - regex: "node: No such file or directory"
+    flags: "i"
+  - regex: "Downloading Node\\.js (20\\.[0-9]+\\.[0-9]+)"
+    flags: "i"
+  - regex: "engines.*node.*>=\\s*20"
+    flags: "i"
+  - regex: "error node_modules.*requires node.*20"
+    flags: "i"
+error_messages:
+  - "node: not found"
+  - "Downloading Node.js 20.x.x (not pre-installed, downloading on demand)"
+  - "error: The engine 'node' is incompatible with this module. Expected version '^20.0.0'. Got '22.x.x'"
+  - "The engine 'node' is incompatible with this module. Expected version '>=20 <21'. Got '22.14.0'"
+root_cause: |
+  Node.js 20 reached end-of-life on April 30, 2026. Starting with runner image
+  updates rolled out May 19–26, 2026, Node.js 20 was removed from the toolcache
+  on ALL GitHub-hosted runner images (ubuntu-22.04, ubuntu-24.04, ubuntu-26.04,
+  macos-14, macos-15, macos-26, windows-2022, windows-2025, and ARM variants).
+
+  Two distinct impacts:
+
+  1. **Default Node.js version changed**: On runners where Node.js 20 was
+     previously the default (e.g., ubuntu-22.04, ubuntu-24.04, windows-2022,
+     macos-14), the default is now Node.js 22 (Maintenance LTS). Workflows
+     that call `node` or `npm` without an explicit `actions/setup-node` step
+     will now run on Node.js 22, potentially breaking packages with strict
+     engines constraints like `"node": "^20.0.0"`.
+
+  2. **setup-node now downloads Node.js 20**: If a workflow pins
+     `node-version: '20'` via `actions/setup-node`, it will no longer find
+     Node.js 20 in the toolcache and must download it on demand. This adds
+     download time and may fail if the registry is rate-limited or the runner
+     has no internet access (self-hosted runners with air-gapped environments).
+
+  Only Node.js 22 and Node.js 24 remain pre-installed in the toolcache on all
+  runner images after this change.
+fix: |
+  Option 1 — Upgrade to Node.js 22 or 24 (recommended):
+    Update your project to support Node.js 22 (current Maintenance LTS) or
+    Node.js 24 (Active LTS). Update package.json engines field, run tests on
+    the new version, and remove the explicit node-version pin (or update it).
+
+  Option 2 — Pin to Node.js 20 via setup-node (temporary):
+    If you cannot migrate yet, explicitly install Node.js 20 on every job
+    using `actions/setup-node`. Node.js 20 is still downloadable on demand —
+    it just won't be pre-cached. This will slow down your workflow.
+
+  Option 3 — Test with FORCE_JAVASCRIPT_ACTIONS_TO_NODE24:
+    Set `FORCE_JAVASCRIPT_ACTIONS_TO_NODE24: true` as a workflow env to test
+    how your action runtime behaves on Node.js 24 before fully migrating.
+fix_code:
+  - language: yaml
+    label: "Upgrade to Node.js 22 (recommended)"
+    code: |
+      - name: Set up Node.js
+        uses: actions/setup-node@v4
+        with:
+          node-version: '22'    # Node.js 22 is Maintenance LTS through 2026
+          cache: 'npm'
+  - language: yaml
+    label: "Pin Node.js 20 temporarily (still downloadable on demand)"
+    code: |
+      - name: Set up Node.js 20 (no longer pre-cached — will download)
+        uses: actions/setup-node@v4
+        with:
+          node-version: '20'    # EOL 2026-04-30; plan your migration to v22
+          cache: 'npm'
+  - language: yaml
+    label: "Use .nvmrc / .node-version to pin version in project root"
+    code: |
+      - name: Set up Node.js from .nvmrc
+        uses: actions/setup-node@v4
+        with:
+          node-version-file: '.nvmrc'    # Update .nvmrc to 22 or 24
+          cache: 'npm'
+prevention:
+  - "Always specify an explicit node-version in actions/setup-node — never rely on the runner's ambient Node.js version."
+  - "Set `node-version-file: '.nvmrc'` and commit a .nvmrc file so all environments (local, CI, containers) use the same version."
+  - "Watch the runner-images Announcements tab for future EOL removals — set up GitHub notifications for the actions/runner-images repo."
+  - "Use `engines` in package.json with a range like `>=22 <25` to catch version incompatibilities in CI early."
+docs:
+  - url: "https://github.com/actions/runner-images/issues/14029"
+    label: "runner-images #14029: Node.js 20 removed, default changed to 22"
+  - url: "https://github.blog/changelog/2025-09-19-deprecation-of-node-20-on-github-actions-runners/"
+    label: "GitHub Changelog: Deprecation of Node 20 on GitHub Actions runners"
+  - url: "https://github.com/nodejs/release#readme"
+    label: "Node.js Release Schedule (EOL dates)"
+  - url: "https://docs.github.com/en/actions/writing-workflows/choosing-what-your-workflow-does/using-pre-installed-software#nodejs-versions"
+    label: "GitHub Docs: Using pre-installed software — Node.js versions"

package/errors/runner-environment/org-runner-group-dispatch-null.yml

@@ -0,0 +1,102 @@
+id: runner-environment-059
+title: "Org-Level Self-Hosted Runner in Group Never Dispatched — Job Queued Indefinitely"
+category: runner-environment
+severity: error
+tags:
+  - self-hosted-runner
+  - runner-group
+  - org-runner
+  - queued
+  - dispatch
+
+patterns:
+  - regex: "no runner.*matching.*label.*self-hosted"
+    flags: "i"
+  - regex: "runner_group_id.*null"
+    flags: "i"
+
+error_messages:
+  - "Can't find any online and idle self-hosted runner in the current repository, account/organization that matches the required labels: 'self-hosted, <group-name>'"
+  - "Waiting for a runner to pick up this job..."
+
+root_cause: |
+  When a self-hosted runner is registered at the ORGANIZATION level and placed into
+  a runner group that has explicit repository access, the GitHub Actions dispatcher
+  sometimes fails to resolve the runner's group membership within the target
+  repository's scope. The job's metadata shows runner_group_id: null throughout the
+  entire wait period, meaning the internal broker never matched the org-level runner
+  to the queued job.
+
+  This affects runners using the V2 broker protocol
+  (broker.actions.githubusercontent.com) on GitHub Team and Enterprise plans.
+  The runner appears "Online" in the org settings, the runner group lists the target
+  repository as allowed, and the runs-on labels match — yet the job never starts.
+
+  Root technical cause: the dispatcher resolves runner group membership differently
+  for org-scoped runners vs. repo-scoped runners. When the runner is registered at
+  org scope, the broker does not propagate its group_id to the queued job record,
+  so no assignment occurs.
+
+fix: |
+  Short-term workaround (immediate):
+    Re-register the runner at the REPOSITORY level instead of the organization level.
+    This bypasses the group dispatch path and the job is assigned immediately.
+
+  Long-term fix:
+    1. Monitor GitHub Actions runner releases for a fix to org-level group dispatch.
+    2. Use GitHub-hosted larger runners or runner scale sets (Actions Runner Controller)
+       for org-level sharing — these use a different dispatch mechanism that is not
+       affected by this bug.
+    3. If org-level management is required, use runner groups with repo-scoped runner
+       registration and rely on group access policies to control visibility.
+
+fix_code:
+  - language: yaml
+    label: "Re-register runner at repository level (workaround)"
+    code: |
+      # 1. Remove the runner from the org-level runner list in GitHub UI:
+      #    Settings → Actions → Runners → (select runner) → Remove runner
+      #
+      # 2. Re-register the runner at the REPO level:
+      #    <repo> → Settings → Actions → Runners → New self-hosted runner
+      #    Follow setup commands shown in the UI.
+      #
+      # 3. Your workflow runs-on stays the same:
+      jobs:
+        build:
+          runs-on: [self-hosted, my-runner-label]
+          steps:
+            - uses: actions/checkout@v4
+
+  - language: yaml
+    label: "Use Actions Runner Controller (ARC) for org-level runners"
+    code: |
+      # ARC scale sets are not affected by the org-runner group dispatch bug.
+      # Install the controller chart and create a runner scale set:
+      #
+      # helm install arc-runner-set \
+      #   --namespace arc-runners \
+      #   oci://ghcr.io/actions/actions-runner-controller-charts/gha-runner-scale-set \
+      #   --set githubConfigUrl=https://github.com/<org> \
+      #   --set githubConfigSecret.github_token=<token>
+      #
+      # Then reference in your workflow:
+      jobs:
+        build:
+          runs-on: arc-runner-set
+          steps:
+            - uses: actions/checkout@v4
+
+prevention:
+  - "Register self-hosted runners at repository level when possible to avoid org-level dispatch issues."
+  - "After registering a runner, trigger a test workflow immediately to confirm dispatch before relying on it in production."
+  - "Use Actions Runner Controller (ARC) scale sets for org-wide shared runners — ARC bypasses the runner group dispatch path."
+  - "Check runner_group_id via the API (`GET /repos/{owner}/{repo}/actions/runs/{run_id}/jobs`) when a job is stuck — null means dispatch failed at the broker level."
+
+docs:
+  - url: "https://github.com/actions/runner/issues/4429"
+    label: "actions/runner#4429 — Org-level runner never dispatched despite correct group access (May 2026)"
+  - url: "https://docs.github.com/en/actions/using-github-hosted-runners/using-github-hosted-runners/about-github-hosted-runners"
+    label: "GitHub Docs — Runner registration scopes"
+  - url: "https://docs.github.com/en/actions/hosting-your-own-runners/managing-self-hosted-runners/using-self-hosted-runners-in-a-workflow"
+    label: "GitHub Docs — Using self-hosted runners in a workflow"

package/errors/runner-environment/powershell-74-76-threadjob-module-rename.yml

@@ -0,0 +1,124 @@
+id: runner-environment-063
+title: "PowerShell 7.4 → 7.6 LTS Upgrade Breaks ThreadJob Module Name and .NET Runtime"
+category: runner-environment
+severity: warning
+tags:
+  - powershell
+  - powershell-76
+  - threadjob
+  - dotnet10
+  - runner-images
+  - breaking-change
+  - module
+patterns:
+  - regex: "The term 'ThreadJob\\\\Start-ThreadJob' is not recognized"
+    flags: "i"
+  - regex: "CommandNotFoundException.*ThreadJob"
+    flags: "i"
+  - regex: "Cannot find module.*ThreadJob"
+    flags: "i"
+  - regex: "Join-Path.*cannot process argument transformation on parameter 'ChildPath'"
+    flags: "i"
+  - regex: "PowerShell.*7\\.4.*not found"
+    flags: "i"
+error_messages:
+  - "The term 'ThreadJob\\Start-ThreadJob' is not recognized as a name of a cmdlet, function, script file, or executable program."
+  - "Cannot find module ThreadJob"
+  - "Join-Path: Cannot process argument transformation on parameter 'ChildPath'."
+  - "Get-Module: The specified module 'ThreadJob' was not found"
+root_cause: |
+  GitHub Actions runner images are being updated from PowerShell 7.4.x to 7.6.x
+  (the latest LTS release, based on .NET 10) across all runner images between
+  June 8–15, 2026 (runner-images#14150). PowerShell 7.6 is a major.minor
+  version upgrade from 7.4 and contains several breaking changes:
+
+  1. **ThreadJob module renamed**: The `ThreadJob` module has been replaced by
+     `Microsoft.PowerShell.ThreadJob`. The `Start-ThreadJob` cmdlet itself is
+     unchanged, but any script using the module-qualified name
+     `ThreadJob\Start-ThreadJob` will throw a CommandNotFoundException because
+     the old module name no longer exists. Scripts that call `Start-ThreadJob`
+     without the module prefix continue to work.
+
+  2. **Join-Path -ChildPath is now string[]**: The `-ChildPath` parameter type
+     changed from `string` to `string[]`. In most cases this is backward-
+     compatible, but scripts with unusual argument binding patterns or that
+     pass a typed `[string]` variable explicitly may encounter parameter
+     transformation errors.
+
+  3. **.NET 10 runtime**: PowerShell 7.6 ships on .NET 10 (7.4 was on .NET 8).
+     Scripts that load .NET assemblies, use P/Invoke, or invoke .NET API
+     members that changed between .NET 8 and .NET 10 may break silently
+     or throw runtime exceptions.
+
+  4. **WildcardPattern.Escape behavior change**: `WildcardPattern.Escape` now
+     correctly escapes lone backticks. Scripts that relied on the old (incorrect)
+     no-escape behavior may produce different wildcard pattern results.
+
+  5. **Trailing space removed from event source name**: Scripts that match
+     exact event source names (e.g., for Windows Event Log) may fail to find
+     the source if they include a trailing space.
+fix: |
+  1. Replace module-qualified ThreadJob references:
+     Find all occurrences of `ThreadJob\Start-ThreadJob` in your scripts and
+     update them to `Microsoft.PowerShell.ThreadJob\Start-ThreadJob` or simply
+     use the unqualified `Start-ThreadJob`.
+
+  2. Review Join-Path usage:
+     Scripts using `Join-Path` with `-ChildPath` should continue to work in
+     most cases. If you see parameter binding errors, check that you are not
+     passing a typed `[string]` variable in a context that is now ambiguous.
+
+  3. Test .NET assembly loading:
+     If your scripts load .NET assemblies via `Add-Type -Path` or
+     `[System.Reflection.Assembly]::LoadFrom()`, test them against .NET 10
+     to catch any API compatibility issues before the upgrade rolls out.
+
+  4. Pin PowerShell version (temporary workaround):
+     Until migration is complete, you can install a specific PowerShell version
+     via the MSI/package manager in a workflow step. This is a temporary
+     workaround and should not be the long-term solution.
+fix_code:
+  - language: yaml
+    label: "Fix module-qualified ThreadJob reference"
+    code: |
+      # Before (PowerShell 7.4 — breaks on 7.6):
+      # $job = ThreadJob\Start-ThreadJob -ScriptBlock { ... }
+      #
+      # After (works on both 7.4 and 7.6):
+      - name: Run threaded job
+        shell: pwsh
+        run: |
+          # Option A: unqualified (works on all versions)
+          $job = Start-ThreadJob -ScriptBlock { Get-Process }
+          
+          # Option B: fully qualified with new module name (7.6+)
+          $job = Microsoft.PowerShell.ThreadJob\Start-ThreadJob -ScriptBlock { Get-Process }
+          
+          $result = $job | Wait-Job | Receive-Job
+          Write-Output $result
+  - language: yaml
+    label: "Verify PowerShell version in workflow to detect future upgrades early"
+    code: |
+      - name: Check PowerShell version
+        shell: pwsh
+        run: |
+          $version = $PSVersionTable.PSVersion
+          Write-Output "PowerShell version: $version"
+          if ($version.Major -lt 7 -or ($version.Major -eq 7 -and $version.Minor -lt 6)) {
+            Write-Warning "PowerShell < 7.6 detected — ensure ThreadJob references use unqualified names"
+          }
+prevention:
+  - "Use unqualified cmdlet names (Start-ThreadJob, not ThreadJob\\Start-ThreadJob) to avoid module-name dependencies."
+  - "Add a PowerShell version check step at the start of complex pwsh workflows to detect unexpected upgrades early."
+  - "Test workflows against the next PowerShell LTS version in a matrix before the runner image upgrade lands."
+  - "Subscribe to GitHub notifications on actions/runner-images to receive Announcement issues for upcoming breaking changes."
+  - "Avoid loading .NET assemblies by absolute path in runner workflows — prefer NuGet package installation to ensure .NET runtime compatibility."
+docs:
+  - url: "https://github.com/actions/runner-images/issues/14150"
+    label: "runner-images #14150: PowerShell will be updated from 7.4 to 7.6 LTS (Jun 8-15 2026)"
+  - url: "https://learn.microsoft.com/en-us/powershell/scripting/whats-new/what-s-new-in-powershell-76"
+    label: "PowerShell 7.6 Release Notes — breaking changes"
+  - url: "https://github.com/PowerShell/PowerShell/releases/tag/v7.6.0"
+    label: "PowerShell v7.6.0 GitHub release"
+  - url: "https://learn.microsoft.com/en-us/powershell/scripting/install/powershell-support-lifecycle"
+    label: "PowerShell support lifecycle"

package/errors/runner-environment/self-hosted-runner-not-found.yml

@@ -0,0 +1,134 @@
+id: runner-environment-067
+title: "Self-Hosted Runner 'An error occurred: Runner not found'"
+category: runner-environment
+severity: error
+tags:
+  - self-hosted
+  - runner
+  - runner-not-found
+  - jit
+  - registration
+  - ephemeral
+patterns:
+  - regex: "An error occurred: Runner not found"
+    flags: "i"
+  - regex: "Runner not found"
+    flags: "i"
+  - regex: "No runner matching the specified criteria was found"
+    flags: "i"
+  - regex: "Could not find any runner that matches the selector"
+    flags: "i"
+error_messages:
+  - "An error occurred: Runner not found"
+  - "Error: An error occurred: Runner not found"
+  - "No runner matching the specified criteria was found"
+root_cause: |
+  "An error occurred: Runner not found" is a vague error emitted by the
+  GitHub Actions broker when it cannot match or allocate a self-hosted runner
+  for a queued job. It has multiple distinct root causes:
+
+  1. **JIT (Just-in-Time) token expiry** (most common with ARC/Kubernetes runners):
+     Ephemeral runners provisioned via Just-in-Time tokens have a short registration
+     window. If the runner process does not connect within the token validity period
+     (~60 seconds), the broker discards the registration and emits "Runner not found"
+     when the job is dispatched. This particularly affects actions-runner-controller
+     (ARC) on Kubernetes when pod startup time exceeds the JIT window.
+
+  2. **Runner de-registered before job starts**:
+     Autoscaling controllers (ARC, custom scripts) that aggressively recycle idle
+     runners may de-register the runner in the brief window between job queue and
+     job dispatch. The broker finds no runner for the job's labels.
+
+  3. **Label mismatch**:
+     The workflow specifies `runs-on: [self-hosted, linux, x64]` but the registered
+     runner has different labels (e.g., just `[self-hosted, linux]`). The broker
+     treats this as "no matching runner found" and emits the same vague error.
+
+  4. **Runner registered at wrong scope**:
+     A runner registered at the organization level is not visible to a repository
+     not in that runner's group, or vice versa. Org runner group access policy
+     may restrict which repos can use the runner.
+
+  5. **Concurrent job stealing**:
+     In autoscaling pools where multiple runners share the same label set, a
+     job token issued to one runner is occasionally "stolen" by another — the
+     original runner's job token is invalid when it tries to start. Less common
+     but documented in high-concurrency pools (actions/runner#3857, 116 reactions).
+
+  The error is intentionally vague because it covers multiple broker-side failures
+  that are indistinguishable from the runner's perspective.
+fix: |
+  Diagnose by checking the runner registration logs first:
+
+  1. **For JIT token expiry (ARC/Kubernetes)**:
+     Reduce pod startup time — use pre-pulled images, smaller base images, or
+     warm pools. Alternatively, switch to Long-Running runners (PAT/App-registered)
+     which don't have JIT token windows. Check actions-runner-controller v0.9+
+     which extended the JIT window.
+
+  2. **For de-registered runner race condition**:
+     Add a grace period to your autoscaler before de-registering idle runners —
+     at least 60 seconds after a job completes. Use `--once` flag on ephemeral
+     runners so they only exit after completing one job, not before.
+
+  3. **For label mismatch**:
+     Run `gh api repos/{owner}/{repo}/actions/runners --jq '.[].labels'` to inspect
+     registered runner labels. Compare against the `runs-on:` in your workflow.
+     Labels are case-sensitive and must be an exact subset match.
+
+  4. **For wrong scope (org vs repo)**:
+     Check Settings → Actions → Runners in both the repo and org. Confirm the
+     runner appears under the correct scope and the runner group allows access
+     to the repository.
+
+  5. **General debugging**:
+     Enable runner diagnostic logs by setting `ACTIONS_RUNNER_DEBUG: true` and
+     `ACTIONS_STEP_DEBUG: true` as repository secrets. This enables verbose
+     broker negotiation logs in the Actions runner output.
+fix_code:
+  - language: yaml
+    label: "Enable runner diagnostic logs to capture broker negotiation details"
+    code: |
+      # Add these as repository secrets (Settings → Secrets → Actions):
+      # ACTIONS_RUNNER_DEBUG = true
+      # ACTIONS_STEP_DEBUG = true
+
+      # Then re-run the failing job. The runner logs will include:
+      # "Checking runner for labels: [self-hosted, linux, x64]"
+      # "Connected to GitHub Actions service"
+      # "Received job assignment: ..."
+      jobs:
+        build:
+          runs-on: [self-hosted, linux, x64]
+          steps:
+            - uses: actions/checkout@v4
+            - run: echo "Runner labels verified"
+  - language: yaml
+    label: "Verify registered runner labels via GitHub API"
+    code: |
+      # Check what labels your self-hosted runners actually have:
+      # gh api repos/{owner}/{repo}/actions/runners --jq '.runners[] | {name: .name, labels: [.labels[].name]}'
+      # Example output:
+      # {"name": "my-runner", "labels": ["self-hosted", "Linux", "X64"]}
+      # Note: Labels are case-sensitive — "Linux" != "linux"
+
+      # Workflow label must match runner label exactly:
+      jobs:
+        build:
+          # Use exact case matching the runner's registered labels:
+          runs-on: [self-hosted, Linux, X64]
+prevention:
+  - "Use explicit, versioned runner labels instead of generic `self-hosted` to make label mismatches immediately visible in the runner registration."
+  - "For ephemeral/JIT runners on Kubernetes, use pre-pulled base images and resource requests that ensure fast pod startup to avoid JIT token expiry."
+  - "Add ACTIONS_RUNNER_DEBUG=true as a repository secret during initial setup to capture detailed registration logs before the runner goes into production."
+  - "Implement health monitoring on your self-hosted runner pool — alert when the runner count drops below the minimum needed for your queue depth."
+  - "Prefer Long-Running runners over JIT ephemeral runners for workflows with unpredictable startup patterns — JIT token windows are unforgiving on slow infrastructure."
+docs:
+  - url: "https://github.com/actions/runner/issues/3857"
+    label: "actions/runner #3857: 'An error occurred: Runner not found' (116 reactions)"
+  - url: "https://docs.github.com/en/actions/hosting-your-own-runners/managing-self-hosted-runners/monitoring-and-troubleshooting-self-hosted-runners"
+    label: "GitHub Docs: Monitoring and troubleshooting self-hosted runners"
+  - url: "https://docs.github.com/en/actions/hosting-your-own-runners/managing-self-hosted-runners/using-labels-with-self-hosted-runners"
+    label: "GitHub Docs: Using labels with self-hosted runners"
+  - url: "https://docs.github.com/en/actions/security-for-github-actions/security-guides/security-hardening-for-github-actions#hardening-for-self-hosted-runners"
+    label: "GitHub Docs: Security hardening for self-hosted runners"

package/errors/runner-environment/self-hosted-runner-selinux-service-exec-failure.yml

@@ -0,0 +1,116 @@
+id: runner-environment-068
+title: "Self-Hosted Runner Service Fails on RHEL/CentOS — SELinux Blocks runsvc.sh with status=203/EXEC"
+category: runner-environment
+severity: error
+tags:
+  - self-hosted
+  - selinux
+  - rhel
+  - centos
+  - oracle-linux
+  - service
+  - systemd
+patterns:
+  - regex: "status=203/EXEC|code=exited.*status=203"
+    flags: "i"
+  - regex: "runsvc\\.sh.*failed|svc\\.sh.*start.*fail|runner.*service.*203"
+    flags: "i"
+  - regex: "avc.*denied.*runner|selinux.*denied.*exec.*runsvc"
+    flags: "i"
+error_messages:
+  - "Active: failed (Result: exit-code)"
+  - "Main PID: XXXX (code=exited, status=203/EXEC)"
+  - "Failed to execute: Permission denied"
+  - "svc install succeeded but svc start exits immediately with status=203/EXEC"
+root_cause: |
+  On SELinux-enforcing Linux distributions (RHEL, CentOS, Oracle Linux, AlmaLinux,
+  Rocky Linux), the GitHub Actions self-hosted runner service fails to start with
+  systemd exit code 203/EXEC when run via sudo ./svc.sh start.
+
+  The root cause is a SELinux security context mismatch:
+  1. GitHub's ./config.sh creates runsvc.sh and run.sh with the security context
+     of the installing user's SSH/interactive session (e.g., unconfined_u:object_r:user_home_t:s0).
+  2. When systemd launches the service, it executes the script in a more restricted
+     domain context. SELinux enforces that service scripts must have a context
+     allowing execution from the systemd context.
+  3. The user_home_t label applied during installation does not permit execution by
+     systemd, so the exec() syscall is denied before the process can start.
+  4. Running ./run.sh directly in an interactive shell works because interactive
+     shells run in a more permissive SELinux context that allows user_home_t exec.
+
+  Exit code 203/EXEC specifically means systemd failed during exec() — not during
+  runtime — confirming SELinux is the blocker rather than a configuration or
+  dependency issue.
+fix: |
+  Apply the correct SELinux security context to the runner service scripts using
+  the chcon command. The usr_t type permits execution by systemd service contexts.
+
+  Step 1 — Fix runsvc.sh context (required):
+    cd /path/to/runner
+    sudo chcon system_u:object_r:usr_t:s0 runsvc.sh
+
+  Step 2 — Fix run.sh context (required if service starts but crashes immediately):
+    sudo chcon system_u:object_r:usr_t:s0 run.sh
+
+  Step 3 — Start the service:
+    sudo ./svc.sh start
+    sudo ./svc.sh status   # Should show: Active: active (running)
+
+  For persistent context that survives runner upgrades and ./config.sh reinstalls,
+  use semanage fcontext to write the context rule permanently. This requires the
+  policycoreutils-python-utils package.
+fix_code:
+  - language: yaml
+    label: "Fix SELinux context — run these commands on the host (not in workflow)"
+    code: |
+      # Navigate to the runner installation directory
+      cd /home/github-runner/actions-runner
+
+      # Step 1: Fix runsvc.sh SELinux context (required)
+      sudo chcon system_u:object_r:usr_t:s0 runsvc.sh
+
+      # Step 2: Fix run.sh as well (needed if service crashes immediately after start)
+      sudo chcon system_u:object_r:usr_t:s0 run.sh
+
+      # Step 3: Start the runner service
+      sudo ./svc.sh start
+
+      # Step 4: Verify the service is running
+      sudo ./svc.sh status
+      # Expected output: Active: active (running)
+
+  - language: yaml
+    label: "Persistent SELinux context via semanage (survives reinstalls)"
+    code: |
+      # Install policycoreutils-python-utils if semanage is not available
+      # sudo dnf install policycoreutils-python-utils
+
+      RUNNER_DIR="/home/github-runner/actions-runner"
+
+      # Add permanent file context rules
+      sudo semanage fcontext -a -t usr_t "${RUNNER_DIR}/runsvc.sh"
+      sudo semanage fcontext -a -t usr_t "${RUNNER_DIR}/run.sh"
+
+      # Apply rules to existing files
+      sudo restorecon -v "${RUNNER_DIR}/runsvc.sh"
+      sudo restorecon -v "${RUNNER_DIR}/run.sh"
+
+      # Verify contexts are set correctly
+      ls -lZ "${RUNNER_DIR}/runsvc.sh" "${RUNNER_DIR}/run.sh"
+      # Expected: system_u:object_r:usr_t:s0
+
+      # Start the runner service
+      sudo ./svc.sh start
+prevention:
+  - "After ./config.sh on SELinux-enforcing systems, always run chcon on runsvc.sh before ./svc.sh start."
+  - "Use semanage fcontext for persistent context that survives runner upgrades and reinstalls."
+  - "Add chcon steps to your runner provisioning runbooks and Ansible/Terraform automation."
+  - "Verify SELinux denials with: sudo ausearch -m avc -ts recent | grep runner"
+  - "Consider using the RHEL runner container image which handles SELinux context automatically."
+docs:
+  - url: "https://stackoverflow.com/questions/71818706/github-self-hosted-runner-fails-to-run-as-a-service-on-rh-linux"
+    label: "Stack Overflow: Self-hosted runner fails as service on RH Linux (17-vote answer)"
+  - url: "https://docs.github.com/en/actions/hosting-your-own-runners/managing-self-hosted-runners/configuring-the-self-hosted-runner-application-as-a-service"
+    label: "GitHub Docs: Configuring the self-hosted runner as a service"
+  - url: "https://docs.redhat.com/en/documentation/red_hat_enterprise_linux/8/html/using_selinux/changing-selinux-contexts_using-selinux"
+    label: "Red Hat Docs: Changing SELinux file contexts with chcon"