@htekdev/actions-debugger 1.0.2 → 1.0.4

package/errors/known-unsolved/job-maximum-execution-time.yml

@@ -0,0 +1,127 @@
+id: known-unsolved-009
+title: "Job Killed After Maximum Execution Time (6h Hosted / 35-Day Workflow)"
+category: known-unsolved
+severity: limitation
+tags:
+  - timeout
+  - execution-time
+  - job-limits
+  - platform-limit
+  - self-hosted
+  - workflow-duration
+  - limitation
+patterns:
+  - regex: "The job running has exceeded the maximum execution time"
+    flags: "i"
+  - regex: "exceeded the maximum (?:time|execution time)"
+    flags: "i"
+  - regex: "job .* exceeded .* maximum"
+    flags: "i"
+error_messages:
+  - "The job running on runner GitHub Actions X has exceeded the maximum execution time of 360 minutes."
+  - "The job running has exceeded the maximum execution time"
+root_cause: |
+  GitHub Actions enforces hard platform-level execution time limits that cannot be
+  overridden or extended by workflow configuration. These limits exist to protect
+  shared infrastructure and prevent runaway jobs from consuming unlimited resources.
+
+  **GitHub-hosted runner limits:**
+  - Maximum job execution time: **6 hours** (360 minutes)
+  - Maximum workflow run time: **35 days** (across all jobs, including queued time)
+  - Default `timeout-minutes` when not set: **360 minutes** (6 hours)
+
+  **Self-hosted runner limits:**
+  - Maximum job execution time: **5 days** (7,200 minutes) by default
+  - Maximum workflow run time: **35 days** (same as hosted)
+  - Self-hosted limits can be customized in enterprise plans via org/enterprise policies
+
+  **When limits are hit:**
+  - The runner process is sent a SIGTERM (graceful) then SIGKILL (forced) after a grace period
+  - The job is marked CANCELLED (not FAILED) in the UI
+  - The log message "The job running has exceeded the maximum execution time" appears in
+    the runner log (may be visible in the step logs depending on where the runner was killed)
+  - Any `post:` steps for active actions (e.g., cache save, artifact upload) are skipped
+  - No email notification is sent to the repo owner about the cancellation
+
+  **Why this is a limitation, not just misconfiguration:**
+  - There is no way to set `timeout-minutes` above 21600 (360 hours) to extend the GitHub-hosted 6h cap
+  - The workflow `timeout-minutes` field cannot override the platform cap on GitHub-hosted runners
+  - Jobs requiring more than 6 hours on GitHub-hosted runners have NO supported path without
+    migrating to self-hosted or restructuring the job into multiple shorter sequential jobs
+fix: |
+  There is no way to extend the GitHub-hosted runner 6-hour job cap. Options:
+
+  1. **Break the job into smaller sequential jobs** — split long-running work (e.g., build
+     artifacts first, test in separate parallel jobs, deploy last). Each job has its own
+     6-hour budget.
+
+  2. **Migrate to self-hosted runners** — self-hosted runners support up to 5-day jobs.
+     Use actions-runner-controller (ARC) or cloud auto-scaling for elastic capacity.
+
+  3. **Optimize the slow step** — profile build/test times; parallelize with matrix
+     strategy; use incremental builds or test sharding to reduce per-job duration.
+
+  4. **Use caching aggressively** — `actions/cache` reduces download/build time between
+     runs, but does not extend limits.
+fix_code:
+  - language: yaml
+    label: "Split a long job into sequential jobs to stay within 6h per job"
+    code: |
+      jobs:
+        build:
+          runs-on: ubuntu-latest
+          timeout-minutes: 120  # 2h budget for build
+          outputs:
+            artifact-id: ${{ steps.upload.outputs.artifact-id }}
+          steps:
+            - uses: actions/checkout@v4
+            - name: Build
+              run: make build-release
+            - name: Upload build artifact
+              id: upload
+              uses: actions/upload-artifact@v4
+              with:
+                name: release-build
+                path: dist/
+
+        # Separate job — gets its own 6h budget
+        test:
+          needs: build
+          runs-on: ubuntu-latest
+          timeout-minutes: 180  # 3h budget for tests
+          steps:
+            - uses: actions/download-artifact@v4
+              with:
+                artifact-id: ${{ needs.build.outputs.artifact-id }}
+            - run: make test-full
+  - language: yaml
+    label: "Self-hosted runner for jobs requiring more than 6 hours"
+    code: |
+      jobs:
+        long-running-job:
+          # Self-hosted runners support up to 5-day job duration
+          runs-on: [self-hosted, linux, x64]
+          timeout-minutes: 2880  # 48h — only possible on self-hosted
+          steps:
+            - uses: actions/checkout@v4
+            - name: Long-running process
+              run: ./scripts/full-dataset-processing.sh
+prevention:
+  - "Set explicit `timeout-minutes` on every job — don't rely on the implicit 6h GitHub-hosted cap as your only safeguard."
+  - "Profile job duration regularly and alert when a job's P99 duration approaches 80% of its timeout budget."
+  - "Parallelize test suites using matrix strategy or `actions/github-script` dynamic matrix generation to reduce per-job time."
+  - "Use self-hosted runners for any workflow that legitimately requires more than 2-3 hours per job (e.g., large model training, full database rebuild, exhaustive integration tests)."
+  - "Be aware that post-run actions (cache save, artifact upload) will NOT execute if the parent job is killed for exceeding the time limit."
+docs:
+  - url: "https://docs.github.com/en/actions/administering-github-actions/usage-limits-billing-and-administration#usage-limits"
+    label: "Usage limits: job execution time and workflow run time"
+  - url: "https://docs.github.com/en/actions/hosting-your-own-runners/managing-self-hosted-runners/about-self-hosted-runners#usage-limits"
+    label: "Self-hosted runner usage limits"
+  - url: "https://github.com/orgs/community/discussions/48790"
+    label: "Community: Workflow run time limit 35 days"
+  - url: "https://github.com/orgs/community/discussions/150900"
+    label: "Community: Job cancellation after 6 hours"
+  - url: "https://stackoverflow.com/questions/70187174/github-actions-self-hosted-runner-the-job-running-has-exceeded-the-maximum-exe"
+    label: "Stack Overflow: The job running has exceeded the maximum execution time"
+  - url: "https://github.com/actions/actions-runner-controller"
+    label: "Actions Runner Controller (ARC) — Kubernetes-based self-hosted runner auto-scaling"

