From c485efc7822c6a8f0c09abe9e17b9daabd2fe5fa Mon Sep 17 00:00:00 2001 From: Hector Flores Date: Sat, 13 Jun 2026 09:58:33 -0500 Subject: [PATCH] feat: add 3 new error entries (caching-artifacts x1, runner-environment x2) Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com> --- .../alpine-busybox-tar-p-flag-unsupported.yml | 84 +++++++++++++ ...it-config-global-auth-placeholder-fail.yml | 89 ++++++++++++++ ...-docker-container-action-not-available.yml | 111 ++++++++++++++++++ 3 files changed, 284 insertions(+) create mode 100644 errors/caching-artifacts/alpine-busybox-tar-p-flag-unsupported.yml create mode 100644 errors/runner-environment/checkout-git-config-global-auth-placeholder-fail.yml create mode 100644 errors/runner-environment/checkout-v6-credentials-docker-container-action-not-available.yml diff --git a/errors/caching-artifacts/alpine-busybox-tar-p-flag-unsupported.yml b/errors/caching-artifacts/alpine-busybox-tar-p-flag-unsupported.yml new file mode 100644 index 0000000..c1d4131 --- /dev/null +++ b/errors/caching-artifacts/alpine-busybox-tar-p-flag-unsupported.yml @@ -0,0 +1,84 @@ +id: caching-artifacts-150 +title: 'actions/cache Fails in Alpine Containers — BusyBox tar Does Not Support -P Flag' +category: caching-artifacts +severity: error +tags: + - alpine + - busybox + - tar + - container + - cache + - linux +patterns: + - regex: 'tar: unrecognized option: P' + flags: 'i' + - regex: 'BusyBox.*?tar.*?unrecognized.*?option' + flags: 'i' + - regex: 'Tar failed with error: The process .*/bin/tar. failed with exit code 1' + flags: 'i' +error_messages: + - "/bin/tar: unrecognized option: P" + - "BusyBox v1.31.1 () multi-call binary." + - "[warning]Tar failed with error: The process '/bin/tar' failed with exit code 1" +root_cause: | + The `actions/cache` action uses GNU tar with the `-P` flag (preserve absolute path names) + when creating and extracting cache archives. Alpine Linux containers ship with BusyBox, + which provides a minimal tar implementation that does not recognise the `-P` flag. + + When the cache step runs inside an Alpine container, `/bin/tar` is BusyBox tar and the + command fails immediately with "unrecognized option: P". The restore step returns exit + code 1 and the workflow stops or the cache is silently skipped depending on fail-on-cache-miss. + + This is a long-standing issue first reported in actions/cache#352 and re-surfaced in + actions/cache#1765 (June 2026). No workaround has been added to the action itself. +fix: | + Install GNU tar in the Alpine container before the cache step using apk: + + steps: + - name: Install GNU tar (required for actions/cache) + run: apk add --no-cache tar + - name: Cache dependencies + uses: actions/cache@v4 + with: + path: ~/.cargo/registry + key: ${{ runner.os }}-cargo-${{ hashFiles('**/Cargo.lock') }} + + Alternatively, switch the job to a Debian/Ubuntu-based container image where + GNU tar is already the default (/usr/bin/tar). +fix_code: + - language: yaml + label: Install GNU tar in Alpine before using actions/cache + code: | + - name: Install GNU tar + run: apk add --no-cache tar + + - name: Cache dependencies + uses: actions/cache@v4 + with: + path: ~/.cargo/registry + key: ${{ runner.os }}-cargo-${{ hashFiles('**/Cargo.lock') }} + - language: yaml + label: Switch to Debian/Ubuntu container to avoid BusyBox tar + code: | + jobs: + build: + runs-on: ubuntu-latest + container: + image: debian:bookworm-slim # GNU tar available by default + steps: + - uses: actions/cache@v4 + with: + path: ~/.cargo/registry + key: ${{ runner.os }}-cargo-${{ hashFiles('**/Cargo.lock') }} +prevention: + - "Run tar --version inside your Alpine container; if it shows BusyBox, add apk add --no-cache tar as the first step." + - "Set container: debian:bookworm-slim or ubuntu:latest instead of alpine when the job uses actions/cache." + - "Add apk add --no-cache tar as the very first step in any job that uses actions/cache inside an Alpine container." + - "Check the actions/cache documentation for container compatibility notes before choosing a base image." +docs: + - url: "https://github.com/actions/cache/issues/1765" + label: "actions/cache issue #1765 — Post cache not working on alpine runners (2026)" + - url: "https://github.com/actions/cache/issues/352" + label: "actions/cache issue #352 — Original Alpine BusyBox tar report" + - url: "https://docs.github.com/en/actions/using-containerized-services/about-service-containers" + label: "GitHub Docs — About service containers" diff --git a/errors/runner-environment/checkout-git-config-global-auth-placeholder-fail.yml b/errors/runner-environment/checkout-git-config-global-auth-placeholder-fail.yml new file mode 100644 index 0000000..2c03885 --- /dev/null +++ b/errors/runner-environment/checkout-git-config-global-auth-placeholder-fail.yml @@ -0,0 +1,89 @@ +id: runner-environment-497 +title: 'actions/checkout Auth Setup Fails When GIT_CONFIG_GLOBAL Is Set in Runner Environment' +category: runner-environment +severity: error +tags: + - checkout + - git-config + - GIT_CONFIG_GLOBAL + - self-hosted + - auth + - submodules + - git-credentials +patterns: + - regex: 'Unable to replace auth placeholder in.*?\.gitconfig' + flags: 'i' + - regex: 'Error.*?Unable to replace.*?placeholder.*?gitconfig' + flags: 'i' + - regex: 'Failed to configure the global config' + flags: 'i' +error_messages: + - "##[error]Unable to replace auth placeholder in /home/runner/work/_temp//.gitconfig" + - "Error: Unable to replace auth placeholder" +root_cause: | + When actions/checkout sets up global git authentication (triggered by submodules: true, + persist-credentials: true, or private-repo checkout), it creates a temporary gitconfig + by following these steps: + + 1. Copies ~/.gitconfig into a temp directory (e.g. /home/runner/work/_temp//). + 2. Overrides the HOME environment variable to point at that temp directory. + 3. Writes an auth token placeholder via `git config --global url..insteadOf` + — expecting it to land in the temp config because HOME now points there. + 4. Reads the temp config back and replaces the placeholder with the real token. + + The problem: git honours GIT_CONFIG_GLOBAL OVER HOME when locating the global + config file. If GIT_CONFIG_GLOBAL is already set in the runner environment (a common + practice on self-hosted runners to isolate per-job git config), step 3 writes to + THAT file instead of the temp config. Step 4 reads the temp config, finds no + placeholder, and fails with "Unable to replace auth placeholder". + + This is an open bug in actions/checkout (issue #2449). The checkout action only + overrides HOME, but never pins GIT_CONFIG_GLOBAL. +fix: | + Unset GIT_CONFIG_GLOBAL for the checkout step using the step-level env block: + + - name: Checkout + uses: actions/checkout@v4 + env: + GIT_CONFIG_GLOBAL: "" # unset so checkout controls global config + with: + submodules: true + + If using actions/checkout@v6, also try persist-credentials: false combined with + manually configured HTTPS credentials. Track actions/checkout#2449 for an + official fix that pins GIT_CONFIG_GLOBAL alongside HOME. +fix_code: + - language: yaml + label: Unset GIT_CONFIG_GLOBAL for the checkout step + code: | + - name: Checkout + uses: actions/checkout@v4 + env: + GIT_CONFIG_GLOBAL: "" # prevent git from redirecting config writes + with: + submodules: true + token: ${{ secrets.GITHUB_TOKEN }} + - language: yaml + label: Unset at job level to protect all checkout steps + code: | + jobs: + build: + runs-on: self-hosted + env: + GIT_CONFIG_GLOBAL: "" # reset for all steps in this job + steps: + - uses: actions/checkout@v4 + with: + submodules: true +prevention: + - "Avoid setting GIT_CONFIG_GLOBAL at workflow or job level when using actions/checkout." + - "On self-hosted runners, use GIT_CONFIG_NOSYSTEM=1 instead of GIT_CONFIG_GLOBAL for job isolation where possible." + - "If GIT_CONFIG_GLOBAL must be set on the runner host, override it to an empty string in the checkout step env block." + - "Track actions/checkout#2449 and upgrade to the patched version once released." +docs: + - url: "https://github.com/actions/checkout/issues/2449" + label: "actions/checkout issue #2449 — Fix global auth when GIT_CONFIG_GLOBAL is set" + - url: "https://git-scm.com/docs/git-config#Documentation/git-config.txt-GITCONFIGGLOBAL" + label: "Git documentation — GIT_CONFIG_GLOBAL environment variable" + - url: "https://docs.github.com/en/actions/security-for-github-actions/security-guides/security-hardening-for-github-actions" + label: "GitHub Docs — Security hardening for GitHub Actions" diff --git a/errors/runner-environment/checkout-v6-credentials-docker-container-action-not-available.yml b/errors/runner-environment/checkout-v6-credentials-docker-container-action-not-available.yml new file mode 100644 index 0000000..7d757a1 --- /dev/null +++ b/errors/runner-environment/checkout-v6-credentials-docker-container-action-not-available.yml @@ -0,0 +1,111 @@ +id: runner-environment-498 +title: 'actions/checkout@v6 Persisted Credentials Not Available Inside Subsequent Docker Container Actions' +category: runner-environment +severity: error +tags: + - checkout + - checkout-v6 + - docker + - container-action + - credentials + - git-auth + - persist-credentials + - v6-regression +patterns: + - regex: 'fatal: could not read Username for .https://github\.com.: terminal prompts disabled' + flags: 'i' + - regex: 'fatal: repository .https://github\.com/.*?. not found' + flags: 'i' + - regex: 'remote: Repository not found\.' + flags: 'i' + - regex: 'Authentication failed for .https://github\.com' + flags: 'i' +error_messages: + - "fatal: could not read Username for 'https://github.com': terminal prompts disabled" + - "remote: Repository not found." + - "fatal: repository 'https://github.com///' not found" + - "Error: Authentication failed for 'https://github.com/'" +root_cause: | + actions/checkout@v6 introduced a new credential persistence mechanism that requires + runner v2.329.0+. In this design the checkout action stores git credentials via the + runner's credential-store rather than writing to the container's filesystem, enabling + persistent access across steps. + + However, subsequent DOCKER CONTAINER ACTIONS run inside an isolated container + filesystem that does not mount or inherit the host runner's credential store. Git + operations inside a Docker container action that attempt to authenticate against + GitHub will fail because: + + 1. The credential helper configured by checkout@v6 points to a host-side file or + socket that is not mounted inside the container. + 2. The container's git has no fallback credentials and interactive prompts are + disabled in CI (GIT_TERMINAL_PROMPT=0). + 3. Even with persist-credentials: true (the default), the container cannot read + the stored credentials. + + The v6-beta release notes stated that Docker container action support would be + available from runner v2.329.0+, but this was not fully implemented as of June 2026. + This is an open upstream bug (actions/checkout#2359). +fix: | + Downgrade to actions/checkout@v4 in any workflow that includes Docker container + actions that require git access. checkout@v4 stores credentials in ~/.git-credentials + on the host filesystem, which IS accessible to Docker container actions via the + default workspace mount. + + - name: Checkout + uses: actions/checkout@v4 # v4 credentials are accessible to Docker container actions + with: + fetch-depth: 0 + token: ${{ secrets.GITHUB_TOKEN }} + persist-credentials: true + + If v6 is required, pass the token to the Docker container action explicitly as an + environment variable and configure git inside the container manually. +fix_code: + - language: yaml + label: Downgrade to checkout@v4 when workflow uses Docker container actions + code: | + steps: + # v4 stores credentials in ~/.git-credentials accessible to Docker containers + - name: Checkout + uses: actions/checkout@v4 + with: + fetch-depth: 0 + token: ${{ secrets.GITHUB_TOKEN }} + persist-credentials: true + + # Docker container action can now access git credentials + - name: Run Docker container action + uses: org/docker-container-action@v1 + with: + token: ${{ secrets.GITHUB_TOKEN }} + - language: yaml + label: Pass token explicitly to Docker container action (v6 workaround) + code: | + steps: + - name: Checkout + uses: actions/checkout@v6 + with: + persist-credentials: false # disable v6 mechanism + + # Manually configure credentials accessible inside the container + - name: Configure git credentials + run: | + git config --global credential.helper store + echo "https://x-access-token:${{ secrets.GITHUB_TOKEN }}@github.com" \ + >> ~/.git-credentials + + - name: Run Docker container action + uses: org/docker-container-action@v1 +prevention: + - "Check the release notes before upgrading checkout versions in workflows that include Docker container actions." + - "Pin checkout to @v4 in workflows that use Docker container actions until actions/checkout#2359 is resolved." + - "After upgrading checkout versions, verify end-to-end in a test branch before rolling out to all workflows." + - "Track actions/checkout#2359 for the upstream fix and re-evaluate once it ships." +docs: + - url: "https://github.com/actions/checkout/issues/2359" + label: "actions/checkout issue #2359 — v6 credentials don't work with Docker container actions" + - url: "https://github.com/actions/checkout/releases/tag/v6.0.0" + label: "actions/checkout v6 release notes" + - url: "https://docs.github.com/en/actions/sharing-automations/creating-actions/creating-a-docker-container-action" + label: "GitHub Docs — Creating a Docker container action"