@htekdev/actions-debugger 1.0.23 → 1.0.25

package/errors/triggers/schedule-cron-self-hosted-runner-not-triggered.yml

@@ -0,0 +1,107 @@
+id: triggers-024
+title: "Scheduled Cron Workflow Does Not Trigger on Self-Hosted Runner"
+category: triggers
+severity: error
+tags:
+  - cron
+  - schedule
+  - self-hosted-runner
+  - trigger
+  - offline
+patterns:
+  - regex: "cron.*self.hosted"
+    flags: "i"
+  - regex: "schedule.*self.hosted"
+    flags: "i"
+error_messages:
+  - "No trigger for scheduled cron task in Github actions on a self-hosted runner"
+root_cause: |
+  Scheduled (on: schedule) workflows are queued by GitHub hosted-runner dispatch
+  infrastructure. When the job targets a self-hosted runner (runs-on: [self-hosted, ...]),
+  the schedule dispatcher attempts to assign the job to a registered self-hosted runner.
+
+  The workflow silently never runs when:
+  1. The self-hosted runner is offline or disconnected at the moment the schedule fires.
+  2. The runner is busy with another job and no other runner with the required label is idle.
+  3. The runner binary is outdated or the registration token has expired, causing the runner
+     to appear registered but fail to accept new jobs.
+  4. The repository has been inactive for 60+ days (GitHub disables scheduled workflows
+     on inactive repositories automatically).
+
+  Unlike GitHub-hosted runners, where a fresh VM is provisioned on demand for every job,
+  self-hosted runners must be online and idle at exactly the moment the schedule fires.
+  If no eligible runner is available, the queued job is eventually abandoned with no retry
+  and no error visible in the Actions UI. The run simply does not appear.
+  Reported in actions/runner#4210 (21 reactions, open since Jan 2026).
+fix: |
+  Option 1 (recommended): Run the scheduled trigger on a GitHub-hosted runner.
+  Use ubuntu-latest for the schedule job and dispatch the real work to self-hosted
+  via workflow_dispatch or a separate triggered workflow.
+
+  Option 2: Use an external scheduler with workflow_dispatch.
+  Remove the on: schedule trigger. Use an external cron (cron job, cloud function, GitHub App)
+  to call the GitHub REST API dispatches endpoint on a schedule. The workflow is triggered
+  by workflow_dispatch instead, which does not require the runner to be available at a
+  fixed clock time.
+
+  Option 3: Ensure runner availability with a persistent service.
+  Run the self-hosted runner as a systemd service with Restart=always so it is online
+  when schedules fire. This reduces but does not eliminate the risk.
+fix_code:
+  - language: yaml
+    label: "Option 1: Schedule on GitHub-hosted, dispatch to self-hosted"
+    code: |
+      on:
+        schedule:
+          - cron: '0 2 * * *'
+        workflow_dispatch: {}
+
+      jobs:
+        # Lightweight orchestrator runs on GitHub-hosted (always available at schedule time)
+        trigger:
+          runs-on: ubuntu-latest
+          steps:
+            - name: Trigger self-hosted workflow
+              uses: actions/github-script@v7
+              with:
+                script: |
+                  await github.rest.actions.createWorkflowDispatch({
+                    owner: context.repo.owner,
+                    repo: context.repo.repo,
+                    workflow_id: 'heavy-work.yml',
+                    ref: 'main'
+                  });
+  - language: yaml
+    label: "Option 2: Receive dispatch from external cron scheduler"
+    code: |
+      # External scheduler calls:
+      # curl -X POST \
+      #   -H "Authorization: Bearer $GH_TOKEN" \
+      #   https://api.github.com/repos/OWNER/REPO/actions/workflows/nightly.yml/dispatches \
+      #   -d '{"ref":"main"}'
+      #
+      # Your workflow:
+      on:
+        workflow_dispatch: {}   # Triggered externally; no GitHub-side scheduling dependency
+
+      jobs:
+        nightly:
+          runs-on: [self-hosted, linux, x64]
+          steps:
+            - uses: actions/checkout@v4
+            - run: ./scripts/nightly.sh
+prevention:
+  - "Run self-hosted runners as a persistent systemd service (Restart=always, RestartSec=10) to minimize offline windows."
+  - "Add workflow_dispatch: alongside schedule: so missed runs can be manually re-triggered from the Actions UI."
+  - "Monitor runner registration status via GET /repos/{owner}/{repo}/actions/runners and alert on offline runners."
+  - "Keep repositories active with at least one push or workflow run to prevent scheduled workflow disablement after 60 days of inactivity."
+  - "Consider using ephemeral runners with autoscaling (ARC) so runners are always provisioned on demand."
+docs:
+  - url: "https://github.com/actions/runner/issues/4210"
+    label: "actions/runner#4210 — Cron not triggering on self-hosted runner (Jan 2026)"
+  - url: "https://github.com/orgs/community/discussions/185024"
+    label: "Community discussion: self-hosted runner not triggering scheduled cron"
+  - url: "https://docs.github.com/en/actions/writing-workflows/choosing-when-your-workflow-runs/events-that-trigger-workflows#schedule"
+    label: "schedule event documentation"
+  - url: "https://docs.github.com/en/actions/managing-workflow-runs-and-deployments/managing-workflow-runs/disabling-and-enabling-a-workflow"
+    label: "Workflow disabled after 60 days of repo inactivity"