package/errors/runner-environment/macos-14-sonoma-eol.yml

@@ -0,0 +1,89 @@
+id: runner-environment-018
+title: "macOS 14 Sonoma Runner Deprecation — EOL November 2026"
+category: runner-environment
+severity: warning
+tags:
+  - macos
+  - deprecation
+  - runner-image
+  - eol
+  - migration
+patterns:
+  - regex: "##\\[error\\]This request was rejected because.*macos-14"
+    flags: "i"
+  - regex: "Image.*macos-14.*deprecated|macos-14.*no longer supported"
+    flags: "i"
+  - regex: "The requested image.*macos-14.*not available"
+    flags: "i"
+error_messages:
+  - "##[error]This request was rejected because the runner label 'macos-14' is no longer supported."
+  - "The macOS 14 image has been retired. Please update to macos-15 or macos-latest."
+root_cause: |
+  GitHub announced the deprecation of `macOS 14 Sonoma` runner images on the following schedule:
+  - **Deprecation begins**: July 6, 2026 — longer queue times during peak hours, brownout periods
+  - **Full retirement**: November 2, 2026 — jobs using `macos-14` will fail permanently
+
+  GitHub maintains only the latest two stable macOS major versions. Since macOS 26 Tahoe is now
+  GA on GitHub Actions, macOS 14 is the oldest and must retire.
+
+  **Brownout schedule** (jobs deliberately failed during these windows to force migration):
+  - October 5, 14:00 UTC – October 6, 00:00 UTC
+  - October 12, 14:00 UTC – October 13, 00:00 UTC
+  - October 16–30, 14:00 UTC – next day 00:00 UTC (escalating weekly)
+
+  Affected labels: `macos-14`, `macos-14-large`, `macos-14-xlarge`.
+fix: |
+  Update your workflow's `runs-on` label to a supported macOS version:
+
+  | Old label | Replace with |
+  |-----------|--------------|
+  | `macos-14` | `macos-latest` or `macos-15` or `macos-26` |
+  | `macos-14-large` | `macos-latest-large` or `macos-15-large` |
+  | `macos-14-xlarge` | `macos-latest-xlarge` or `macos-15-xlarge` or `macos-26-xlarge` |
+
+  If your workflow depends on macOS 14-specific software versions (e.g., Xcode 15, older
+  Python/Ruby), test carefully against macOS 15 before switching `macos-latest`.
+  See runner-environment-017 for macOS 15 → 26 migration notes if moving to `macos-latest`.
+fix_code:
+  - language: yaml
+    label: "Migrate from macos-14 to macos-15 (conservative) or macos-latest"
+    code: |
+      jobs:
+        build:
+          # Before:
+          # runs-on: macos-14
+
+          # Conservative: macos-15 (similar software stack, no OpenSSL jump)
+          runs-on: macos-15
+
+          # OR accept latest (currently macos-26 after June 15 2026):
+          # runs-on: macos-latest
+
+          steps:
+            - uses: actions/checkout@v4
+  - language: yaml
+    label: "Strategy matrix: test across multiple macOS versions during migration"
+    code: |
+      jobs:
+        build:
+          strategy:
+            matrix:
+              os: [macos-15, macos-26]
+          runs-on: ${{ matrix.os }}
+          steps:
+            - uses: actions/checkout@v4
+            - name: Build and test
+              run: make test
+prevention:
+  - "Subscribe to actions/runner-images GitHub Issues announcements label to receive deprecation notices well in advance."
+  - "Avoid pinning to specific macOS point versions (`macos-14`, `macos-15`) in long-lived workflows — use `macos-latest` and test proactively against the next version."
+  - "Run a matrix strategy against `macos-latest` and your pinned version to detect incompatibilities before they cause production failures."
+  - "Search your organization's workflows periodically for deprecated runner labels using: `gh search code 'runs-on: macos-14' --owner YOUR_ORG`."
+docs:
+  - url: "https://github.com/actions/runner-images/issues/13518"
+    label: "GitHub Announcement: macOS 14 Sonoma deprecation timeline"
+  - url: "https://docs.github.com/en/actions/using-github-hosted-runners/using-github-hosted-runners/about-github-hosted-runners#supported-runners-and-hardware-resources"
+    label: "Supported GitHub-hosted runner labels"
+source:
+  article: "https://htek.dev/articles/github-actions-debugging-guide"
+  section: "Runner deprecation and EOL"

