@htekdev/actions-debugger 1.0.44 → 1.0.46

package/errors/caching-artifacts/caching-artifacts-034.yml

@@ -0,0 +1,70 @@
+id: caching-artifacts-034
+title: "Cache entries created in a PR branch are not accessible from other PR branches or the default branch"
+category: caching-artifacts
+severity: limitation
+tags:
+  - cache
+  - branch-scope
+  - pull-request
+  - isolation
+  - cache-miss
+  - known-limitation
+patterns:
+  - regex: 'cache.*miss.*pull.request|cache.*not.*found.*branch|cache.*not.*accessible.*pr'
+    flags: "i"
+  - regex: 'cache.*scope.*branch|branch.specific.*cache.*miss|pr.*branch.*no.*cache'
+    flags: "i"
+error_messages:
+  - "Cache not found for input keys"
+root_cause: |
+  GitHub Actions cache entries are strictly scoped to the branch that created them. The
+  cache lookup order during a restore operation is:
+
+  1. Exact key match on the CURRENT branch
+  2. restore-keys prefix match on the CURRENT branch
+  3. restore-keys prefix match on the BASE branch (for PRs) or the DEFAULT branch
+
+  Consequences of this scoping:
+  - A cache saved on PR branch A is NOT readable from PR branch B
+  - A cache saved on a PR branch is NOT readable from the default branch's push workflow
+  - Each new PR starts with a cold cache until it produces its own branch-scoped entry
+  - The base branch cache is only available as a fallback during a PR workflow restore
+
+  This is an intentional security isolation boundary — one PR cannot read potentially
+  sensitive build artifacts cached by another PR. There is no configuration option to
+  enable cross-PR cache sharing.
+
+  Teams migrating from shared CI caches (Jenkins, GitLab with shared runner caches) are
+  frequently surprised by persistent cache misses across parallel PRs on active repos.
+fix: |
+  Structure cache keys and restore-keys to maximize fallback hits from the default branch.
+  The strategy: save a well-keyed cache on the default branch after each merge (readable
+  by all PRs as a fallback), and include base-branch and OS-only restore-key prefixes so
+  new PR runs warm up quickly via partial matches.
+
+  For dependency caches, a lockfile-hash-keyed entry on main ensures new PRs get a
+  near-hit on first run via restore-keys, rather than a completely cold cache.
+fix_code:
+  - language: yaml
+    label: "Cache key strategy that maximizes default-branch fallback for all PRs"
+    code: |
+      - name: Cache dependencies
+        uses: actions/cache@v4
+        with:
+          path: ~/.npm
+          # Primary: exact branch + lockfile hash (hit on repeat runs of same PR)
+          key: ${{ runner.os }}-npm-${{ github.ref_name }}-${{ hashFiles('**/package-lock.json') }}
+          # Fallbacks: base branch (for PRs) → default branch → OS-only
+          restore-keys: |
+            ${{ runner.os }}-npm-${{ github.base_ref }}-
+            ${{ runner.os }}-npm-
+prevention:
+  - "Add restore-keys with base branch and OS-only prefixes so PRs fall back to main's cache"
+  - "Ensure the default branch workflow saves a fresh cache after each merge so PRs have a warm fallback"
+  - "Be aware that parallel PRs each maintain their own independent branch-scoped cache"
+  - "For monorepos, include the workspace or package path in the cache key to prevent cross-PR key collisions"
+docs:
+  - url: "https://docs.github.com/en/actions/writing-workflows/choosing-what-your-workflow-does/caching-dependencies-to-speed-up-workflows#restrictions-for-accessing-a-cache"
+    label: "GitHub Docs: Cache access restrictions by branch"
+  - url: "https://github.com/orgs/community/discussions/10539"
+    label: "GitHub Community: Cache access is restricted to the same branch and base branches"

package/errors/known-unsolved/known-unsolved-035.yml