package/errors/yaml-syntax/case-function-runner-version-too-old.yml

@@ -0,0 +1,100 @@
+id: yaml-syntax-031
+title: "case() expression function fails with 'Unrecognized function' on runners older than 2.329.0"
+category: yaml-syntax
+severity: error
+tags:
+  - case-function
+  - expressions
+  - runner-version
+  - self-hosted
+  - composite-action
+  - if-condition
+
+patterns:
+  - regex: "Unrecognized function: 'case'"
+    flags: "i"
+  - regex: "The workflow is not valid.*Unrecognized function.*case"
+    flags: "i"
+
+error_messages:
+  - "Unrecognized function: 'case'. Located at position 1 within expression: case(github.event_name == 'push', 'deploy', github.event_name == 'pull_request', 'review', 'skip')"
+  - "The workflow is not valid. .github/workflows/deploy.yml (Line: 24, Col: 16): Unrecognized function: 'case'"
+
+root_cause: |
+  GitHub introduced the case() expression function in runner version 2.329.0 (January 2026,
+  announced in the GitHub Actions changelog on 2026-01-29). The case() function enables
+  conditional branching similar to SQL CASE expressions, supporting if-else and switch-case
+  patterns in workflow expressions.
+
+  Self-hosted runners that have not been updated to version 2.329.0 or later do not recognize
+  case() as a valid function. When any workflow step, job-level if: condition, output mapping,
+  or composite action uses ${{ case(...) }}, the runner throws "Unrecognized function: 'case'"
+  and the job fails immediately.
+
+  GitHub-hosted runners (ubuntu-latest, windows-latest, macos-latest) receive runner updates
+  automatically and are not affected. Only self-hosted runners with version pinning or delayed
+  update policies encounter this error.
+
+  A secondary regression occurred in runner 2.333.0 (March 2026) where case() was temporarily
+  broken for composite actions specifically, producing the same error. This was resolved in
+  2.333.1.
+
+fix: |
+  For self-hosted runners: Update the runner to version 2.329.0 or later. Runner updates
+  can be applied via the GitHub Actions runner update script or by re-registering the runner
+  with the latest version from the GitHub Actions runner releases page.
+
+  To verify your runner version: check Settings > Actions > Runners in your repository or
+  organization, or inspect the runner binary with ./actions-runner/config.sh --version.
+
+  Temporary workaround: Rewrite case() expressions using nested ternary-style expressions
+  that work on all runner versions, then migrate to case() once runners are updated.
+
+fix_code:
+  - language: yaml
+    label: "New (requires runner 2.329.0+): using case() for conditional output"
+    code: |
+      jobs:
+        determine-env:
+          runs-on: self-hosted
+          outputs:
+            environment: ${{ steps.set-env.outputs.env }}
+          steps:
+            - id: set-env
+              run: echo "env=${{ case(github.ref == 'refs/heads/main', 'production', github.ref == 'refs/heads/staging', 'staging', 'development') }}" >> $GITHUB_OUTPUT
+
+  - language: yaml
+    label: "Fallback for runners older than 2.329.0 (works on all versions)"
+    code: |
+      jobs:
+        determine-env:
+          runs-on: self-hosted
+          outputs:
+            environment: ${{ steps.set-env.outputs.env }}
+          steps:
+            - id: set-env
+              run: |
+                REF="${{ github.ref }}"
+                if [[ "$REF" == "refs/heads/main" ]]; then
+                  echo "env=production" >> $GITHUB_OUTPUT
+                elif [[ "$REF" == "refs/heads/staging" ]]; then
+                  echo "env=staging" >> $GITHUB_OUTPUT
+                else
+                  echo "env=development" >> $GITHUB_OUTPUT
+                fi
+
+prevention:
+  - "Pin runner version in self-hosted runner documentation and set up automated update notifications."
+  - "Add a workflow step that logs the runner version (echo $ACTIONS_RUNNER_VERSION) to surface version mismatches early."
+  - "Test new expression functions on GitHub-hosted runners first; then roll out to self-hosted after confirming the runner version."
+  - "Configure runner auto-update policies — GitHub recommends keeping self-hosted runners within 2 major versions of the latest."
+
+docs:
+  - url: "https://github.blog/changelog/2026-01-29-github-actions-smarter-editing-clearer-debugging-and-a-new-case-function/"
+    label: "GitHub Changelog 2026-01-29: New case() function introduction"
+  - url: "https://docs.github.com/en/actions/writing-workflows/choosing-what-your-workflow-does/evaluate-expressions-in-workflows-and-actions"
+    label: "GitHub Docs: Expressions — case() function reference"
+  - url: "https://github.com/actions/runner/issues/4315"
+    label: "actions/runner#4315: Runner v2.333.0 breaks case function (regression)"
+  - url: "https://github.com/actions/runner/releases"
+    label: "GitHub Actions Runner releases — version history"