package/errors/runner-environment/macos-latest-to-macos-26.yml

@@ -0,0 +1,127 @@
+id: runner-environment-017
+title: "macos-latest Label Now Points to macOS 26 Tahoe"
+category: runner-environment
+severity: error
+tags:
+  - macos
+  - runner-image
+  - breaking-change
+  - openssl
+  - xcode
+  - migration
+patterns:
+  - regex: "Error opening configuration file.*openssl"
+    flags: "i"
+  - regex: "SSL_CTX_new.*failed|SSL_connect.*SYSCALL error"
+    flags: "i"
+  - regex: "Could not find Xcode.*version.*16\\.\\d"
+    flags: "i"
+  - regex: "ruby.*requires.*Ruby (2|3\\.0|3\\.1|3\\.2|3\\.3)"
+    flags: "i"
+  - regex: "dyld.*Library not loaded.*libssl\\.1\\.1"
+    flags: "i"
+error_messages:
+  - "dyld[]: Library not loaded: /usr/local/opt/openssl@1.1/lib/libssl.1.1.dylib"
+  - "Could not find Xcode version '16.4'"
+  - "SSL_connect returned=1 errno=0 state=error: certificate verify failed"
+  - "Your Ruby version is 3.3.x, but your Gemfile specified ~> 3.3"
+  - "npm warn old lockfile"
+root_cause: |
+  The `macos-latest` label in GitHub Actions was migrated to point to macOS 26 Tahoe
+  beginning June 15, 2026 (completing by July 15, 2026). Previously it pointed to macOS 15
+  Sequoia. This migration includes several major software version changes that silently break
+  workflows:
+
+  - **OpenSSL**: 1.1.1w → 3.6.2 — The biggest breaking change. Many C/C++ projects,
+    Ruby gems (openssl), and Python packages that link against the system OpenSSL dynamically
+    will fail at runtime because libssl.1.1.dylib no longer ships with macOS 26.
+  - **Xcode**: Default changes from 16.4 to 26.4.1 (Xcode 26 series). Workflows pinning
+    `xcode-version: '16.4'` or relying on Clang 17 will break — Clang/LLVM jumps from 17 → 21.
+  - **Ruby**: 3.3.x → 3.4.x — Minor version bump can cause Gemfile constraint failures and
+    gem native extension compilation issues.
+  - **Node.js**: Default moves from 22 → 24 (though both images include Node 24 in cached tools).
+  - **npm**: 10.x → 11.x — Major npm version. Package-lock.json format changes possible.
+  - **Homebrew LLVM**: 18 → 20 (major version jump for workflows using `llvm@18` explicitly).
+fix: |
+  **Immediate mitigation:** Pin to `macos-15` to restore previous behavior while you migrate:
+
+  ```yaml
+  runs-on: macos-15
+  ```
+
+  **Proper fix** — address each breaking dependency:
+
+  1. **OpenSSL**: Brew-install a pinned OpenSSL version and set library paths:
+     ```bash
+     brew install openssl@1.1
+     export LDFLAGS="-L$(brew --prefix openssl@1.1)/lib"
+     export CPPFLAGS="-I$(brew --prefix openssl@1.1)/include"
+     ```
+     Or migrate to OpenSSL 3.x compatible code.
+
+  2. **Xcode**: Pin the Xcode version explicitly using `maxim-lobanov/setup-xcode`:
+     ```yaml
+     - uses: maxim-lobanov/setup-xcode@v1
+       with:
+         xcode-version: '16.4'
+     ```
+     Or migrate your project to Xcode 26.
+
+  3. **Ruby**: Update your Gemfile to accept 3.4.x (`~> 3.4`) or use `ruby/setup-ruby` to
+     pin a specific version:
+     ```yaml
+     - uses: ruby/setup-ruby@v1
+       with:
+         ruby-version: '3.3'
+     ```
+fix_code:
+  - language: yaml
+    label: "Pin to macos-15 for immediate rollback"
+    code: |
+      jobs:
+        build:
+          runs-on: macos-15   # pinned until macos-26 migration complete
+          steps:
+            - uses: actions/checkout@v4
+  - language: yaml
+    label: "Full macos-26 compatible workflow — pin Xcode, Ruby, and OpenSSL"
+    code: |
+      jobs:
+        build:
+          runs-on: macos-latest  # now macos-26
+          steps:
+            - uses: actions/checkout@v4
+
+            # Pin Xcode version explicitly
+            - uses: maxim-lobanov/setup-xcode@v1
+              with:
+                xcode-version: '26.4'
+
+            # Pin Ruby if needed
+            - uses: ruby/setup-ruby@v1
+              with:
+                ruby-version: '3.3'
+                bundler-cache: true
+
+            # If OpenSSL 1.1 is needed, install and export paths
+            - name: Install OpenSSL 1.1
+              run: |
+                brew install openssl@1.1
+                echo "LDFLAGS=-L$(brew --prefix openssl@1.1)/lib" >> $GITHUB_ENV
+                echo "CPPFLAGS=-I$(brew --prefix openssl@1.1)/include" >> $GITHUB_ENV
+prevention:
+  - "Avoid relying on `macos-latest` for builds that depend on specific system library versions (OpenSSL, LLVM). Pin to a concrete label like `macos-15`."
+  - "Subscribe to the actions/runner-images repository announcements to get advance notice of `macos-latest` label migrations."
+  - "Use `ruby/setup-ruby`, `actions/setup-node`, and `actions/setup-python` to pin language runtimes instead of relying on runner image defaults."
+  - "Test your macOS workflows against the new image early by substituting `macos-26` before the `macos-latest` migration completes."
+  - "Audit all dylib/framework dependencies — anything linking to libssl.1.1 must be migrated to OpenSSL 3.x or brew-pinned."
+docs:
+  - url: "https://github.com/actions/runner-images/issues/14167"
+    label: "GitHub Announcement: macos-latest will use macos-26 in June 2026"
+  - url: "https://github.com/actions/runner-images/blob/main/images/macos/macos-26-arm64-Readme.md"
+    label: "macOS 26 arm64 image README — full software list"
+  - url: "https://docs.github.com/en/actions/using-github-hosted-runners/using-github-hosted-runners/about-github-hosted-runners"
+    label: "About GitHub-hosted runners — supported runner labels"
+source:
+  article: "https://htek.dev/articles/github-actions-debugging-guide"
+  section: "Runner image migrations"