@@ -0,0 +1,97 @@
+id: known-unsolved-035
+title: "workflow_run trigger only fires for same-repo workflows — cross-repo chaining not supported"
+category: known-unsolved
+severity: limitation
+tags:
+  - workflow_run
+  - cross-repo
+  - triggers
+  - repository-dispatch
+  - known-limitation
+  - event-chaining
+patterns:
+  - regex: 'workflow_run.*never.*trigger|on.*workflow_run.*different.*repo'
+    flags: "i"
+  - regex: 'cross.repo.*workflow.run|workflow_run.*external.*repo'
+    flags: "i"
+error_messages:
+  - "workflow_run trigger does not fire for workflows in a different repository"
+root_cause: |
+  The on: workflow_run trigger only listens to workflow completion events in the same
+  repository. It cannot subscribe to events from workflows in external repositories,
+  even within the same organization or enterprise. Teams building cross-repository
+  CI/CD chains (e.g., "when repo-A build finishes, trigger repo-B deploy") discover
+  that the downstream workflow simply never starts — there is no error, just silence.
+
+  This is a platform design decision: workflow_run was built for intra-repo fan-out
+  (e.g., running security scans after CI passes) and not for cross-repo event routing.
+
+  Common scenarios where this limitation is hit:
+  - Platform team repo triggering deploy workflows in service repos
+  - Shared library repo signaling consumers after a release
+  - Monorepo-to-polyrepo migration preserving CI event chains
+  - Organization-wide rollout pipelines spanning multiple repositories
+fix: |
+  Use repository_dispatch for cross-repo event chaining. The upstream workflow sends
+  a POST to the GitHub REST API to create a repository_dispatch event in the downstream
+  repo. The downstream workflow listens on on: repository_dispatch: types: [...].
+
+  This requires a PAT (classic) with repo scope, or a GitHub App token with contents:
+  write or actions: write on the downstream repository. The peter-evans/repository-dispatch
+  action is the most widely used wrapper.
+fix_code:
+  - language: yaml
+    label: "Upstream (repo-A): dispatch event to repo-B on workflow completion"
+    code: |
+      # .github/workflows/build.yml in repo-A
+      on:
+        push:
+          branches: [main]
+
+      jobs:
+        build:
+          runs-on: ubuntu-latest
+          steps:
+            - name: Build
+              run: make build
+
+            - name: Trigger deployment in repo-B
+              uses: peter-evans/repository-dispatch@v3
+              with:
+                token: ${{ secrets.CROSS_REPO_PAT }}
+                repository: my-org/repo-B
+                event-type: repo-a-build-complete
+                client-payload: >-
+                  {"sha": "${{ github.sha }}", "ref": "${{ github.ref }}",
+                   "run_id": "${{ github.run_id }}"}
+  - language: yaml
+    label: "Downstream (repo-B): receive repository_dispatch from repo-A"
+    code: |
+      # .github/workflows/deploy.yml in repo-B
+      on:
+        repository_dispatch:
+          types: [repo-a-build-complete]
+
+      jobs:
+        deploy:
+          runs-on: ubuntu-latest
+          steps:
+            - name: Deploy
+              run: |
+                echo "Triggered by SHA: ${{ github.event.client_payload.sha }}"
+                echo "Source run: ${{ github.event.client_payload.run_id }}"
+                # deploy steps here
+prevention:
+  - "Use repository_dispatch for cross-repository event chaining — workflow_run is same-repo only"
+  - "Document this limitation in workflow comments so future maintainers don't spend time debugging non-firing triggers"
+  - "Consider reusable workflows (workflow_call) for sharing logic within an org instead of cross-repo triggers"
+  - "For org-wide fan-out, a central platform repo dispatching to all downstream repos is a common pattern"
+docs:
+  - url: "https://docs.github.com/en/actions/writing-workflows/choosing-when-your-workflow-runs/events-that-trigger-workflows#workflow_run"
+    label: "GitHub Docs: workflow_run trigger"
+  - url: "https://docs.github.com/en/rest/repos/repos#create-a-repository-dispatch-event"
+    label: "GitHub REST API: Create a repository dispatch event"
+  - url: "https://github.com/peter-evans/repository-dispatch"
+    label: "peter-evans/repository-dispatch action"
+  - url: "https://github.com/orgs/community/discussions/26323"
+    label: "GitHub Community #26323: workflow_run cross-repo limitation confirmed"

package/errors/known-unsolved/known-unsolved-036.yml

