@htekdev/actions-debugger 1.0.0 → 1.0.1

package/errors/known-unsolved/no-dynamic-secret-access.yml

@@ -0,0 +1,111 @@
+id: known-unsolved-005
+title: "No Dynamic Secret Access — Cannot Resolve Secret Name from a Variable"
+category: known-unsolved
+severity: limitation
+tags:
+  - secrets
+  - dynamic
+  - variable
+  - runtime
+  - limitation
+  - workaround
+patterns:
+  - regex: "secrets\\[\\$\\{\\{.*\\}\\}\\]"
+    flags: "i"
+  - regex: "Unrecognized named-value: 'secrets'"
+    flags: "i"
+error_messages:
+  - "Context access might be invalid: secrets[variableName]"
+  - "The secrets context does not support dynamic access."
+root_cause: |
+  GitHub Actions secrets can only be accessed by their **literal name** at workflow
+  authoring time — there is no way to resolve a secret by a name computed at runtime.
+
+  Expressions like `${{ secrets[env.SECRET_NAME] }}` or
+  `${{ secrets[github.event.inputs.env] }}` are not valid. The expression parser requires
+  the secret name to be a compile-time string literal, not a variable reference.
+
+  This is a deliberate security measure: dynamic secret access would allow workflows
+  to iterate over all secrets and exfiltrate them, or allow user-controlled input to
+  select which secret to use (a form of secret injection attack).
+
+  Teams that need environment-specific secrets often try to work around this with dynamic
+  naming patterns (`PROD_API_KEY`, `STAGING_API_KEY`) but cannot select between them at
+  runtime without pre-wiring all possibilities at workflow authoring time.
+fix: |
+  There is no supported dynamic secret access. Use one of these workarounds:
+  1. **Inline all possibilities** with a conditional step per environment
+  2. **Use GitHub Environments** — each environment has its own secret namespace,
+     and selecting `environment: production` vs `environment: staging` automatically
+     scopes secrets without dynamic resolution
+  3. **Use a secrets manager** (AWS Secrets Manager, Azure Key Vault, HashiCorp Vault)
+     where dynamic key lookups ARE supported at runtime
+fix_code:
+  - language: yaml
+    label: "WRONG — dynamic secret access (not supported)"
+    code: |
+      jobs:
+        deploy:
+          runs-on: ubuntu-latest
+          steps:
+            - name: Get environment-specific secret
+              env:
+                # This does NOT work — cannot use variable as secret key
+                API_KEY: ${{ secrets[format('{0}_API_KEY', github.event.inputs.environment)] }}
+              run: ./deploy.sh
+  - language: yaml
+    label: "CORRECT option 1 — explicit conditional per environment"
+    code: |
+      jobs:
+        deploy:
+          runs-on: ubuntu-latest
+          steps:
+            - name: Set environment-specific secret
+              run: |
+                if [ "${{ github.event.inputs.environment }}" = "production" ]; then
+                  echo "API_KEY=${{ secrets.PROD_API_KEY }}" >> $GITHUB_ENV
+                elif [ "${{ github.event.inputs.environment }}" = "staging" ]; then
+                  echo "API_KEY=${{ secrets.STAGING_API_KEY }}" >> $GITHUB_ENV
+                fi
+            - run: ./deploy.sh
+  - language: yaml
+    label: "CORRECT option 2 — use GitHub Environments (recommended)"
+    code: |
+      on:
+        workflow_dispatch:
+          inputs:
+            environment:
+              type: choice
+              options: [production, staging]
+
+      jobs:
+        deploy:
+          runs-on: ubuntu-latest
+          environment: ${{ github.event.inputs.environment }}   # auto-scopes secrets
+          steps:
+            # secrets.API_KEY automatically resolves to the correct environment's secret
+            - run: ./deploy.sh
+              env:
+                API_KEY: ${{ secrets.API_KEY }}
+  - language: yaml
+    label: "CORRECT option 3 — delegate to a secrets manager"
+    code: |
+      jobs:
+        deploy:
+          runs-on: ubuntu-latest
+          steps:
+            - uses: aws-actions/aws-secretsmanager-get-secrets@v2
+              with:
+                secret-ids: |
+                  ${{ github.event.inputs.environment }}/api-key   # dynamic lookup is fine here
+prevention:
+  - "Use GitHub Environments — they provide per-environment secret namespacing without dynamic access."
+  - "For more than 2-3 environments, invest in a proper secrets manager (Vault, AWS SM, Azure KV)."
+  - "Never attempt `secrets[variable]` — it silently produces an empty string and the workflow continues with empty credentials."
+docs:
+  - url: "https://docs.github.com/en/actions/managing-workflow-runs-and-deployments/managing-deployments/managing-environments-for-deployment"
+    label: "Managing environments for deployment"
+  - url: "https://docs.github.com/en/actions/security-for-github-actions/security-guides/using-secrets-in-github-actions"
+    label: "Using secrets in GitHub Actions"
+  - url: "https://github.com/orgs/community/discussions/29248"
+    label: "Community discussion: Dynamic secret access (GitHub Community)"