package/errors/runner-environment/powershell-74-to-76-upgrade.yml

@@ -0,0 +1,112 @@
+id: runner-environment-019
+title: "PowerShell 7.4 → 7.6 LTS Upgrade Breaks pwsh Scripts"
+category: runner-environment
+severity: warning
+tags:
+  - powershell
+  - pwsh
+  - runner-image
+  - breaking-change
+  - windows
+  - linux
+patterns:
+  - regex: "The term 'ThreadJob\\\\\\\\Start-ThreadJob' is not recognized"
+    flags: "i"
+  - regex: "Cannot bind parameter.*ChildPath.*expected.*String.*got.*Array"
+    flags: "i"
+  - regex: "WildcardPattern.*backtick|escape.*pattern.*unexpected"
+    flags: "i"
+  - regex: "New-EventLog.*source.*trailing|event source.*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 bind parameter 'ChildPath'. Cannot convert the 'System.Object[]' value of type 'System.Object[]' to type 'System.String'."
+  - "Start-ThreadJob : The term 'ThreadJob\\Start-ThreadJob' is not recognized"
+root_cause: |
+  GitHub Actions upgraded PowerShell from 7.4.x to 7.6 LTS on all runner images beginning
+  June 8, 2026 (completing June 15, 2026). This affects every runner OS: ubuntu-22.04,
+  ubuntu-24.04, ubuntu-slim, macos-14/15/26, windows-2022/2025/2025-vs2026.
+
+  PowerShell 7.6 is built on .NET 10 (7.4 was on .NET 8). The documented breaking changes are:
+
+  1. **ThreadJob module renamed**: `ThreadJob` module is now `Microsoft.PowerShell.ThreadJob`.
+     Scripts calling `ThreadJob\Start-ThreadJob` with the old module-qualified name will throw
+     a "not recognized" error. The cmdlet itself (`Start-ThreadJob`) still works without prefix.
+
+  2. **`Join-Path -ChildPath` now accepts `string[]`**: Parameter binding changed from `string`
+     to `string[]`. Existing code that passes multiple -ChildPath args may see binding errors
+     depending on how arguments were constructed.
+
+  3. **`WildcardPattern.Escape` now correctly escapes lone backticks**: Scripts that relied on
+     the previous (incorrect) behavior of backtick handling in wildcard patterns may produce
+     different results.
+
+  4. **Event source name trailing space removed**: New-EventLog / Write-EventLog source names
+     no longer have a trailing space. Scripts that matched exact event source names including
+     the trailing space (e.g., `"MySource "`) will fail to match.
+
+  5. **.NET 10 runtime**: Any `pwsh` script using .NET types or reflection that was tested
+     against .NET 8 behavior may see subtle differences.
+fix: |
+  **ThreadJob module name** — the most common breaking change:
+  Replace `ThreadJob\Start-ThreadJob` with `Microsoft.PowerShell.ThreadJob\Start-ThreadJob`,
+  or just call `Start-ThreadJob` without the module qualifier.
+
+  **Event source name** — if you match exact source names:
+  Trim any trailing spaces from source name comparisons.
+
+  **Pin PowerShell version** if you need time to migrate (not recommended long-term):
+  Install a specific pwsh version in your workflow before running scripts.
+
+  **Test locally**: Install PowerShell 7.6 (`winget install Microsoft.PowerShell`) and run
+  your scripts to catch any remaining issues before they surface in CI.
+fix_code:
+  - language: yaml
+    label: "Fix ThreadJob module-qualified name"
+    code: |
+      # In your PowerShell script — change this:
+      #   ThreadJob\Start-ThreadJob -ScriptBlock { ... }
+      # To either:
+      #   Start-ThreadJob -ScriptBlock { ... }          # simplest fix
+      #   Microsoft.PowerShell.ThreadJob\Start-ThreadJob -ScriptBlock { ... }  # fully qualified
+  - language: yaml
+    label: "Pin PowerShell version as a temporary workaround"
+    code: |
+      jobs:
+        build:
+          runs-on: ubuntu-latest
+          steps:
+            - uses: actions/checkout@v4
+
+            # Pin pwsh to 7.4.x temporarily while migrating
+            - name: Install PowerShell 7.4
+              run: |
+                wget -q "https://github.com/PowerShell/PowerShell/releases/download/v7.4.10/powershell_7.4.10-1.deb_amd64.deb"
+                sudo dpkg -i powershell_7.4.10-1.deb_amd64.deb
+
+            - name: Run PowerShell script
+              shell: pwsh
+              run: ./scripts/build.ps1
+  - language: yaml
+    label: "Fix event source name trailing-space match"
+    code: |
+      # Before (broken on 7.6):
+      # if ($event.Source -eq "MyApp ") { ... }
+      #
+      # After (works on 7.4 and 7.6):
+      # if ($event.Source.Trim() -eq "MyApp") { ... }
+prevention:
+  - "Subscribe to actions/runner-images announcements for PowerShell upgrade notices well before they ship."
+  - "Always use unqualified cmdlet names (`Start-ThreadJob`) rather than module-qualified names (`ThreadJob\\Start-ThreadJob`) to avoid module-rename breakage."
+  - "Run your PowerShell scripts through PSScriptAnalyzer with the latest rule set after any PS version upgrade."
+  - "Test pwsh workflows in a matrix with the previous and new PS version during runner image transition periods."
+docs:
+  - url: "https://github.com/actions/runner-images/issues/14150"
+    label: "GitHub Announcement: PowerShell 7.4 → 7.6 upgrade on all runner images"
+  - url: "https://learn.microsoft.com/en-us/powershell/scripting/whats-new/what-s-new-in-powershell-76"
+    label: "PowerShell 7.6 release notes and breaking changes"
+  - url: "https://learn.microsoft.com/en-us/powershell/scripting/install/powershell-support-lifecycle"
+    label: "PowerShell support lifecycle"
+source:
+  article: "https://htek.dev/articles/github-actions-debugging-guide"
+  section: "Runner image tool version changes"