@@ -0,0 +1,87 @@
+id: known-unsolved-036
+title: "Scheduled workflows auto-disabled after 60 days of repository inactivity"
+category: known-unsolved
+severity: limitation
+tags:
+  - schedule
+  - cron
+  - inactivity
+  - disabled
+  - known-limitation
+  - maintenance
+patterns:
+  - regex: 'This scheduled workflow is disabled|scheduled workflow.*disabled.*no.*activity'
+    flags: "i"
+  - regex: 'schedule.*60.day.*inactiv|60.day.*no.*activity.*workflow'
+    flags: "i"
+error_messages:
+  - "This scheduled workflow is disabled because there has been no repository activity in the past 60 days"
+root_cause: |
+  GitHub automatically disables on: schedule workflows in repositories that have had no
+  activity (pushes, pull requests, merges) for 60 days. This is a platform resource
+  management decision to reduce compute on dormant repositories.
+
+  When triggered, the Actions tab displays a banner:
+  "This scheduled workflow is disabled because there has been no repository activity
+  in the past 60 days."
+
+  GitHub sends a notification email before disabling, but many maintainers miss it.
+
+  Common affected scenarios:
+  - Maintenance repos (dependency update jobs, reporting pipelines) with infrequent code changes
+  - Scheduled audit or monitoring workflows in stable, rarely-pushed codebases
+  - Open source repos that go quiet between releases
+  - Returning after extended leave to find weeks or months of scheduled runs silently missed
+
+  There is no workflow-level setting to prevent automatic disabling. The only remedies
+  are to manually re-enable via the GitHub UI or maintain repository activity artificially.
+fix: |
+  To re-enable a disabled scheduled workflow:
+  1. Navigate to the repository Actions tab
+  2. Select the disabled workflow in the left sidebar
+  3. Click the "Enable workflow" button shown in the banner
+
+  To prevent future auto-disabling, add a keep-alive workflow that creates an empty
+  commit on a schedule shorter than 60 days. Using stefanzweifel/git-auto-commit-action
+  with --allow-empty avoids modifying tracked files while still generating commit activity
+  that resets the 60-day counter.
+
+  There is no REST API endpoint to re-enable disabled scheduled workflows — it must be
+  done via the GitHub UI or by pushing a new commit to the repository.
+fix_code:
+  - language: yaml
+    label: "Keep-alive workflow — runs monthly to prevent schedule auto-disable"
+    code: |
+      # .github/workflows/keep-alive.yml
+      name: Keep Alive
+
+      on:
+        schedule:
+          - cron: '0 0 1 * *'    # First of each month — well within 60-day window
+        workflow_dispatch:
+
+      jobs:
+        keep-alive:
+          runs-on: ubuntu-latest
+          permissions:
+            contents: write
+          steps:
+            - uses: actions/checkout@v4
+
+            - name: Maintain repository activity
+              uses: stefanzweifel/git-auto-commit-action@v5
+              with:
+                commit_message: 'chore: keep-alive [skip ci]'
+                commit_options: '--allow-empty'
+prevention:
+  - "Monitor the Actions tab for the 60-day inactivity warning banner"
+  - "Add a keep-alive workflow to all repos with important scheduled jobs but infrequent commits"
+  - "Subscribe to GitHub notification emails so the pre-disable warning is not missed"
+  - "Document this limitation in the repo CONTRIBUTING guide for future maintainers"
+docs:
+  - url: "https://docs.github.com/en/actions/writing-workflows/choosing-when-your-workflow-runs/events-that-trigger-workflows#schedule"
+    label: "GitHub Docs: schedule trigger"
+  - url: "https://github.com/orgs/community/discussions/5614"
+    label: "GitHub Community #5614: Scheduled workflow disabled after 60 days of inactivity"
+  - url: "https://github.com/stefanzweifel/git-auto-commit-action"
+    label: "stefanzweifel/git-auto-commit-action — keep-alive commit pattern"

package/errors/runner-environment/runner-environment-100.yml

