@htekdev/actions-debugger 1.0.124 → 1.0.126

package/errors/triggers/triggers-072.yml

@@ -0,0 +1,150 @@
+id: triggers-072
+title: 'Scheduled workflow silently disabled after 60 days of public repository inactivity — distinct from the fork schedule disabling rule'
+category: triggers
+severity: silent-failure
+tags:
+  - schedule
+  - cron
+  - disabled
+  - inactivity
+  - public-repo
+  - silent-disable
+  - 60-days
+patterns:
+  - regex: 'on:\s*\n\s+schedule:'
+    flags: 'im'
+  - regex: 'This workflow was disabled'
+    flags: 'i'
+  - regex: 'Workflow.*disabled.*inactiv'
+    flags: 'i'
+error_messages:
+  - "This workflow was disabled."
+  - "Scheduled workflows are disabled for repositories with no recent activity."
+root_cause: |
+  GitHub automatically disables scheduled (`on: schedule:`) workflows in **public
+  repositories** that have had no activity for more than **60 days**. "Activity"
+  includes pushes, pull requests, issue comments, or other events that generate
+  a repository event payload. Pure time-passing without any interaction does not
+  reset the timer.
+
+  The disabling happens silently:
+  - No email notification is sent to repository owners or workflow authors.
+  - No GitHub notification appears in the repository's notification feed.
+  - The scheduled run simply does not appear in the Actions run history.
+  - The workflow file is not changed — the `on: schedule:` trigger is still present
+    in the YAML, but the schedule is inactive in GitHub's internal scheduler.
+
+  The Actions tab will show the workflow listed but with a note that it has been
+  disabled. The **"Enable workflow"** button must be clicked manually to re-activate it.
+
+  This behavior is separate from the fork schedule-disabling rule (where ALL
+  scheduled workflows are disabled on forked repos regardless of activity). The
+  inactivity rule applies to non-fork public repositories.
+
+  Common scenarios:
+  - Maintenance scripts (e.g., weekly dependency updates, cleanup jobs) in repos
+    that receive no push activity between runs.
+  - Documentation or static-site repos where content is rarely updated but a nightly
+    build/deploy workflow is expected to run.
+  - Monitoring or alerting workflows in repos with no other CI triggers.
+  - Open-source libraries with stable codebases and monthly or quarterly releases.
+fix: |
+  **Immediate fix:** Navigate to the repository → Actions tab → find the disabled
+  workflow → click "Enable workflow."
+
+  **Prevent future silent disabling — Option 1 (Recommended): Add a dummy commit
+  or workflow_dispatch trigger:**
+  Add `workflow_dispatch:` to the workflow so it can be triggered manually and also
+  resets the inactivity timer. Then use `gh workflow run` or the UI to manually
+  trigger it if needed.
+
+  **Prevent future silent disabling — Option 2: Artificially keep the repo active:**
+  Add a companion workflow that runs on schedule and updates a file (e.g., a
+  `last-run.txt` with the current timestamp) via a commit. This creates repository
+  activity and resets the 60-day timer. Warning: this generates commit noise.
+
+  **Prevent future silent disabling — Option 3: Convert to a self-hosted or
+  external scheduler:**
+  Use an external cron service (e.g., a cron job in a cloud provider) to trigger
+  the workflow via `workflow_dispatch` or `repository_dispatch`. External triggers
+  count as activity and keep the workflow enabled.
+
+  **Long-term design:** For workflows that are truly meant to run on a schedule
+  without any other repo activity, always add `workflow_dispatch:` as a co-trigger.
+  This makes the workflow manually invocable AND provides a path to re-enable it if
+  it is ever silently disabled.
+fix_code:
+  - language: yaml
+    label: 'At-risk — schedule-only workflow in a low-activity public repo'
+    code: |
+      # ⚠ This workflow will be silently disabled after 60 days with no repo activity
+      name: Weekly Dependency Update
+
+      on:
+        schedule:
+          - cron: '0 9 * * 1'   # Every Monday at 09:00 UTC
+
+      jobs:
+        update:
+          runs-on: ubuntu-latest
+          steps:
+            - uses: actions/checkout@v4
+            - run: npm update && npm audit fix
+
+  - language: yaml
+    label: 'Fixed — add workflow_dispatch to keep the workflow manageable and prevent inactivity disable'
+    code: |
+      name: Weekly Dependency Update
+
+      on:
+        schedule:
+          - cron: '0 9 * * 1'   # Every Monday at 09:00 UTC
+        workflow_dispatch:       # ✅ Allows manual trigger; manual runs also reset the inactivity timer
+
+      jobs:
+        update:
+          runs-on: ubuntu-latest
+          steps:
+            - uses: actions/checkout@v4
+            - run: npm update && npm audit fix
+
+  - language: yaml
+    label: 'Alternative — heartbeat workflow that commits a timestamp to keep the repo active'
+    code: |
+      name: Activity Heartbeat (prevents schedule auto-disable)
+
+      on:
+        schedule:
+          - cron: '0 0 * * 0'   # Every Sunday midnight UTC — reset 60-day timer
+        workflow_dispatch:
+
+      permissions:
+        contents: write
+
+      jobs:
+        heartbeat:
+          runs-on: ubuntu-latest
+          steps:
+            - uses: actions/checkout@v4
+            - name: Update heartbeat timestamp
+              run: |
+                echo "$(date -u +%Y-%m-%dT%H:%M:%SZ)" > .github/heartbeat.txt
+                git config user.name 'github-actions[bot]'
+                git config user.email '41898282+github-actions[bot]@users.noreply.github.com'
+                git add .github/heartbeat.txt
+                git diff --staged --quiet || git commit -m 'chore: activity heartbeat [skip ci]'
+                git push
+
+prevention:
+  - 'Always add `workflow_dispatch:` alongside `on: schedule:` for any workflow that should run reliably in a low-activity repo.'
+  - 'Check the Actions tab after a period of low repository activity to verify scheduled workflows are still enabled.'
+  - 'The 60-day inactivity rule applies to non-fork public repositories — private repos are NOT subject to this rule.'
+  - 'This is distinct from the fork schedule-disabling rule: forks disable schedules immediately on fork creation, not after inactivity.'
+  - 'Set up a GitHub Actions alert or monitoring workflow that notifies you if expected scheduled runs stop appearing.'
+docs:
+  - url: 'https://docs.github.com/en/actions/writing-workflows/choosing-when-your-workflow-runs/events-that-trigger-workflows#schedule'
+    label: 'GitHub Docs: Events that trigger workflows — schedule (inactivity disable note)'
+  - url: 'https://docs.github.com/en/actions/managing-workflow-runs-and-deployments/managing-workflow-runs/disabling-and-enabling-a-workflow'
+    label: 'GitHub Docs: Disabling and enabling a workflow'
+  - url: 'https://github.com/orgs/community/discussions/134086'
+    label: 'GitHub Community #134086: Scheduled workflows not running — inactivity disable reports'

