@htekdev/actions-debugger 1.0.121 → 1.0.122

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
@@ -0,0 +1,145 @@
1
+ id: runner-environment-221
2
+ title: 'actions/checkout@v6 Hangs at git-credential-osxkeychain on macOS Self-Hosted Runners with Concurrent Jobs'
3
+ category: runner-environment
4
+ severity: error
5
+ tags:
6
+ - checkout
7
+ - macos
8
+ - osxkeychain
9
+ - credential-helper
10
+ - deadlock
11
+ - self-hosted
12
+ - concurrent
13
+ - v6
14
+ - hang
15
+ patterns:
16
+ - regex: 'trace: start_command:.*git-credential-osxkeychain store'
17
+ flags: 'i'
18
+ - regex: 'trace: run_command: .?git credential-osxkeychain store.?$'
19
+ flags: 'im'
20
+ - regex: 'credential-osxkeychain store.*\n.*\n.*\n.*\n.*checkout.*hang'
21
+ flags: 'im'
22
+ error_messages:
23
+ - "trace: run_command: 'git credential-osxkeychain store'"
24
+ - "trace: start_command: /bin/sh -c 'git credential-osxkeychain store' 'git credential-osxkeychain store'"
25
+ - "trace: exec: git-credential-osxkeychain store"
26
+ - "trace: start_command: /opt/homebrew/opt/git/libexec/git-core/git-credential-osxkeychain store"
27
+ root_cause: |
28
+ On macOS self-hosted runners, Git uses git-credential-osxkeychain as the default
29
+ credential helper. When actions/checkout@v6 runs with persist-credentials: true
30
+ (the default), it stores the GITHUB_TOKEN in the macOS Keychain via the osxkeychain
31
+ credential helper.
32
+
33
+ The macOS Keychain grants exclusive write locks to one process at a time. When two or
34
+ more jobs run actions/checkout@v6 concurrently on the same self-hosted runner machine,
35
+ both jobs attempt to call `git credential-osxkeychain store` simultaneously. One process
36
+ acquires the Keychain lock and proceeds; the other blocks indefinitely waiting for the
37
+ lock to be released — which never happens because the macOS Keychain's IPC mechanism
38
+ can deadlock under concurrent access from multiple git processes sharing the same runner
39
+ session.
40
+
41
+ The hung checkout step produces no error output — the last visible log lines are the
42
+ `git-credential-osxkeychain store` trace entries. The job appears to be running but
43
+ makes no progress. Without a step-level timeout, GitHub's 6-hour job timeout eventually
44
+ cancels it.
45
+
46
+ Affected environment:
47
+ - actions/checkout@v6 (v6.0.x, the version that changed credential handling)
48
+ - macOS self-hosted runners, including macOS 26 Tahoe (runner 2.331.0+)
49
+ - Reproduced when ≥2 jobs on the same runner machine execute checkout concurrently
50
+ - Not specific to runner 2.331.0 — also reported on earlier macOS self-hosted setups
51
+ since checkout@v2, but became more frequent with v6's credential handling changes
52
+
53
+ Distinct from runner-environment-032 (persist-credentials: false breaks subsequent
54
+ git push auth — the opposite direction: fixing the push but needing credentials).
55
+ fix: |
56
+ Two workarounds — try Option 1 first, fall back to Option 2 if the deadlock persists:
57
+
58
+ Option 1 — Disable credential persistence for checkout (avoids Keychain writes):
59
+
60
+ - uses: actions/checkout@v6
61
+ with:
62
+ persist-credentials: false
63
+
64
+ This prevents checkout from calling `git credential-osxkeychain store` entirely,
65
+ eliminating the deadlock. Note: if your workflow's later steps need to push changes
66
+ to the repo using git directly (not via GH_TOKEN env var), you must pass the token
67
+ explicitly in the remote URL or use a separate authentication step.
68
+
69
+ Option 2 — Clean workspace before checkout (forces clean lock state):
70
+
71
+ - name: Clean workspace before checkout
72
+ run: |
73
+ find "$GITHUB_WORKSPACE" -mindepth 1 -maxdepth 1 -exec rm -rf {} + \
74
+ || echo "::warning::Workspace cleanup had warnings (non-fatal)"
75
+ - uses: actions/checkout@v6
76
+
77
+ This removes any pre-existing files that might be holding Git process locks
78
+ from a previous job, allowing checkout to complete cleanly. This is an uglier
79
+ workaround but more effective when persist-credentials: false alone does not help.
80
+
81
+ Option 3 — Disable the macOS credential helper globally for CI git operations:
82
+
83
+ - name: Disable osxkeychain credential helper for CI
84
+ run: git config --global credential.helper ''
85
+ - uses: actions/checkout@v6
86
+
87
+ For git push steps that use an explicit token URL, also set GIT_TERMINAL_PROMPT=0:
88
+
89
+ - name: Push changes
90
+ env:
91
+ GIT_TERMINAL_PROMPT: '0'
92
+ run: |
93
+ git -c credential.helper='' push --force \
94
+ "https://x-access-token:${GITHUB_TOKEN}@github.com/${{ github.repository }}.git" \
95
+ HEAD:gh-pages
96
+ fix_code:
97
+ - language: yaml
98
+ label: 'Fix 1 — persist-credentials: false prevents Keychain write (preferred)'
99
+ code: |
100
+ steps:
101
+ - uses: actions/checkout@v6
102
+ with:
103
+ persist-credentials: false # Avoids git-credential-osxkeychain store call
104
+
105
+ - language: yaml
106
+ label: 'Fix 2 — clean workspace before checkout to resolve concurrent lock conflicts'
107
+ code: |
108
+ steps:
109
+ - name: Clean workspace before checkout
110
+ run: |
111
+ find "$GITHUB_WORKSPACE" -mindepth 1 -maxdepth 1 -exec rm -rf {} + \
112
+ || echo "::warning::Cleanup warnings are non-fatal"
113
+
114
+ - uses: actions/checkout@v6
115
+
116
+ - language: yaml
117
+ label: 'Fix 3 — disable osxkeychain globally and use explicit token for git push'
118
+ code: |
119
+ steps:
120
+ - name: Disable macOS keychain credential helper for CI
121
+ run: git config --global credential.helper ''
122
+
123
+ - uses: actions/checkout@v6
124
+
125
+ # Later, for git push steps:
126
+ - name: Push to gh-pages
127
+ env:
128
+ GIT_TERMINAL_PROMPT: '0'
129
+ run: |
130
+ git -c credential.helper='' push --force \
131
+ "https://x-access-token:${GITHUB_TOKEN}@github.com/${{ github.repository }}.git" \
132
+ HEAD:gh-pages
133
+
134
+ prevention:
135
+ - 'Always set persist-credentials: false on actions/checkout@v6 for macOS self-hosted runners if your jobs do not need subsequent git operations using the GITHUB_TOKEN credential helper.'
136
+ - 'Add a timeout-minutes: on checkout steps on macOS self-hosted runners to bound hang duration (e.g., timeout-minutes: 5) rather than waiting for the 6-hour job timeout.'
137
+ - 'Serialize concurrent jobs on the same macOS runner using a concurrency group, or ensure jobs that checkout concurrently run on different runner instances.'
138
+ - 'Set GIT_TERMINAL_PROMPT=0 in macOS self-hosted runner environments to prevent git from waiting for interactive input from any credential helper.'
139
+ docs:
140
+ - url: 'https://github.com/actions/checkout/issues/550'
141
+ label: 'actions/checkout#550 — Actions checkout gets stuck forever randomly (open, 2021–2026)'
142
+ - url: 'https://stackoverflow.com/questions/79881327/github-actions-self-hosted-runner-on-macos-tries-to-checkout-repository-forever'
143
+ label: 'SO q/79881327 — Github Actions self hosted runner on macOS tries to checkout repository forever (Feb 2026)'
144
+ - url: 'https://github.com/actions/checkout#usage'
145
+ label: 'actions/checkout README — persist-credentials input documentation'
@@ -0,0 +1,117 @@
1
+ id: triggers-071
2
+ title: 'on: branches: Filter with Only Negation Patterns Silently Never Triggers'
3
+ category: triggers
4
+ severity: silent-failure
5
+ tags:
6
+ - branches-filter
7
+ - push
8
+ - pull_request
9
+ - negation
10
+ - glob
11
+ - workflow-not-triggering
12
+ patterns:
13
+ - regex: 'branches:\s*\n(\s+-\s+[''"]?!)'
14
+ flags: 'm'
15
+ - regex: 'branches:\s*\[\s*[''"]?!'
16
+ flags: 'i'
17
+ error_messages:
18
+ - "# No error message — workflow simply never appears in the Actions run queue"
19
+ root_cause: |
20
+ GitHub Actions branch filters evaluate patterns sequentially against the ref name. The
21
+ documented rule is: "the workflow only runs if at least one pattern matches the ref name."
22
+
23
+ When a branches: (or branches-ignore's inverse: branches:) filter list contains ONLY
24
+ negation patterns (entries starting with !), no positive match is ever established.
25
+ Negation patterns can only EXCLUDE from an existing positive match set — they cannot
26
+ create a match on their own. The evaluation starts with zero matches, negations find
27
+ nothing to remove, and the result is always "no match" → workflow never fires.
28
+
29
+ This is a silent failure: no error is raised, no annotation appears, and the workflow
30
+ simply never shows up in the Actions tab when the target branch is pushed to. It is
31
+ especially confusing because the workflow file is syntactically valid and GitHub accepts it.
32
+
33
+ Common mistake patterns:
34
+ branches:
35
+ - '!main' # ← Only a negation — zero positive matches → never triggers
36
+
37
+ branches:
38
+ - '!master' # ← Same problem — always zero triggers
39
+ - '!release/**'
40
+
41
+ The branches-ignore filter does NOT have this problem because it operates on the
42
+ complement: it matches everything EXCEPT the listed patterns. Use branches-ignore when
43
+ you want to exclude specific branches.
44
+
45
+ Source: SO q/57699839 (144 votes) "GitHub Actions: how to target all branches EXCEPT
46
+ master?" — accepted answer (242 votes) documents the required positive+negative combo.
47
+ fix: |
48
+ To target all branches EXCEPT specific ones, choose one of two approaches:
49
+
50
+ Option 1 — Add wildcard positive patterns before the negation (order matters):
51
+
52
+ on:
53
+ push:
54
+ branches:
55
+ - '*' # matches every branch without a '/' (e.g. main, develop)
56
+ - '*/*' # matches single-slash branches (e.g. feature/x)
57
+ - '**' # matches all remaining branches
58
+ - '!main' # now excludes main from the positive matches above
59
+
60
+ Option 2 — Use branches-ignore instead (simpler and cleaner):
61
+
62
+ on:
63
+ push:
64
+ branches-ignore:
65
+ - main
66
+ - 'release/**'
67
+
68
+ Do NOT combine branches: and branches-ignore: on the same event — GitHub rejects that
69
+ combination with a YAML validation error.
70
+ fix_code:
71
+ - language: yaml
72
+ label: 'Broken — only negation in branches: filter, workflow never runs'
73
+ code: |
74
+ # This workflow NEVER triggers for any branch push — negation-only matches nothing:
75
+ on:
76
+ push:
77
+ branches:
78
+ - '!main' # WRONG: no positive pattern to negate from
79
+
80
+ - language: yaml
81
+ label: 'Fixed — positive wildcard patterns before negation'
82
+ code: |
83
+ # Correct approach: include positive patterns first, then exclude specific branches:
84
+ on:
85
+ push:
86
+ branches:
87
+ - '*' # matches branches without '/' in name
88
+ - '*/*' # matches single-level slash branches
89
+ - '**' # matches all remaining branches
90
+ - '!main' # now excludes main from the above positive matches
91
+
92
+ - language: yaml
93
+ label: 'Alternative fix — use branches-ignore (simplest for exclusion only)'
94
+ code: |
95
+ # Use branches-ignore when you want to exclude specific branches entirely:
96
+ on:
97
+ push:
98
+ branches-ignore:
99
+ - main
100
+ - 'release/**'
101
+ - 'hotfix/**'
102
+ pull_request:
103
+ branches-ignore:
104
+ - main
105
+
106
+ prevention:
107
+ - 'When you want to exclude branches, prefer branches-ignore: over branches: with negation — it is simpler and has no positive-pattern requirement.'
108
+ - 'If you must use branches: with negation, always include at least one positive glob (like ** or *) before the negation patterns.'
109
+ - 'Remember that pattern order matters: a positive match AFTER a negative pattern re-includes the ref; a negative match AFTER a positive match excludes it.'
110
+ - 'Use actionlint or act --list to verify your workflow would trigger before relying on pushes to test it.'
111
+ docs:
112
+ - url: 'https://docs.github.com/en/actions/using-workflows/workflow-syntax-for-github-actions#onpushbranchestagsbranches-ignoretags-ignore'
113
+ label: 'GitHub Docs — on.push.branches filter syntax and negation patterns'
114
+ - url: 'https://stackoverflow.com/questions/57699839/github-actions-how-to-target-all-branches-except-master'
115
+ label: 'SO q/57699839 (144 votes) — GitHub Actions: how to target all branches EXCEPT master?'
116
+ - url: 'https://docs.github.com/en/actions/using-workflows/workflow-syntax-for-github-actions#filter-pattern-cheat-sheet'
117
+ label: 'GitHub Docs — Filter pattern cheat sheet (glob syntax reference)'
@@ -0,0 +1,130 @@
1
+ id: yaml-syntax-074
2
+ title: 'Workflow YAML File in Nested Subdirectory of .github/workflows/ Is Silently Ignored'
3
+ category: yaml-syntax
4
+ severity: silent-failure
5
+ tags:
6
+ - workflow-placement
7
+ - subdirectory
8
+ - nested-folder
9
+ - file-location
10
+ - workflow-not-appearing
11
+ - silent-failure
12
+ patterns:
13
+ - regex: '\.github/workflows/[^/\s]+/[^/\s]+\.ya?ml'
14
+ flags: 'i'
15
+ error_messages:
16
+ - "# No error — workflow YAML in .github/workflows/subdir/name.yml is silently ignored"
17
+ - "# Workflow never appears in Actions tab; no annotation is created"
18
+ root_cause: |
19
+ GitHub Actions only scans for workflow files in the DIRECT children of
20
+ `.github/workflows/` — it does NOT recurse into subdirectories. Files placed in
21
+ nested paths such as:
22
+
23
+ .github/workflows/ci/build.yml
24
+ .github/workflows/scripts/deploy.yaml
25
+ .github/workflows/reusable/my-caller.yml
26
+
27
+ are completely invisible to GitHub Actions. The runner does not parse them, does not
28
+ validate them, and emits no error or warning of any kind. The workflow simply never
29
+ appears in the repository's Actions tab, regardless of how correct the YAML content is.
30
+
31
+ This is a documented but easy-to-overlook constraint in the GitHub Actions architecture.
32
+ The scanner uses a shallow file glob equivalent to `.github/workflows/*.yml` and
33
+ `.github/workflows/*.yaml` — NOT `.github/workflows/**/*.yml`.
34
+
35
+ Common causes:
36
+ 1. Developers organize workflows into subdirectories for clarity (e.g., `ci/`, `deploy/`),
37
+ not realizing GitHub won't pick them up.
38
+ 2. Copy-pasting a workflow into a folder that already holds related shell scripts or
39
+ configuration files, creating an unintended nested path.
40
+ 3. Renaming or restructuring the .github directory and accidentally moving workflow files
41
+ one level too deep.
42
+ 4. Reusable workflow files placed in a `reusable/` or `shared/` subdirectory under
43
+ workflows/ — these also won't be discovered by GitHub as callable workflows.
44
+
45
+ Note: This affects ALL workflow types — regular workflows, reusable workflows
46
+ (workflow_call), scheduled workflows, and manually dispatched workflows alike.
47
+
48
+ Source: SO q/61989951 answer (score 9, from the 158-vote "GitHub Action workflow not
49
+ running" thread) and GitHub Actions documentation.
50
+ fix: |
51
+ Move all workflow YAML files directly into `.github/workflows/` (one level deep).
52
+ Do not create subdirectories inside `.github/workflows/` for workflow YAML files.
53
+
54
+ If you want to organize workflows logically, use naming prefixes instead of folders:
55
+
56
+ .github/workflows/ci-build.yml
57
+ .github/workflows/ci-test.yml
58
+ .github/workflows/deploy-staging.yml
59
+ .github/workflows/deploy-production.yml
60
+
61
+ For scripts, configs, and helper files that are referenced by workflows, place them
62
+ in a separate directory OUTSIDE `.github/workflows/`, for example:
63
+ .github/scripts/
64
+ .github/actions/my-local-action/
65
+
66
+ Note: Local composite actions (in `.github/actions/`) CAN be in subdirectories — the
67
+ subdirectory restriction only applies to workflow YAML files inside `.github/workflows/`.
68
+ fix_code:
69
+ - language: yaml
70
+ label: 'Broken — workflow file in nested subdirectory (silently ignored)'
71
+ code: |
72
+ # .github/workflows/ci/build.yml ← WRONG LOCATION, never discovered
73
+ name: Build CI
74
+
75
+ on:
76
+ push:
77
+ branches: ['**']
78
+
79
+ jobs:
80
+ build:
81
+ runs-on: ubuntu-latest
82
+ steps:
83
+ - uses: actions/checkout@v4
84
+ - run: npm ci && npm run build
85
+
86
+ - language: yaml
87
+ label: 'Fixed — workflow file at root of .github/workflows/'
88
+ code: |
89
+ # .github/workflows/ci-build.yml ← CORRECT LOCATION, discovered by GitHub
90
+ name: Build CI
91
+
92
+ on:
93
+ push:
94
+ branches: ['**']
95
+
96
+ jobs:
97
+ build:
98
+ runs-on: ubuntu-latest
99
+ steps:
100
+ - uses: actions/checkout@v4
101
+ - run: npm ci && npm run build
102
+
103
+ - language: yaml
104
+ label: 'Organization pattern — use prefixes instead of subdirectories'
105
+ code: |
106
+ # Use name prefixes to group related workflows at the root level:
107
+ # .github/workflows/ci-build.yml
108
+ # .github/workflows/ci-lint.yml
109
+ # .github/workflows/ci-test.yml
110
+ # .github/workflows/deploy-staging.yml
111
+ # .github/workflows/deploy-production.yml
112
+ # .github/workflows/release-tag.yml
113
+ #
114
+ # Helper scripts/configs can be in subdirectories outside workflows/:
115
+ # .github/scripts/deploy.sh
116
+ # .github/actions/my-composite-action/action.yml ← composite actions CAN be nested
117
+
118
+ prevention:
119
+ - 'Keep all workflow YAML files (.yml / .yaml) directly in .github/workflows/ — never in subdirectories of that folder.'
120
+ - 'For workflow organization, use descriptive filename prefixes (ci-, deploy-, release-) instead of subdirectories.'
121
+ - 'Place helper shell scripts in .github/scripts/ and composite actions in .github/actions/<name>/ — subdirectories are fine there but not for workflow files.'
122
+ - 'After creating a new workflow file, immediately check that it appears in the repository Actions tab before relying on it for CI.'
123
+ - 'Use actionlint or the GitHub Actions VS Code extension to validate placement — both tools warn about unrecognized workflow file locations.'
124
+ docs:
125
+ - url: 'https://docs.github.com/en/actions/using-workflows/about-workflows#workflow-basics'
126
+ label: 'GitHub Docs — About workflows: file placement requirements'
127
+ - url: 'https://stackoverflow.com/questions/61989951/github-action-workflow-not-running'
128
+ label: 'SO q/61989951 (158 votes) — GitHub Action workflow not running (answer: nested subfolder not recognized)'
129
+ - url: 'https://docs.github.com/en/actions/creating-actions/creating-a-composite-action'
130
+ label: 'GitHub Docs — Composite actions (can be in .github/actions/ subdirectories)'
package/package.json CHANGED
@@ -1,6 +1,6 @@
1
1
  {
2
2
  "name": "@htekdev/actions-debugger",
3
- "version": "1.0.121",
3
+ "version": "1.0.122",
4
4
  "description": "65+ real GitHub Actions errors, queryable by agents. CLI + MCP server + Copilot skills + error database.",
5
5
  "type": "module",
6
6
  "main": "./dist/index.js",