@@ -0,0 +1,69 @@
+id: runner-environment-100
+title: "ubuntu-24.04 libmysqlclient-dev renamed to default-libmysqlclient-dev — apt install fails"
+category: runner-environment
+severity: error
+tags:
+  - ubuntu-24.04
+  - apt
+  - mysql
+  - libmysqlclient
+  - migration
+  - package-rename
+patterns:
+  - regex: 'Package .libmysqlclient-dev. has no installation candidate'
+    flags: "i"
+  - regex: 'Unable to locate package openjdk-8|libmysqlclient-dev.*no installation'
+    flags: "i"
+error_messages:
+  - "E: Package 'libmysqlclient-dev' has no installation candidate"
+  - "Package 'libmysqlclient-dev' has no installation candidate"
+root_cause: |
+  In Ubuntu 24.04 (Noble Numbat), the libmysqlclient-dev package was removed from
+  the default apt repositories. MySQL 8.x development headers are now provided by
+  default-libmysqlclient-dev (a metapackage resolving to MySQL or MariaDB headers)
+  or the MariaDB-specific libmariadb-dev. Workflows migrating from ubuntu-22.04
+  (which carried libmysqlclient-dev) to ubuntu-24.04 fail at the apt-get install
+  step. This affects Django (mysqlclient), Ruby on Rails (mysql2 gem), PHP (mysqli
+  extension compile), and Go applications using CGO MySQL bindings.
+fix: |
+  Replace libmysqlclient-dev with default-libmysqlclient-dev, which resolves to
+  the correct MySQL or MariaDB dev headers on Ubuntu 22.04 and 24.04. For projects
+  strictly requiring Oracle MySQL headers, add the official MySQL APT repository
+  before installing.
+fix_code:
+  - language: yaml
+    label: "Replace libmysqlclient-dev with default-libmysqlclient-dev"
+    code: |
+      - name: Install MySQL development headers
+        run: |
+          sudo apt-get update
+          # libmysqlclient-dev removed in Ubuntu 24.04 — use default-libmysqlclient-dev
+          sudo apt-get install -y default-libmysqlclient-dev
+  - language: yaml
+    label: "Alternative: MariaDB headers explicitly"
+    code: |
+      - name: Install MariaDB development headers
+        run: |
+          sudo apt-get update
+          sudo apt-get install -y libmariadb-dev pkg-config
+  - language: yaml
+    label: "Alternative: Oracle MySQL APT repo for strict MySQL requirement"
+    code: |
+      - name: Add Oracle MySQL APT repository
+        run: |
+          wget https://dev.mysql.com/get/mysql-apt-config_0.8.33-1_all.deb
+          sudo dpkg -i mysql-apt-config_0.8.33-1_all.deb
+          sudo apt-get update
+          sudo apt-get install -y libmysqlclient-dev
+prevention:
+  - "Grep workflow files for libmysqlclient-dev before migrating from ubuntu-22.04 to ubuntu-24.04"
+  - "Use default-libmysqlclient-dev in all new workflows — it works on both Ubuntu 22.04 and 24.04"
+  - "Pin MySQL client library versions in requirements.txt or Gemfile rather than relying on system headers"
+  - "Add an ubuntu-24.04 job to the matrix before retiring ubuntu-22.04 to catch apt package renames early"
+docs:
+  - url: "https://packages.ubuntu.com/noble/default-libmysqlclient-dev"
+    label: "Ubuntu Noble: default-libmysqlclient-dev"
+  - url: "https://dev.mysql.com/doc/refman/8.0/en/linux-installation-apt-repo.html"
+    label: "MySQL APT Repository Guide"
+  - url: "https://github.com/actions/runner-images/issues/9932"
+    label: "runner-images #9932: Ubuntu 24.04 MySQL package rename"

package/errors/runner-environment/runner-environment-101.yml