package/errors/yaml-syntax/yaml-syntax-075.yml

@@ -0,0 +1,128 @@
+id: yaml-syntax-075
+title: 'environment: shorthand string format silently rejects needs.* and jobs.* contexts — use environment.name form'
+category: yaml-syntax
+severity: error
+tags:
+  - environment
+  - dynamic-environment
+  - needs-context
+  - expression
+  - shorthand
+  - template-validation
+patterns:
+  - regex: 'Unrecognized named-value.*needs.*environment'
+    flags: 'i'
+  - regex: "Unrecognized named-value: 'needs'.*position.*expression.*needs\\."
+    flags: 'i'
+  - regex: 'TemplateValidationException.*Unrecognized named-value.*needs'
+    flags: 'i'
+error_messages:
+  - "The workflow is not valid. .github/workflows/deploy.yml (Line: 15, Col: 18): Unrecognized named-value: 'needs'. Located at position 1 within expression: needs.set_environment.outputs.my_env"
+  - "Unrecognized named-value: 'needs'. Located at position 1 within expression: needs.X.outputs.env"
+root_cause: |
+  The GitHub Actions workflow parser supports two forms for specifying a job environment:
+
+  1. Shorthand string: `environment: production` or `environment: ${{ some.expression }}`
+  2. Explicit mapping: `environment:\n  name: ${{ expression }}\n  url: ${{ expression }}`
+
+  The shorthand string form (`environment: ${{ ... }}`) supports only a limited expression
+  context and does NOT support the `needs.*` or `jobs.*` contexts, even when the job
+  has `needs:` declared. Attempting to use `needs.X.outputs.Y` inside the shorthand
+  produces a TemplateValidationException at workflow parse time:
+
+    "Unrecognized named-value: 'needs'. Located at position 1 within expression: needs.X.outputs.Y"
+
+  The explicit mapping form (`environment:\n  name: ${{ ... }}`) DOES support the `needs.*`
+  context fully — this is the documented way to set a dynamic environment name or URL.
+
+  This trips up developers who:
+  - Copy the shorthand form from documentation examples and add an expression.
+  - Want to choose between staging/production environments based on the branch output
+    of an earlier job.
+  - Try to set a dynamic environment URL using `needs.deploy.outputs.url`.
+
+  The error appears only at workflow validation time (not at job runtime), which means
+  the entire workflow is rejected before any jobs run.
+fix: |
+  Use the explicit `environment:` mapping format with `name:` and optionally `url:` sub-keys
+  instead of the shorthand string with a `${{ }}` expression.
+
+  The shorthand `environment: ${{ expression }}` is only for literal strings or simple
+  expressions without `needs.*` / `jobs.*`. Once you need cross-job outputs, switch to
+  the explicit form.
+fix_code:
+  - language: yaml
+    label: 'Broken — shorthand with needs.* context causes TemplateValidationException'
+    code: |
+      jobs:
+        determine-env:
+          runs-on: ubuntu-latest
+          outputs:
+            target: ${{ steps.pick.outputs.env }}
+          steps:
+            - id: pick
+              run: echo "env=production" >> $GITHUB_OUTPUT
+
+        deploy:
+          needs: determine-env
+          runs-on: ubuntu-latest
+          # ❌ BROKEN: shorthand does not support needs.* context
+          environment: ${{ needs.determine-env.outputs.target }}
+          steps:
+            - run: echo "deploying"
+
+  - language: yaml
+    label: 'Fixed — explicit environment.name form supports needs.* context'
+    code: |
+      jobs:
+        determine-env:
+          runs-on: ubuntu-latest
+          outputs:
+            target: ${{ steps.pick.outputs.env }}
+          steps:
+            - id: pick
+              run: |
+                if [[ "${{ github.ref_name }}" == "main" ]]; then
+                  echo "env=production" >> $GITHUB_OUTPUT
+                else
+                  echo "env=staging" >> $GITHUB_OUTPUT
+                fi
+
+        deploy:
+          needs: determine-env
+          runs-on: ubuntu-latest
+          # ✅ FIXED: explicit name: sub-key supports needs.* context
+          environment:
+            name: ${{ needs.determine-env.outputs.target }}
+            url: ${{ needs.deploy.outputs.deploy_url }}
+          steps:
+            - run: echo "deploying to ${{ needs.determine-env.outputs.target }}"
+
+  - language: yaml
+    label: 'Dynamic environment from workflow_dispatch input — correct form'
+    code: |
+      on:
+        workflow_dispatch:
+          inputs:
+            environment:
+              required: true
+              type: environment
+      jobs:
+        deploy:
+          runs-on: ubuntu-latest
+          # ✅ Use explicit name: when referencing inputs.* or needs.* contexts
+          environment:
+            name: ${{ inputs.environment }}
+          steps:
+            - run: echo "deploying to ${{ inputs.environment }}"
+prevention:
+  - 'Always use the `environment:\n  name: ${{ }}` form (never the shorthand string) when the environment name is dynamic or derived from another job.'
+  - 'Remember: `environment: ${{ expression }}` is valid syntax but only for literal strings — it silently ignores `needs.*` context at parse time, producing a hard error.'
+  - 'Lint with actionlint (v1.7.0+) which detects this pattern before pushing.'
+docs:
+  - url: 'https://github.com/actions/runner/issues/998'
+    label: 'actions/runner#998 — Setting job environment dynamically fails with needs context in shorthand form'
+  - url: 'https://docs.github.com/en/actions/using-workflows/workflow-syntax-for-github-actions#jobsjob_idenvironment'
+    label: 'GitHub Docs — jobs.<job_id>.environment syntax reference'
+  - url: 'https://stackoverflow.com/questions/65826284/use-dynamic-input-value-for-environment-in-github-actions-workflow-job'
+    label: 'Stack Overflow — Dynamic environment in GitHub Actions workflow job (many upvotes)'