package/errors/yaml-syntax/composite-action-run-shell-missing.yml

@@ -0,0 +1,90 @@
+id: yaml-syntax-030
+title: "Composite Action run: Step Missing Required shell: Property"
+category: yaml-syntax
+severity: error
+tags:
+  - composite-action
+  - shell
+  - required-property
+  - action-yml
+  - schema-validation
+patterns:
+  - regex: "Required property is missing: shell"
+    flags: "i"
+  - regex: "action\\.yml.*Required property is missing: shell"
+    flags: "i"
+error_messages:
+  - "Required property is missing: shell"
+  - "(Line: 29, Col: 5): Required property is missing: shell"
+  - "Error: GitHub.DistributedTask.ObjectTemplating.TemplateValidationException: The template is not valid."
+  - "Error: Fail to load action.yml"
+root_cause: |
+  Every run: step inside a composite action's action.yml MUST declare an explicit
+  shell: property. This is mandatory for composite actions — unlike regular workflow
+  run: steps where the runner infers the shell from the operating system, composite
+  action steps require an explicit declaration because the action may run on any OS.
+
+  The validation error fires at workflow preparation time (before any steps execute),
+  causing the entire workflow to fail with "Fail to load <action>.yml".
+
+  This is a common mistake when:
+  - Converting a workflow step into a reusable composite action
+  - Copying run: steps from a workflow into action.yml without adding shell:
+  - Using a third-party composite action whose author omitted the shell: property
+fix: |
+  Add shell: to every run: step in the composite action's action.yml.
+
+  Supported shell values: bash, sh, python, pwsh, powershell, cmd
+
+  For cross-platform composite actions, use shell: bash (available on all
+  GitHub-hosted runners including Windows via Git Bash). If platform-specific
+  behavior is needed, use if: runner.os == 'Windows' conditionals with
+  separate steps.
+fix_code:
+  - language: yaml
+    label: "Broken action.yml — run steps missing shell:"
+    code: |
+      runs:
+        using: "composite"
+        steps:
+          - name: Install dependencies
+            run: npm ci
+          - name: Run build
+            run: npm run build
+  - language: yaml
+    label: "Fixed action.yml — shell: added to every run step"
+    code: |
+      runs:
+        using: "composite"
+        steps:
+          - name: Install dependencies
+            run: npm ci
+            shell: bash
+          - name: Run build
+            run: npm run build
+            shell: bash
+  - language: yaml
+    label: "Cross-platform composite action with OS-conditional steps"
+    code: |
+      runs:
+        using: "composite"
+        steps:
+          - name: Run script (cross-platform)
+            run: echo "Running on ${{ runner.os }}"
+            shell: bash
+          - name: Windows-only step
+            if: runner.os == 'Windows'
+            run: Write-Host "Windows step"
+            shell: pwsh
+prevention:
+  - "Add actionlint to your CI — it catches missing shell: properties in composite actions."
+  - "When creating a new composite action, start from the GitHub documentation template which includes shell: on all run steps."
+  - "Every run: step in action.yml requires shell: — add this to code review checklists."
+  - "Use rhysd/actionlint locally or as a pre-commit hook to validate composite action syntax before pushing."
+docs:
+  - url: "https://docs.github.com/en/actions/sharing-automations/creating-actions/creating-a-composite-action"
+    label: "GitHub Docs: Creating a composite action"
+  - url: "https://stackoverflow.com/questions/71041836/github-actions-required-property-is-missing-shell"
+    label: "Stack Overflow: Required property is missing: shell (Score: 51, 31K views)"
+  - url: "https://docs.github.com/en/actions/sharing-automations/creating-actions/metadata-syntax-for-github-actions#runs-for-composite-actions"
+    label: "GitHub Docs: Metadata syntax for composite actions (runs.steps[*].shell)"