@@ -0,0 +1,73 @@
+id: runner-environment-101
+title: "ubuntu-24.04 openjdk-8-jdk unavailable via apt — must use actions/setup-java"
+category: runner-environment
+severity: error
+tags:
+  - ubuntu-24.04
+  - java
+  - openjdk
+  - apt
+  - migration
+  - jdk8
+patterns:
+  - regex: 'Package .openjdk-8-(jdk|jre|jre-headless). has no installation candidate'
+    flags: "i"
+  - regex: 'Unable to locate package openjdk-8'
+    flags: "i"
+error_messages:
+  - "E: Package 'openjdk-8-jdk' has no installation candidate"
+  - "E: Unable to locate package openjdk-8-jdk"
+  - "E: Package 'openjdk-8-jre-headless' has no installation candidate"
+root_cause: |
+  Ubuntu 24.04 (Noble) dropped OpenJDK 8 from its official apt repositories because
+  OpenJDK 8 reached end-of-life upstream. Workflows that install Java via
+  apt-get install -y openjdk-8-jdk succeed on ubuntu-22.04 but fail immediately on
+  ubuntu-24.04 with "no installation candidate". Common affected scenarios include:
+
+  - Legacy Android builds requiring Java 8 compile target
+  - Apache Ant or Maven builds with a Java 8 minimum
+  - Older Spring Boot projects targeting Java 8
+  - Workflows that manually set JAVA_HOME after apt-get install
+
+  The actions/setup-java action with the temurin distribution still supports Java 8
+  and is the recommended cross-platform replacement.
+fix: |
+  Replace apt-get install openjdk-8-jdk with actions/setup-java using the temurin
+  (Eclipse Adoptium, formerly AdoptOpenJDK) distribution. This resolves correctly
+  on ubuntu-22.04, ubuntu-24.04, macOS, and Windows runners. Migrate to Java 11 or
+  17 LTS if the project allows — Java 8 is past end-of-life.
+fix_code:
+  - language: yaml
+    label: "Replace apt install with actions/setup-java for JDK 8"
+    code: |
+      - name: Set up Java 8
+        uses: actions/setup-java@v4
+        with:
+          distribution: temurin   # Eclipse Adoptium (formerly AdoptOpenJDK)
+          java-version: '8'
+          # Prefer java-version: '17' or '21' where the project allows
+  - language: yaml
+    label: "Matrix: test multiple Java versions"
+    code: |
+      strategy:
+        matrix:
+          java: ['8', '11', '17', '21']
+      steps:
+        - uses: actions/setup-java@v4
+          with:
+            distribution: temurin
+            java-version: ${{ matrix.java }}
+prevention:
+  - "Prefer actions/setup-java over apt-get for Java in all workflows — explicit version pinning works cross-platform"
+  - "Upgrade to Java 11 or 17 LTS where feasible — Java 8 is EOL"
+  - "Search workflow files for openjdk-8 before migrating the runner label to ubuntu-24.04"
+  - "Use distribution: zulu as an alternative Azul OpenJDK distribution if Temurin is not suitable"
+docs:
+  - url: "https://github.com/actions/setup-java"
+    label: "actions/setup-java — supported distributions and versions"
+  - url: "https://adoptium.net/temurin/releases/?version=8"
+    label: "Eclipse Temurin Java 8 Releases"
+  - url: "https://packages.ubuntu.com/search?keywords=openjdk-8"
+    label: "Ubuntu Package Search: openjdk-8 availability"
+  - url: "https://github.com/actions/runner-images/issues/9848"
+    label: "runner-images #9848: openjdk-8 missing on Ubuntu 24.04"

package/errors/runner-environment/runner-environment-102.yml