package/errors/yaml-syntax/yaml-syntax-076.yml

@@ -0,0 +1,107 @@
+id: yaml-syntax-076
+title: 'actionlint <=1.7.7 rejects valid `entrypoint` and `command` keys on service containers — schema lag after April 2026 GitHub changelog'
+category: yaml-syntax
+severity: error
+tags:
+  - actionlint
+  - service-container
+  - entrypoint
+  - command
+  - schema-lag
+  - linting
+  - CI-check
+patterns:
+  - regex: 'unexpected key "entrypoint" for "services" section'
+    flags: 'i'
+  - regex: 'unexpected key "command" for "services" section'
+    flags: 'i'
+  - regex: 'unexpected key "(?:entrypoint|command)" for "services" section\. expected one of "credentials", "env", "image", "options", "ports", "volumes"'
+    flags: 'i'
+error_messages:
+  - '.github/workflows/test.yaml:9:9: unexpected key "entrypoint" for "services" section. expected one of "credentials", "env", "image", "options", "ports", "volumes" [syntax-check]'
+  - '.github/workflows/test.yaml:10:9: unexpected key "command" for "services" section. expected one of "credentials", "env", "image", "options", "ports", "volumes" [syntax-check]'
+root_cause: |
+  GitHub Actions added support for `entrypoint` and `command` keys on service container
+  definitions on April 2, 2026 (GitHub Actions: Early April 2026 updates changelog). These
+  new keys allow overriding the service container's default entrypoint and command directly from
+  workflow YAML, matching Docker Compose semantics:
+
+  ```yaml
+  services:
+    redis:
+      image: redis
+      entrypoint: redis-server
+      command: --save 60 1 --loglevel warning
+  ```
+
+  actionlint versions <=1.7.7 validate service container keys against a hardcoded schema that
+  only permits `credentials`, `env`, `image`, `options`, `ports`, and `volumes`. When a workflow
+  uses the new `entrypoint` or `command` keys, actionlint reports them as unknown properties with
+  a `[syntax-check]` error.
+
+  This causes CI pipelines that run actionlint as a lint check to fail even though the workflow
+  is perfectly valid on GitHub.com. The fix was merged into actionlint on April 19, 2026 and
+  released in v1.7.8.
+
+  This is a schema-lag pattern: a new GitHub Actions feature was released before the static
+  analysis tool's schema was updated to recognize it, causing a false-positive lint failure.
+fix: |
+  **Primary fix: Upgrade actionlint to >=1.7.8.**
+  The fix was merged April 19, 2026 (rhysd/actionlint#644). Update your CI pipeline to use
+  actionlint >=1.7.8:
+
+  ```yaml
+  - name: Run actionlint
+    uses: raven-actions/actionlint@v2
+    with:
+      version: latest  # or pin to 1.7.8+
+  ```
+
+  **Temporary workaround (if upgrading is not immediately possible):** Add an inline ignore
+  comment to suppress the false-positive while on the older actionlint version:
+
+  ```yaml
+  services:
+    redis:
+      image: redis
+      entrypoint: redis-server  # actionlint:ignore
+      command: --save 60 1      # actionlint:ignore
+  ```
+fix_code:
+  - language: yaml
+    label: 'Upgrade actionlint in CI to >=1.7.8 to recognize entrypoint/command service keys'
+    code: |
+      - name: Run actionlint
+        uses: raven-actions/actionlint@v2
+        with:
+          version: 1.7.8  # Minimum version that supports entrypoint/command on service containers
+  - language: yaml
+    label: 'Valid service container workflow using new entrypoint/command keys (GitHub Actions only)'
+    code: |
+      jobs:
+        test:
+          runs-on: ubuntu-latest
+          services:
+            redis:
+              image: redis:7
+              # These keys are valid on GitHub Actions (GA April 2, 2026)
+              # but require actionlint >=1.7.8 for linting to pass
+              entrypoint: redis-server
+              command: --save 60 1 --loglevel warning
+              ports:
+                - 6379:6379
+          steps:
+            - uses: actions/checkout@v4
+            - name: Run tests
+              run: npm test
+prevention:
+  - 'Pin actionlint to a specific version in CI and include it in your Dependabot or Renovate configuration so schema updates are picked up promptly when new GitHub Actions features are released.'
+  - 'When a new GitHub Actions feature ships, check the actionlint changelog (https://github.com/rhysd/actionlint/releases) for schema support before using the feature in linted workflows.'
+  - 'Use `# actionlint:ignore` comment as a short-term workaround for valid-but-unknown-to-linter keys while waiting for the schema update.'
+docs:
+  - url: 'https://github.com/rhysd/actionlint/issues/644'
+    label: 'rhysd/actionlint#644 — Add support for entrypoint and command for service containers (fixed in v1.7.8)'
+  - url: 'https://github.blog/changelog/2026-04-02-github-actions-early-april-2026-updates/'
+    label: 'GitHub Changelog — April 2026 updates: entrypoint and command overrides for service containers'
+  - url: 'https://docs.github.com/en/actions/reference/workflows-and-actions/workflow-syntax#jobsjob_idservicesservice_identrypoint'
+    label: 'GitHub Docs — Workflow syntax: jobs.<job_id>.services.<service_id>.entrypoint'

package/package.json

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