package/errors/yaml-syntax/composite-action-secrets-context-unavailable.yml

@@ -0,0 +1,99 @@
+id: yaml-syntax-025
+title: "secrets Context Unavailable Inside Composite Action Definitions"
+category: yaml-syntax
+severity: error
+tags:
+  - composite-actions
+  - secrets-context
+  - expression
+  - runner-validation
+  - context-availability
+  - action-yml
+patterns:
+  - regex: "Unrecognized named-value.*'?secrets'?"
+    flags: "i"
+  - regex: "Unexpected value.*secrets\\.\\w+"
+    flags: "i"
+error_messages:
+  - "Unrecognized named-value: 'secrets'. Located at position 1 within expression: secrets.MY_TOKEN"
+  - "Error: Unrecognized named-value: 'secrets'"
+  - "Invalid workflow file: .github/actions/my-action/action.yml (Line 12, Col 18): Unrecognized named-value: 'secrets'"
+root_cause: |
+  The `secrets` context is **not available inside composite action definitions** (`action.yml`).
+  When a developer writes `${{ secrets.MY_TOKEN }}` inside a composite action's steps or
+  expressions, runner validation rejects it with "Unrecognized named-value: 'secrets'".
+
+  This is a deliberate architectural restriction. Composite actions run in the calling
+  workflow's runner environment but do NOT receive the calling workflow's secrets context.
+  The `secrets` context is only available in:
+  - Regular workflow job steps (`jobs.<job_id>.steps.*`)
+  - Reusable workflows (`.github/workflows/*.yml` using `on: workflow_call`)
+
+  Composite actions (`action.yml` with `using: composite`) only receive values the calling
+  workflow explicitly passes as `inputs`. This differs from `vars` context rejection
+  (yaml-syntax-016) — both contexts are unavailable in composite actions, but the pattern
+  for passing secrets as inputs is worth documenting separately.
+
+  A common migration mistake: extracting workflow steps that reference `${{ secrets.GITHUB_TOKEN }}`
+  into a composite action and expecting them to continue working unchanged.
+fix: |
+  Declare an explicit `input` for each secret the composite action needs. The calling workflow
+  passes secrets at the `with:` level — where the secrets context IS available. Inside the
+  composite action, reference `${{ inputs.token }}` instead of `${{ secrets.MY_TOKEN }}`.
+
+  Never reference the secrets context directly inside `action.yml` regardless of runner version.
+fix_code:
+  - language: yaml
+    label: "action.yml — Replace secrets.* with an explicit input"
+    code: |
+      # ❌ BROKEN: secrets context not available in composite actions
+      # .github/actions/deploy/action.yml
+      name: Deploy
+      description: Deploy to production
+      runs:
+        using: composite
+        steps:
+          - name: Authenticate
+            shell: bash
+            run: |
+              # ❌ Will fail: Unrecognized named-value: 'secrets'
+              echo "${{ secrets.DEPLOY_TOKEN }}" | docker login ghcr.io -u user --password-stdin
+
+      ---
+
+      # ✅ CORRECT: accept token via explicit input
+      name: Deploy
+      description: Deploy to production
+      inputs:
+        deploy-token:
+          description: "Authentication token for container registry"
+          required: true
+      runs:
+        using: composite
+        steps:
+          - name: Authenticate
+            shell: bash
+            run: echo "${{ inputs.deploy-token }}" | docker login ghcr.io -u user --password-stdin
+  - language: yaml
+    label: "Calling workflow — pass secrets at the with: level"
+    code: |
+      # ✅ Caller resolves secrets context and passes value as composite action input
+      jobs:
+        deploy:
+          runs-on: ubuntu-latest
+          steps:
+            - uses: ./.github/actions/deploy
+              with:
+                deploy-token: ${{ secrets.DEPLOY_TOKEN }}  # secrets resolved in caller, not in composite
+prevention:
+  - "Never reference `secrets.*` directly inside composite action `action.yml` — require callers to pass secrets as explicit inputs."
+  - "When migrating workflow steps to a composite action, replace every `${{ secrets.X }}` with a declared input and update all callers."
+  - "Use `actionlint` to statically validate context access in composite actions before pushing."
+  - "Composite actions (composite) require explicit input passing for secrets; reusable workflows (workflow_call) support `secrets: inherit`."
+docs:
+  - url: "https://docs.github.com/en/actions/writing-workflows/choosing-what-your-workflow-does/accessing-contextual-information-about-workflow-runs#context-availability"
+    label: "GitHub Docs: Context availability by element type"
+  - url: "https://docs.github.com/en/actions/sharing-automations/creating-actions/creating-a-composite-action"
+    label: "GitHub Docs: Creating a composite action"
+  - url: "https://stackoverflow.com/questions/73821801/unable-to-use-secrets-in-workflow"
+    label: "SO#73821801 — Unrecognized named-value: 'secrets' in composite action (3,059 views)"