package/errors/known-unsolved/no-step-level-rerun.yml

@@ -0,0 +1,94 @@
+id: known-unsolved-006
+title: "No Native Way to Retry a Single Failed Step Without Re-Running the Entire Job"
+category: known-unsolved
+severity: limitation
+tags:
+  - retry
+  - step
+  - flaky
+  - re-run
+  - limitation
+  - idempotency
+patterns:
+  - regex: "Re-run failed jobs"
+    flags: "i"
+  - regex: "retry.*step.*not supported"
+    flags: "i"
+error_messages:
+  - "GitHub Actions does not support step-level re-run — only job-level or failed-jobs-level re-run is available."
+root_cause: |
+  GitHub Actions' "Re-run" feature operates at the **job level** or "re-run failed jobs"
+  level — there is no UI or API to re-run a single failed step within an already-completed
+  job. When you click "Re-run failed jobs," the entire job restarts from the beginning,
+  including all steps that already passed.
+
+  This has three practical consequences:
+  1. **Flaky step recovery is expensive** — a 20-minute job must re-run entirely to retry
+     a 30-second network call that failed transiently.
+  2. **Non-idempotent steps can double-execute** — steps that modify external state
+     (publish to npm, create a GitHub release, push Docker image) will attempt to run again
+     on re-run, even if they succeeded the first time.
+  3. **Re-run artifacts** — artifacts and cache from the first run may or may not be
+     available depending on what step failed and whether post-steps ran.
+
+  This limitation has been requested since GitHub Actions launched. As of 2024, GitHub
+  has not implemented step-level granularity for re-runs.
+fix: |
+  Design workflows with step-level retry in mind from the start. Use retry actions
+  inline, make steps idempotent, and split long workflows into jobs so that a partial
+  re-run covers fewer steps.
+fix_code:
+  - language: yaml
+    label: "Workaround 1 — use nick-fields/retry for flaky steps"
+    code: |
+      steps:
+        - name: Flaky network call (with retry)
+          uses: nick-fields/retry@v3
+          with:
+            timeout_minutes: 5
+            max_attempts: 3
+            retry_wait_seconds: 10
+            command: curl -f https://api.example.com/deploy
+  - language: yaml
+    label: "Workaround 2 — inline retry loop"
+    code: |
+      steps:
+        - name: Deploy with retry
+          run: |
+            for i in 1 2 3; do
+              echo "Attempt $i"
+              ./deploy.sh && break || {
+                echo "Attempt $i failed"
+                if [ $i -eq 3 ]; then
+                  echo "::error::All 3 deploy attempts failed"
+                  exit 1
+                fi
+                sleep 30
+              }
+            done
+  - language: yaml
+    label: "Workaround 3 — idempotent steps that safe to re-run"
+    code: |
+      steps:
+        - name: Create GitHub Release (idempotent — skip if already exists)
+          run: |
+            TAG="${{ github.ref_name }}"
+            if gh release view "$TAG" &>/dev/null; then
+              echo "Release $TAG already exists — skipping creation"
+            else
+              gh release create "$TAG" dist/*.tar.gz
+            fi
+          env:
+            GH_TOKEN: ${{ secrets.GITHUB_TOKEN }}
+prevention:
+  - "Build retry logic directly into steps using `nick-fields/retry` or shell loops — don't rely on job re-run for flaky operations."
+  - "Make every step idempotent (safe to run twice) so job re-runs don't cause double-execution side effects."
+  - "Split workflows into small jobs — `Re-run failed jobs` is more surgical with smaller jobs."
+  - "Cache and upload artifacts eagerly so a re-run can pick up from near the failure point."
+docs:
+  - url: "https://docs.github.com/en/actions/managing-workflow-runs-and-deployments/managing-workflow-runs/re-running-workflows-and-jobs"
+    label: "Re-running workflows and jobs"
+  - url: "https://github.com/nick-fields/retry"
+    label: "nick-fields/retry — step-level retry action"
+  - url: "https://github.com/orgs/community/discussions/17743"
+    label: "Community discussion: Step-level re-run (GitHub Community)"

package/errors/known-unsolved/no-step-retry.yml

@@ -1,53 +1,53 @@
-id: known-unsolved-002
-title: "No Step-Level Retry"
-category: known-unsolved
-severity: limitation
-tags:
-  - retry
-  - steps
-  - limitation
-  - flakiness
-  - resilience
-patterns:
-  - regex: "Process completed with exit code [0-9]+"
-    flags: "i"
-  - regex: 'curl: \(28\) Operation timed out'
-    flags: "i"
-  - regex: "npm ERR! network"
-    flags: "i"
-error_messages:
-  - "Process completed with exit code 1"
-  - "curl: (28) Operation timed out"
-root_cause: |
-  GitHub Actions can rerun jobs and whole workflows, but it does not provide native retry
-  semantics for a single arbitrary step. That means flaky network calls, package registry
-  hiccups, and transient shell commands fail the step immediately unless you build a retry
-  wrapper yourself.
-
-  This is a platform limitation rather than a YAML mistake.
-fix: |
-  Wrap the flaky command in a retry helper or use a marketplace action such as
-  `nick-fields/retry` when retry semantics are needed for one step only.
-fix_code:
-  - language: yaml
-    label: "Retry a flaky step with nick-fields/retry"
-    code: |
-      - name: Retry npm install
-        uses: nick-fields/retry@v3
-        with:
-          timeout_minutes: 15
-          max_attempts: 3
-          retry_wait_seconds: 20
-          command: npm ci
-prevention:
-  - "Assume external network calls are flaky and wrap them in retries if they are business-critical."
-  - "Prefer idempotent commands for steps that may need retry wrappers."
-  - "Document step-level retry strategy because GitHub Actions does not provide it natively."
-docs:
-  - url: "https://docs.github.com/en/actions/managing-workflow-runs-and-deployments/managing-workflow-runs/re-running-workflows-and-jobs"
-    label: "Re-running workflows and jobs"
-  - url: "https://docs.github.com/en/actions/using-workflows/workflow-syntax-for-github-actions"
-    label: "Workflow syntax for GitHub Actions"
-source:
-  article: "https://htek.dev/articles/github-actions-debugging-guide"
-  section: "Platform limitations: no step-level retry"
+id: known-unsolved-002
+title: "No Step-Level Retry"
+category: known-unsolved
+severity: limitation
+tags:
+  - retry
+  - steps
+  - limitation
+  - flakiness
+  - resilience
+patterns:
+  - regex: "Process completed with exit code [0-9]+"
+    flags: "i"
+  - regex: 'curl: \(28\) Operation timed out'
+    flags: "i"
+  - regex: "npm ERR! network"
+    flags: "i"
+error_messages:
+  - "Process completed with exit code 1"
+  - "curl: (28) Operation timed out"
+root_cause: |
+  GitHub Actions can rerun jobs and whole workflows, but it does not provide native retry
+  semantics for a single arbitrary step. That means flaky network calls, package registry
+  hiccups, and transient shell commands fail the step immediately unless you build a retry
+  wrapper yourself.
+
+  This is a platform limitation rather than a YAML mistake.
+fix: |
+  Wrap the flaky command in a retry helper or use a marketplace action such as
+  `nick-fields/retry` when retry semantics are needed for one step only.
+fix_code:
+  - language: yaml
+    label: "Retry a flaky step with nick-fields/retry"
+    code: |
+      - name: Retry npm install
+        uses: nick-fields/retry@v3
+        with:
+          timeout_minutes: 15
+          max_attempts: 3
+          retry_wait_seconds: 20
+          command: npm ci
+prevention:
+  - "Assume external network calls are flaky and wrap them in retries if they are business-critical."
+  - "Prefer idempotent commands for steps that may need retry wrappers."
+  - "Document step-level retry strategy because GitHub Actions does not provide it natively."
+docs:
+  - url: "https://docs.github.com/en/actions/managing-workflow-runs-and-deployments/managing-workflow-runs/re-running-workflows-and-jobs"
+    label: "Re-running workflows and jobs"
+  - url: "https://docs.github.com/en/actions/using-workflows/workflow-syntax-for-github-actions"
+    label: "Workflow syntax for GitHub Actions"
+source:
+  article: "https://htek.dev/articles/github-actions-debugging-guide"
+  section: "Platform limitations: no step-level retry"

package/errors/permissions-auth/checkout-submodule-private-auth.yml

@@ -0,0 +1,91 @@
+id: permissions-auth-003
+title: "Checkout Private Submodules Fails — Permission Denied or Repository Not Found"
+category: permissions-auth
+severity: error
+tags:
+  - checkout
+  - submodules
+  - private-repos
+  - PAT
+  - SSH
+  - GITHUB_TOKEN
+patterns:
+  - regex: "fatal: could not read Username for 'https://github\\.com/'.*terminal prompts disabled"
+    flags: "i"
+  - regex: "git@github\\.com: Permission denied \\(publickey\\)"
+    flags: "i"
+  - regex: "remote: Repository not found\\."
+    flags: "i"
+  - regex: "fatal: clone of '.*' into submodule path .* failed"
+    flags: "i"
+  - regex: "Host key verification failed"
+    flags: "i"
+error_messages:
+  - "fatal: could not read Username for 'https://github.com/': terminal prompts disabled"
+  - "git@github.com: Permission denied (publickey)."
+  - "remote: Repository not found."
+  - "Error: fatal: clone of 'git@github.com:Org/SubRepo.git' into submodule path '<path>' failed"
+  - "Host key verification failed."
+root_cause: |
+  The default `GITHUB_TOKEN` only grants access to the single repository that triggered the workflow.
+  When a repository contains submodules pointing to other private repositories, the checkout action
+  cannot authenticate to those private repos using GITHUB_TOKEN alone.
+
+  Two distinct failure modes exist depending on how submodule URLs are declared in `.gitmodules`:
+
+  1. HTTPS submodule URL (`https://github.com/Org/Repo`) — fails with "terminal prompts disabled"
+     because git cannot interactively prompt for credentials in a non-interactive CI environment,
+     and GITHUB_TOKEN is not forwarded to the submodule clone.
+
+  2. SSH submodule URL (`git@github.com:Org/Repo.git`) — fails with "Permission denied (publickey)"
+     because no SSH private key is configured on the runner.
+
+  This is especially confusing when the parent repository checkout succeeds and only the submodule
+  clone step fails, and because `remote: Repository not found` is the error GitHub returns when
+  authentication fails for a private repo (the repo is hidden from unauthenticated access).
+fix: |
+  The fix depends on the URL scheme used in `.gitmodules`:
+
+  For HTTPS submodule URLs: provide a Personal Access Token (PAT) with `repo` scope via the `token`
+  input of `actions/checkout`. The action will automatically configure git credential helpers using
+  the provided token for all submodule clones.
+
+  For SSH submodule URLs (`git@github.com:...`): provide an SSH deploy key via the `ssh-key` input.
+  A PAT will NOT work for SSH-scheme URLs — the authentication mechanism is fundamentally different.
+
+  For organization-wide private submodule access, a GitHub App installation token is preferred over
+  a personal PAT because it does not depend on an individual user's account.
+fix_code:
+  - language: yaml
+    label: "Checkout private HTTPS submodules using a PAT"
+    code: |
+      - uses: actions/checkout@v4
+        with:
+          submodules: recursive
+          token: ${{ secrets.GH_PAT_SUBMODULES }}
+          # PAT must have 'repo' scope and access to all private submodule repos
+          # Do NOT use GITHUB_TOKEN — it only covers the current repository
+  - language: yaml
+    label: "Checkout private SSH submodules using a deploy key"
+    code: |
+      - uses: actions/checkout@v4
+        with:
+          submodules: recursive
+          ssh-key: ${{ secrets.SUBMODULES_DEPLOY_KEY }}
+          # SSH private key must be added as a deploy key to all private submodule repos
+          # Required when .gitmodules uses SSH-scheme URLs (git@github.com:...)
+prevention:
+  - "Check `.gitmodules` URL scheme first — HTTPS submodules need a PAT, SSH submodules need an SSH deploy key."
+  - "Never use GITHUB_TOKEN for private submodule checkout — it only covers the triggering repository."
+  - "Prefer GitHub App installation tokens over PATs for organization-wide private submodule access."
+  - "Add the PAT or deploy key to repository (or organization) secrets before running the workflow."
+  - "Test with a manual workflow_dispatch run before adding to CI pipelines."
+docs:
+  - url: "https://docs.github.com/en/actions/security-guides/automatic-token-authentication#permissions-for-the-github_token"
+    label: "GITHUB_TOKEN permissions — scope limited to the current repository"
+  - url: "https://github.com/actions/checkout#usage"
+    label: "actions/checkout README — token and ssh-key inputs"
+  - url: "https://github.com/actions/checkout/issues/738"
+    label: "actions/checkout#738 — terminal prompts disabled with private submodules (many affected users)"
+  - url: "https://github.com/actions/checkout/issues/2080"
+    label: "actions/checkout#2080 — Repository not found error with private submodules without PAT"

package/errors/permissions-auth/fork-pr-secrets-unavailable.yml

@@ -0,0 +1,97 @@
+id: permissions-auth-005
+title: "Secrets Unavailable in Workflows Triggered by Fork Pull Requests"
+category: permissions-auth
+severity: silent-failure
+tags:
+  - secrets
+  - fork
+  - pull_request
+  - permissions
+  - security
+  - third-party
+patterns:
+  - regex: "Context access might be invalid: secrets"
+    flags: "i"
+  - regex: "secrets\\.[A-Z_]+ is not available"
+    flags: "i"
+error_messages:
+  - "Error: Input required and not supplied: token"
+  - "Error: Resource not accessible by integration"
+  - "HttpError: Resource not accessible by integration"
+root_cause: |
+  By design, GitHub Actions does not pass `secrets.*` to workflows triggered by
+  `pull_request` events from **fork repositories**. This is a security measure: a
+  malicious actor could open a PR from a fork and, if secrets were available, extract
+  them by printing them or exfiltrating them via a network call in the workflow.
+
+  When a fork PR triggers a `pull_request` workflow, `secrets.GITHUB_TOKEN` is also
+  **read-only** (cannot push back to the repo) and all other named secrets resolve to
+  empty strings. There is no error — the secret silently returns `""`.
+
+  Common symptoms: actions/checkout fails to fetch LFS or private submodules,
+  third-party action API calls fail with 401/403, Docker logins fail silently.
+fix: |
+  Use `pull_request_target` for workflows that need secrets from fork PRs, but **only
+  after thoroughly auditing the workflow for code injection risks** — `pull_request_target`
+  runs in the context of the base branch (not the fork's code) and has full secret access.
+  Alternatively, use the `Repository maintainers must approve` workflow setting to gate
+  secret access on trusted reviewer approval.
+fix_code:
+  - language: yaml
+    label: "WRONG — pull_request from fork has no secrets"
+    code: |
+      on: pull_request   # from fork: secrets are all empty strings
+
+      jobs:
+        test:
+          runs-on: ubuntu-latest
+          steps:
+            - uses: actions/checkout@v4
+            - name: Authenticate to registry
+              run: echo "${{ secrets.DOCKER_PASSWORD }}" | docker login -u user --password-stdin
+              # FAILS silently — DOCKER_PASSWORD is "" for fork PRs
+  - language: yaml
+    label: "CORRECT — use pull_request_target with safety guard"
+    code: |
+      on:
+        pull_request_target:
+          types: [opened, synchronize]
+
+      jobs:
+        test:
+          runs-on: ubuntu-latest
+          # Only run for trusted contributors to prevent code injection
+          if: |
+            github.event.pull_request.head.repo.full_name == github.repository ||
+            contains(fromJSON('["MEMBER","OWNER","COLLABORATOR"]'), github.event.pull_request.author_association)
+          steps:
+            # CRITICAL: checkout the BASE, not the PR head, to avoid untrusted code execution
+            - uses: actions/checkout@v4
+              with:
+                ref: ${{ github.event.pull_request.base.sha }}
+            - run: echo "${{ secrets.DOCKER_PASSWORD }}" | docker login -u user --password-stdin
+  - language: yaml
+    label: "ALTERNATIVE — fork-safe workflow with manual approval step"
+    code: |
+      # In org settings: require approval for first-time contributors
+      # Settings → Actions → Fork pull request workflows → Require approval for all outside collaborators
+      on: pull_request
+
+      jobs:
+        test:
+          runs-on: ubuntu-latest
+          steps:
+            - uses: actions/checkout@v4
+            # For public tests that don't need secrets:
+            - run: npm test
+prevention:
+  - "Never assume secrets are available in `pull_request` workflows from forks — always check with `github.event.pull_request.head.repo.fork`."
+  - "Require manual approval for fork PRs in your org's Actions settings."
+  - "When using `pull_request_target`, ALWAYS check out the base SHA, not the PR head — running fork code with full secrets is a critical security vulnerability."
+docs:
+  - url: "https://docs.github.com/en/actions/security-for-github-actions/security-guides/security-hardening-for-github-actions#understanding-the-risk-of-script-injections"
+    label: "Security hardening — script injection risks"
+  - url: "https://docs.github.com/en/actions/writing-workflows/choosing-when-your-workflow-runs/events-that-trigger-workflows#pull_request_target"
+    label: "pull_request_target event"
+  - url: "https://securitylab.github.com/resources/github-actions-preventing-pwn-requests/"
+    label: "Preventing pwn requests (GitHub Security Lab)"

package/errors/permissions-auth/github-token-403.yml

@@ -1,64 +1,64 @@
-id: permissions-auth-001
-title: "GITHUB_TOKEN Permission Denied (403)"
-category: permissions-auth
-severity: error
-tags:
-  - github-token
-  - permissions
-  - 403
-  - auth
-  - push
-patterns:
-  - regex: "remote: Permission to .+\\.git denied to github-actions\\[bot\\]"
-    flags: "i"
-  - regex: "fatal: unable to access 'https://github\\.com/.+': The requested URL returned error: 403"
-    flags: "i"
-  - regex: "Resource not accessible by integration"
-    flags: "i"
-error_messages:
-  - "remote: Permission to org/repo.git denied to github-actions[bot]."
-  - "fatal: unable to access 'https://github.com/org/repo.git/': The requested URL returned error: 403"
-  - "Resource not accessible by integration"
-root_cause: |
-  Since February 2023, newly created repositories default `GITHUB_TOKEN` to read-only
-  permissions in many cases. A workflow that tries to push commits, create releases, or
-  modify pull requests without an explicit `permissions:` block can suddenly fail with 403
-  or integration access errors.
-
-  The token exists, but it does not have the scopes the job assumed it had.
-fix: |
-  Add the minimum required `permissions:` block at the workflow or job level. For pushes,
-  tags, or release creation, that usually means `contents: write`. For pull request comments
-  or checks, grant the specific write permission those APIs require.
-fix_code:
-  - language: yaml
-    label: "Grant explicit write permissions to GITHUB_TOKEN"
-    code: |
-      name: Release
-
-      on:
-        push:
-          branches:
-            - main
-
-      permissions:
-        contents: write
-
-      jobs:
-        release:
-          runs-on: ubuntu-latest
-          steps:
-            - uses: actions/checkout@v4
-            - run: git push origin HEAD:main
-prevention:
-  - "Assume `GITHUB_TOKEN` is read-only unless you explicitly grant the needed permission."
-  - "Set least-privilege `permissions:` blocks on every workflow instead of relying on defaults."
-  - "Match API usage to the smallest write scope required."
-docs:
-  - url: "https://docs.github.com/en/actions/security-guides/automatic-token-authentication"
-    label: "Automatic token authentication"
-  - url: "https://docs.github.com/en/actions/using-workflows/workflow-syntax-for-github-actions#permissions"
-    label: "permissions"
-source:
-  article: "https://htek.dev/articles/github-actions-debugging-guide"
-  section: "GITHUB_TOKEN 403 and read-only defaults"
+id: permissions-auth-001
+title: "GITHUB_TOKEN Permission Denied (403)"
+category: permissions-auth
+severity: error
+tags:
+  - github-token
+  - permissions
+  - 403
+  - auth
+  - push
+patterns:
+  - regex: "remote: Permission to .+\\.git denied to github-actions\\[bot\\]"
+    flags: "i"
+  - regex: "fatal: unable to access 'https://github\\.com/.+': The requested URL returned error: 403"
+    flags: "i"
+  - regex: "Resource not accessible by integration"
+    flags: "i"
+error_messages:
+  - "remote: Permission to org/repo.git denied to github-actions[bot]."
+  - "fatal: unable to access 'https://github.com/org/repo.git/': The requested URL returned error: 403"
+  - "Resource not accessible by integration"
+root_cause: |
+  Since February 2023, newly created repositories default `GITHUB_TOKEN` to read-only
+  permissions in many cases. A workflow that tries to push commits, create releases, or
+  modify pull requests without an explicit `permissions:` block can suddenly fail with 403
+  or integration access errors.
+
+  The token exists, but it does not have the scopes the job assumed it had.
+fix: |
+  Add the minimum required `permissions:` block at the workflow or job level. For pushes,
+  tags, or release creation, that usually means `contents: write`. For pull request comments
+  or checks, grant the specific write permission those APIs require.
+fix_code:
+  - language: yaml
+    label: "Grant explicit write permissions to GITHUB_TOKEN"
+    code: |
+      name: Release
+
+      on:
+        push:
+          branches:
+            - main
+
+      permissions:
+        contents: write
+
+      jobs:
+        release:
+          runs-on: ubuntu-latest
+          steps:
+            - uses: actions/checkout@v4
+            - run: git push origin HEAD:main
+prevention:
+  - "Assume `GITHUB_TOKEN` is read-only unless you explicitly grant the needed permission."
+  - "Set least-privilege `permissions:` blocks on every workflow instead of relying on defaults."
+  - "Match API usage to the smallest write scope required."
+docs:
+  - url: "https://docs.github.com/en/actions/security-guides/automatic-token-authentication"
+    label: "Automatic token authentication"
+  - url: "https://docs.github.com/en/actions/using-workflows/workflow-syntax-for-github-actions#permissions"
+    label: "permissions"
+source:
+  article: "https://htek.dev/articles/github-actions-debugging-guide"
+  section: "GITHUB_TOKEN 403 and read-only defaults"