package/errors/runner-environment/service-container-unhealthy.yml

@@ -0,0 +1,126 @@
+id: runner-environment-021
+title: "Service Container Marked Unhealthy — Health Check Timeout"
+category: runner-environment
+severity: error
+tags:
+  - service-container
+  - healthcheck
+  - docker
+  - timeout
+  - postgres
+  - redis
+  - rabbitmq
+patterns:
+  - regex: "service is unhealthy"
+    flags: "i"
+  - regex: "Failed to initialize.*service is unhealthy"
+    flags: "i"
+  - regex: "##\\[error\\]Failed to initialize.*service"
+    flags: "i"
+  - regex: "container_id.*unhealthy"
+    flags: "i"
+error_messages:
+  - "##[error]Failed to initialize, rabbitmq service is unhealthy."
+  - "##[error]Failed to initialize, postgres service is unhealthy."
+  - "##[error]Failed to initialize, redis service is unhealthy."
+  - "unhealthy"
+  - "service is starting, waiting 29 seconds before checking again."
+root_cause: |
+  GitHub Actions checks the Docker HEALTHCHECK status of service containers
+  before allowing dependent job steps to run. If the container does not
+  transition to `healthy` within the runner's fixed retry window, the job
+  fails with "service is unhealthy".
+
+  This commonly occurs because:
+  1. **No options specified** — Docker uses the image's built-in HEALTHCHECK,
+     which may be missing, too aggressive, or unsuitable for the CI environment.
+  2. **Startup time** — services like PostgreSQL, RabbitMQ, or Elasticsearch
+     take longer to initialize on GitHub-hosted runners than on local machines,
+     and the default health-check interval/retries expire before they're ready.
+  3. **Wrong health-check command** — a network ping health check may fail if
+     the service port isn't yet bound even though the process is running.
+  4. **Missing `--health-start-period`** — without a start period, Docker counts
+     health-check failures from container start, before the service has had time
+     to initialize.
+
+  Documented in actions/example-services issue #3.
+fix: |
+  Add `options:` to the service container definition with explicit health-check
+  parameters suited to the service and GitHub-hosted runner environment:
+
+  - `--health-cmd`: Use a service-native health check command, not a TCP probe.
+    Examples:
+      PostgreSQL: `pg_isready -U postgres`
+      Redis:      `redis-cli ping`
+      MySQL:      `mysqladmin ping -h localhost`
+      RabbitMQ:   `rabbitmqctl node_health_check`
+
+  - `--health-interval 10s`: Check every 10 seconds
+  - `--health-timeout 5s`: Allow up to 5 seconds per check
+  - `--health-retries 5`: Retry up to 5 times before marking unhealthy
+  - `--health-start-period 30s`: Give 30 seconds before counting failures
+
+  If the image lacks a health check and the options approach is insufficient,
+  add an explicit wait step after job start using the service label name to
+  poll readiness with a loop.
+fix_code:
+  - language: yaml
+    label: "PostgreSQL service container with proper health check"
+    code: |
+      jobs:
+        test:
+          runs-on: ubuntu-latest
+          services:
+            postgres:
+              image: postgres:16
+              env:
+                POSTGRES_PASSWORD: postgres
+                POSTGRES_DB: testdb
+              ports:
+                - 5432:5432
+              options: >-
+                --health-cmd "pg_isready -U postgres"
+                --health-interval 10s
+                --health-timeout 5s
+                --health-retries 5
+                --health-start-period 30s
+          steps:
+            - run: psql postgresql://postgres:postgres@localhost:5432/testdb -c "SELECT 1"
+  - language: yaml
+    label: "Redis service container with proper health check"
+    code: |
+      services:
+        redis:
+          image: redis:7
+          ports:
+            - 6379:6379
+          options: >-
+            --health-cmd "redis-cli ping"
+            --health-interval 10s
+            --health-timeout 5s
+            --health-retries 5
+  - language: yaml
+    label: "Fallback — explicit wait step if health check unreliable"
+    code: |
+      steps:
+        - name: Wait for PostgreSQL to be ready
+          run: |
+            until pg_isready -h localhost -p 5432 -U postgres; do
+              echo "Waiting for postgres..."
+              sleep 2
+            done
+          timeout-minutes: 2
+prevention:
+  - "Always specify `options:` with `--health-cmd`, `--health-interval`, `--health-retries`, and `--health-start-period` for every service container."
+  - "Use service-native health check commands (pg_isready, redis-cli ping) rather than generic TCP probes."
+  - "Add `--health-start-period` of 20-30 seconds for services with slow initialization (PostgreSQL, Elasticsearch, RabbitMQ)."
+  - "Test health check timing locally in Docker before relying on it in CI: `docker run --health-cmd '...' --health-interval 5s <image>`."
+docs:
+  - url: "https://docs.github.com/en/actions/using-containerized-services/about-service-containers"
+    label: "About service containers"
+  - url: "https://docs.github.com/en/actions/using-workflows/workflow-syntax-for-github-actions#jobsjob_idservicesservice_idoptions"
+    label: "Workflow syntax — services options"
+  - url: "https://github.com/actions/example-services/issues/3"
+    label: "actions/example-services #3 — Service container health check questions and fixes"
+  - url: "https://stackoverflow.com/questions/66763353/how-to-health-check-a-service-in-github"
+    label: "Stack Overflow — How to health check a service in GitHub Actions"