@@ -0,0 +1,89 @@
+id: runner-environment-102
+title: "macOS 14+ xcrun altool removed — notarization workflows fail with 'unable to find utility'"
+category: runner-environment
+severity: error
+tags:
+  - macos
+  - xcode
+  - notarization
+  - altool
+  - notarytool
+  - codesign
+  - migration
+patterns:
+  - regex: 'xcrun: error: unable to find utility .altool.'
+    flags: "i"
+  - regex: 'altool.*has been deprecated and is no longer supported|unable to find utility .altool.'
+    flags: "i"
+error_messages:
+  - "xcrun: error: unable to find utility \"altool\", not a developer tool or in PATH"
+  - "altool has been deprecated and is no longer supported"
+root_cause: |
+  xcrun altool was Apple's original notarization CLI tool. Apple deprecated it in
+  Xcode 13 (WWDC 2021) and removed it entirely in Xcode 15 (September 2023).
+  GitHub's macOS 14, macOS 15, and macOS 26 runners ship Xcode 15 or later, so
+  altool is not present on these runners.
+
+  Workflows that use any of the following commands fail immediately on macos-14+:
+    xcrun altool --notarize-app ...
+    xcrun altool --notarization-info ...
+    xcrun altool --staple-archive ...
+    xcrun altool --notarization-history ...
+
+  This is a runner image migration break: workflows working on macos-12 or macos-13
+  (Xcode 14) silently stop working when the runner label switches to macos-14 or
+  macos-latest, which ships Xcode 15+. The failure is loud (non-zero exit from
+  xcrun) but easy to miss if teams assume the mac runner version did not change.
+fix: |
+  Migrate to xcrun notarytool, the replacement for altool since Xcode 13. Notarytool
+  accepts the same Apple ID + app-specific password credentials or the more secure
+  App Store Connect API key (recommended for CI — avoids 2FA issues). Submissions
+  complete synchronously with --wait, replacing the polling loop previously required
+  by altool.
+fix_code:
+  - language: yaml
+    label: "Migrate from altool to notarytool (Apple ID auth)"
+    code: |
+      - name: Notarize app
+        env:
+          APPLE_ID: ${{ secrets.APPLE_ID }}
+          APPLE_PASSWORD: ${{ secrets.APPLE_APP_SPECIFIC_PASSWORD }}
+          TEAM_ID: ${{ secrets.APPLE_TEAM_ID }}
+        run: |
+          xcrun notarytool submit MyApp.zip \
+            --apple-id "$APPLE_ID" \
+            --password "$APPLE_PASSWORD" \
+            --team-id "$TEAM_ID" \
+            --wait
+
+      - name: Staple notarization ticket
+        run: xcrun stapler staple MyApp.app
+  - language: yaml
+    label: "Preferred: App Store Connect API key auth (no 2FA issues)"
+    code: |
+      - name: Notarize with App Store Connect API key
+        env:
+          API_KEY_ID: ${{ secrets.AC_API_KEY_ID }}
+          API_KEY_ISSUER: ${{ secrets.AC_API_KEY_ISSUER }}
+          API_KEY_PATH: /tmp/AuthKey.p8
+        run: |
+          printf '%s' "${{ secrets.AC_API_KEY }}" > "$API_KEY_PATH"
+          xcrun notarytool submit MyApp.zip \
+            --key "$API_KEY_PATH" \
+            --key-id "$API_KEY_ID" \
+            --issuer "$API_KEY_ISSUER" \
+            --wait
+prevention:
+  - "Migrate all xcrun altool commands to xcrun notarytool — altool is gone on any Xcode 15+ runner"
+  - "Prefer App Store Connect API key authentication in CI — avoids 2FA prompts and app-specific password rotation"
+  - "Search workflow files for altool before updating the macos runner label from macos-13 to macos-14 or macos-latest"
+  - "Test notarization on macos-14 alongside macos-13 before fully retiring the older runner label"
+docs:
+  - url: "https://developer.apple.com/documentation/notaryapi"
+    label: "Apple: Notary API (notarytool)"
+  - url: "https://developer.apple.com/news/releases/xcode-15-release-notes/"
+    label: "Xcode 15 Release Notes — altool removal"
+  - url: "https://developer.apple.com/documentation/security/notarizing-macos-software-before-distribution/customizing-the-notarization-workflow"
+    label: "Apple: Customizing the notarization workflow"
+  - url: "https://github.com/actions/runner-images/discussions/7505"
+    label: "runner-images: macOS 14 Xcode 15 notarization migration"

package/errors/silent-failures/silent-failures-050.yml