package/errors/yaml-syntax/github-script-octokit-renamed-to-github.yml

@@ -0,0 +1,130 @@
+id: yaml-syntax-026
+title: "actions/github-script: 'octokit' Not Defined — API Client Renamed to 'github'"
+category: yaml-syntax
+severity: error
+tags:
+  - github-script
+  - octokit
+  - javascript
+  - api-client
+  - breaking-change
+  - v4
+patterns:
+  - regex: "ReferenceError: octokit is not defined"
+    flags: "i"
+  - regex: "octokit is not defined"
+    flags: "i"
+  - regex: "TypeError: Cannot read propert(?:y|ies) of undefined.*octokit"
+    flags: "i"
+  - regex: "Error: Unhandled error: ReferenceError: octokit is not defined"
+    flags: "i"
+error_messages:
+  - "ReferenceError: octokit is not defined"
+  - "Error: Unhandled error: ReferenceError: octokit is not defined"
+  - "Error: Script failed with exit code 1 — ReferenceError: octokit is not defined"
+root_cause: |
+  In versions of `actions/github-script` prior to v4, the Octokit REST client
+  was injected into the script as a variable named `octokit`. The action was
+  refactored and the variable was renamed to `github` in v4 (released late 2020).
+
+  Many blog posts, Stack Overflow answers, older README examples, and community
+  discussions still use the original `octokit` variable name. Developers copying
+  these examples encounter `ReferenceError: octokit is not defined` at runtime
+  because the variable no longer exists.
+
+  Available variables injected into `actions/github-script` scripts (v4+):
+  - `github`   — authenticated Octokit REST + GraphQL client (replaces old `octokit`)
+  - `context`  — workflow run context (repo, sha, ref, event payload, etc.)
+  - `core`     — @actions/core (setOutput, setFailed, info, warning, etc.)
+  - `glob`     — @actions/glob (file globbing utility)
+  - `io`       — @actions/io (filesystem utilities)
+  - `exec`     — @actions/exec (run shell commands from script)
+  - `require`  — restricted require() for loading bundled modules
+
+  The variable `octokit` does not exist in any released version of
+  actions/github-script. It was never a stable public interface — the README
+  always showed `github`, but pre-release/alpha samples used `octokit`.
+
+  A secondary version of this error occurs with `github.rest` vs `github` API
+  surface: in v6+, REST methods moved to `github.rest.*` (e.g.,
+  `github.rest.issues.create()`). Scripts using `github.issues.create()` (v5
+  style) will fail with "TypeError: github.issues.create is not a function"
+  on v6+.
+fix: |
+  Replace every occurrence of `octokit` in your script with `github`:
+
+    Before (broken):  const result = await octokit.rest.issues.create({...})
+    After (correct):  const result = await github.rest.issues.create({...})
+
+  If you are using an older API surface (pre-v6), also update method paths:
+    Before (v5):  await github.issues.create({...})
+    After (v6+):  await github.rest.issues.create({...})
+
+  Check your github-script version — v6 is the current stable release (v7 is
+  also available with Node.js 20). Pin to a major version like @v7 rather than
+  a commit SHA to get bugfixes without breaking changes.
+fix_code:
+  - language: yaml
+    label: "Before (broken) vs After (correct) — replace octokit with github"
+    code: |
+      # BROKEN — uses old `octokit` variable name (throws ReferenceError):
+      - uses: actions/github-script@v7
+        with:
+          script: |
+            const { data: issue } = await octokit.rest.issues.create({
+              owner: context.repo.owner,
+              repo: context.repo.repo,
+              title: 'Automated issue',
+              body: 'Created by workflow'
+            });
+
+      # CORRECT — use `github` (the injected Octokit client):
+      - uses: actions/github-script@v7
+        with:
+          script: |
+            const { data: issue } = await github.rest.issues.create({
+              owner: context.repo.owner,
+              repo: context.repo.repo,
+              title: 'Automated issue',
+              body: 'Created by workflow'
+            });
+            console.log('Created issue #' + issue.number);
+  - language: yaml
+    label: "Common github-script v5 to v6+ migration — update method paths"
+    code: |
+      # v5 style (broken on v6+):
+      - uses: actions/github-script@v6
+        with:
+          script: |
+            await github.issues.addLabels({       # BROKEN: no github.issues
+              issue_number: context.issue.number,
+              owner: context.repo.owner,
+              repo: context.repo.repo,
+              labels: ['bug']
+            });
+
+      # v6+ style (correct):
+      - uses: actions/github-script@v7
+        with:
+          script: |
+            await github.rest.issues.addLabels({  # CORRECT: github.rest.*
+              issue_number: context.issue.number,
+              owner: context.repo.owner,
+              repo: context.repo.repo,
+              labels: ['bug']
+            });
+prevention:
+  - "Always use `github` (not `octokit`) as the Octokit client variable in actions/github-script — `octokit` has never been a stable public interface."
+  - "Pin to a major version like `actions/github-script@v7` rather than copying scripts from undated blog posts or old Stack Overflow answers that may reference pre-release variable names."
+  - "Test scripts locally using the `@octokit/rest` npm package before embedding them in a workflow — you'll get clear errors immediately rather than waiting for a CI run."
+  - "Read the actions/github-script README for your pinned version — the variable reference table at the top shows exactly what is injected (github, context, core, glob, io, exec)."
+  - "When upgrading from github-script v5 to v6+, update all REST method calls from `github.X.Y()` to `github.rest.X.Y()` — this is the only breaking change between v5 and v6."
+docs:
+  - url: "https://github.com/actions/github-script"
+    label: "actions/github-script README — available variables (github, context, core, etc.)"
+  - url: "https://github.com/actions/github-script/issues/545"
+    label: "actions/github-script #545: octokit instance from README examples doesn't work (12 reactions)"
+  - url: "https://github.com/actions/github-script/releases/tag/v4.0.0"
+    label: "actions/github-script v4 release — renamed octokit → github"
+  - url: "https://octokit.github.io/rest.js/v21"
+    label: "Octokit REST.js v21 API reference — methods available via github.rest.*"