@@ -0,0 +1,93 @@
+id: silent-failures-050
+title: "continue-on-error: true on a failing step silently prevents if: failure() downstream steps from running"
+category: silent-failures
+severity: silent-failure
+tags:
+  - continue-on-error
+  - if-condition
+  - failure-check
+  - step-outcome
+  - silent-skip
+  - cleanup
+patterns:
+  - regex: 'continue.on.error.*if.*failure|if.*failure.*not.*running.*continue.on.error'
+    flags: "i"
+  - regex: 'cleanup.*step.*skipped.*continue.on.error|failure.*handler.*not.*triggered'
+    flags: "i"
+error_messages:
+  - "Downstream step with if: failure() silently skipped when preceding step uses continue-on-error: true"
+root_cause: |
+  When a step fails AND has continue-on-error: true, GitHub Actions marks that step's
+  conclusion as success (the error was absorbed) while preserving its outcome as failure.
+  Because the step conclusion is success, the job's overall result remains success.
+
+  Any downstream step or job conditioned on if: failure() evaluates the job's overall
+  status, not individual step outcomes. Since the job is still succeeding (the failure was
+  continued past), if: failure() evaluates to false — and those downstream steps are
+  silently skipped with no error or warning.
+
+  The pattern developers expect to work (but doesn't):
+
+    steps:
+      - name: Run tests
+        run: npm test
+        continue-on-error: true
+      - name: Upload failure report   # NEVER runs — job outcome is still 'success'
+        if: failure()
+
+  Silently broken patterns:
+  - Failure notification steps after continue-on-error test or lint steps
+  - Cleanup steps conditioned on job failure after a continued-on-error build
+  - Report upload or artifact save steps expected to fire when tests fail
+  - Alerting steps (Slack, PagerDuty) conditioned on failure() after a tolerated failure
+fix: |
+  Reference the specific failing step's outcome directly using steps.<id>.outcome
+  instead of the job-level failure() function. Give the step-with-continue-on-error an
+  explicit id: field, then condition the downstream step on
+  steps.<step-id>.outcome == 'failure'.
+
+  This correctly captures the step-level failure even when the job overall is succeeding.
+fix_code:
+  - language: yaml
+    label: "Wrong: if: failure() silently never fires after a continue-on-error step"
+    code: |
+      steps:
+        - name: Run tests
+          run: npm test
+          continue-on-error: true
+          # Job outcome stays 'success' — if: failure() below never executes
+
+        - name: Upload test failure report
+          if: failure()
+          uses: actions/upload-artifact@v4
+          with:
+            name: test-report
+            path: test-results/
+  - language: yaml
+    label: "Correct: check the specific step outcome to catch the continued failure"
+    code: |
+      steps:
+        - name: Run tests
+          id: run-tests           # Explicit ID required to reference outcome below
+          run: npm test
+          continue-on-error: true
+
+        - name: Upload test failure report
+          # Fires when tests failed — works correctly even though the job is still 'success'
+          if: steps.run-tests.outcome == 'failure'
+          uses: actions/upload-artifact@v4
+          with:
+            name: test-report
+            path: test-results/
+prevention:
+  - "Never rely on if: failure() to detect failures from steps that use continue-on-error: true"
+  - "Assign explicit id: to any step with continue-on-error that needs downstream conditional checks"
+  - "Use steps.<id>.outcome == 'failure' to condition steps on a specific earlier step's result"
+  - "Test failure-handler steps explicitly by temporarily forcing the upstream step to fail without continue-on-error"
+docs:
+  - url: "https://docs.github.com/en/actions/writing-workflows/choosing-what-your-workflow-does/using-conditions-to-control-job-execution"
+    label: "GitHub Docs: Using conditions to control job execution"
+  - url: "https://docs.github.com/en/actions/writing-workflows/choosing-what-your-workflow-does/accessing-contextual-information-about-workflow-runs#steps-context"
+    label: "GitHub Docs: steps context — outcome vs conclusion"
+  - url: "https://github.com/orgs/community/discussions/25420"
+    label: "GitHub Community: continue-on-error and if: failure() interaction explained"

package/errors/triggers/triggers-033.yml

@@ -0,0 +1,100 @@
+id: triggers-033
+title: "Commits, PRs, and releases created using GITHUB_TOKEN do not trigger new workflow runs"
+category: triggers
+severity: limitation
+tags:
+  - GITHUB_TOKEN
+  - loopback-prevention
+  - push-event
+  - pull-request
+  - no-trigger
+  - known-limitation
+patterns:
+  - regex: 'GITHUB_TOKEN.*push.*not.*trigger|workflow.*not.*triggered.*after.*commit'
+    flags: "i"
+  - regex: 'auto.commit.*no.*workflow|push.*token.*not.*firing.*CI'
+    flags: "i"
+error_messages:
+  - "Workflow not triggered after automated push using GITHUB_TOKEN"
+root_cause: |
+  GitHub Actions intentionally prevents new workflow runs from being triggered by events
+  performed with the built-in GITHUB_TOKEN. This loopback prevention exists to stop
+  accidental or malicious infinite workflow loops — for example, a push workflow that
+  commits back to the repo and re-triggers itself in perpetuity.
+
+  Affected operations when performed with GITHUB_TOKEN:
+  - Pushing a commit to a branch (no push event fired; CI does not run on the new SHA)
+  - Creating a pull request via REST API (no pull_request event fired; PR checks do not start)
+  - Publishing a release (no release event fired)
+  - Merging a PR programmatically (no push or pull_request closed event fired)
+
+  Common surprise scenarios:
+  - Auto-version-bump workflows that commit package.json and expect CI to run on the result
+  - Automated changelog commits that should trigger a docs publish pipeline
+  - Bots that open PRs using GITHUB_TOKEN expecting branch protection checks to start
+  - Tag-from-workflow jobs expecting the resulting tag push to start a release pipeline
+fix: |
+  To trigger new workflow runs from operations performed inside a workflow, use a Personal
+  Access Token (PAT) or a GitHub App installation token instead of GITHUB_TOKEN. Events
+  created with these tokens are not subject to the loopback prevention rule.
+
+  For organizational workflows, GitHub App tokens are the recommended approach — they
+  do not rely on a personal user's credentials and can be scoped to minimum permissions.
+
+  If triggering new runs is NOT needed, add [skip ci] to the commit message to make the
+  intent explicit and prevent accidental CI consumption if a PAT is used later.
+fix_code:
+  - language: yaml
+    label: "PAT-based checkout so the resulting push triggers downstream CI"
+    code: |
+      jobs:
+        version-bump:
+          runs-on: ubuntu-latest
+          steps:
+            # Check out with PAT — any subsequent push WILL trigger a new push workflow run
+            - uses: actions/checkout@v4
+              with:
+                token: ${{ secrets.MY_PAT }}
+
+            - name: Bump version
+              run: npm version patch --no-git-tag-version
+
+            - name: Commit and push version bump
+              uses: stefanzweifel/git-auto-commit-action@v5
+              with:
+                commit_message: 'chore: bump version'
+  - language: yaml
+    label: "GitHub App token so an auto-created PR triggers branch protection checks"
+    code: |
+      jobs:
+        create-pr:
+          runs-on: ubuntu-latest
+          steps:
+            - name: Get GitHub App token
+              id: app-token
+              uses: actions/create-github-app-token@v1
+              with:
+                app-id: ${{ secrets.APP_ID }}
+                private-key: ${{ secrets.APP_PRIVATE_KEY }}
+
+            - uses: actions/checkout@v4
+              with:
+                token: ${{ steps.app-token.outputs.token }}
+
+            - name: Create PR — App token causes PR checks to be triggered
+              uses: peter-evans/create-pull-request@v6
+              with:
+                token: ${{ steps.app-token.outputs.token }}
+                title: 'chore: automated update'
+prevention:
+  - "Use a PAT or GitHub App token when downstream workflow runs must be triggered by a commit or PR"
+  - "Add [skip ci] to auto-commit messages when downstream CI triggering is explicitly NOT needed"
+  - "Document in workflow comments why PAT or App token is used instead of GITHUB_TOKEN"
+  - "When debugging missing CI runs after automated commits, check whether GITHUB_TOKEN loopback prevention applies"
+docs:
+  - url: "https://docs.github.com/en/actions/security-for-github-actions/security-guides/automatic-token-authentication#using-the-github_token-in-a-workflow"
+    label: "GitHub Docs: Automatic token authentication — events triggered by GITHUB_TOKEN"
+  - url: "https://github.com/orgs/community/discussions/27072"
+    label: "GitHub Community: Push with GITHUB_TOKEN does not trigger new workflow runs"
+  - url: "https://docs.github.com/en/apps/creating-github-apps/authenticating-with-a-github-app/making-authenticated-api-requests-with-a-github-app-in-a-github-actions-workflow"
+    label: "GitHub Docs: Using a GitHub App token in Actions workflows"

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@htekdev/actions-debugger",
-  "version": "1.0.44",
+  "version": "1.0.46",
   "description": "65+ real GitHub Actions errors, queryable by agents. CLI + MCP server + Copilot skills + error database.",
   "type": "module",
   "main": "./dist/index.js",