package/errors/yaml-syntax/labeler-v5-config-format-breaking.yml

@@ -0,0 +1,67 @@
+id: yaml-syntax-028
+title: "actions/labeler v5 config format breaking change causes unexpected type error"
+category: yaml-syntax
+severity: error
+tags:
+  - labeler
+  - v5-breaking-change
+  - config-format
+  - pull-request-labels
+  - migration
+patterns:
+  - regex: "found unexpected type for label '.+' \\(should be array of config options\\)"
+    flags: "i"
+  - regex: "Error: found unexpected type for label"
+    flags: "i"
+error_messages:
+  - "Error: found unexpected type for label 'frontend' (should be array of config options)"
+  - "found unexpected type for label 'X' (should be array of config options)"
+root_cause: |
+  actions/labeler v5.0.0 introduced a breaking change to the labeler.yml configuration format.
+  In v4 and earlier, labels could be configured as a flat list of glob patterns (strings).
+  In v5, each label must be an array of objects with specific keys such as changed-files,
+  head-branch, or base-branch. If a workflow pins to @master or @latest and a new major
+  version is published, workflows inherit the breaking format without warning.
+  The old flat string format ("label: - path/**") is no longer valid in v5 and causes
+  the action to throw immediately.
+fix: |
+  Either migrate labeler.yml to the v5 object format using changed-files key, or pin the
+  action to @v4 to preserve the old flat string format.
+fix_code:
+  - language: yaml
+    label: "Old v4 format (still works with actions/labeler@v4)"
+    code: |
+      # .github/labeler.yml (v4 format)
+      frontend:
+        - shared/frontend/**/*
+      backend:
+        - shared/api/**/*
+  - language: yaml
+    label: "New v5 format (required for actions/labeler@v5)"
+    code: |
+      # .github/labeler.yml (v5 format)
+      frontend:
+        - changed-files:
+          - any-glob-to-any-file: shared/frontend/**/*
+      backend:
+        - changed-files:
+          - any-glob-to-any-file: shared/api/**/*
+  - language: yaml
+    label: "Pin to v4 to avoid breaking change"
+    code: |
+      steps:
+        - uses: actions/labeler@v4
+          with:
+            repo-token: ${{ secrets.GITHUB_TOKEN }}
+prevention:
+  - "Never pin actions to @master or @latest branch — always use a major version tag like @v4"
+  - "Review the CHANGELOG or release notes before bumping a major version of any action"
+  - "Use Dependabot with major version grouping to get explicit upgrade PRs for breaking changes"
+  - "Test label config changes in a fork or draft PR before merging"
+docs:
+  - url: "https://github.com/actions/labeler/issues/710"
+    label: "actions/labeler#710: found unexpected type for label (v5 breaking change)"
+  - url: "https://github.com/actions/labeler/releases/tag/v5.0.0"
+    label: "actions/labeler v5.0.0 release notes"
+  - url: "https://github.com/actions/labeler/tree/main#pull-request-labeler"
+    label: "actions/labeler v5 configuration documentation"