Fail action on invalid ESP-IDF version tags instead of continuing silently

[Copilot]

When an invalid ESP-IDF version tag is provided (e.g., 5.5.1 instead of v5.5.1), EIM logs an error but returns exit code 0, causing the action to continue and create a broken installation that appears successful.

Changes

• Error detection: Capture stderr from EIM execution and detect error patterns ("Failed to checkout reference", "did not exist", "ERROR" with tag/reference keywords)
• Explicit failure: Throw descriptive error with version format guidance when invalid tags are detected
• Test coverage: Add workflow job that validates action fails on invalid version input
• Documentation: Clarify version format requirements in inputs table and common issues section

Example

Before:

- uses: espressif/install-esp-idf-action@v1
  with:
    version: '5.5.1'  # Silently fails, continues with broken install

After:

- uses: espressif/install-esp-idf-action@v1
  with:
    version: '5.5.1'  # Fails with: "...may not exist. Please check that the version tag is correct (e.g., 'v5.5.1' instead of '5.5.1')"

Original prompt

---

This section details on the original issue you should resolve

<issue_title>Incorrect tag fails silently (RDT-1591)</issue_title>
<issue_description>### Checklist

• Checked the issue tracker for similar issues to ensure this is not a duplicate
• Read the documentation to confirm the issue is not addressed there and your configuration is set correctly
• Tested with the latest version to ensure the issue hasn't been fixed

How often does this bug occurs?

always

Expected behavior

Ideally, if any version tag does not exist, we should exit with non-zero exit-code.

Actual behavior (suspected bug)

In my case, I used 5.5.1 even though the correct version input should have been v5.5.1. Instead of throwing error, it goes on to give an illusion that 5.5.1 is correctly installed (judging from the file paths). The idf.py --version output:

Run idf.py --version
  idf.py --version
  shell: /usr/bin/bash --noprofile --norc -e -o pipefail {0}
  env:
    SYSTEM_PATH: /snap/bin:/home/runner/.local/bin:/opt/pipx_bin:/home/runner/.cargo/bin:/home/runner/.config/composer/vendor/bin:/usr/local/.ghcup/bin:/home/runner/.dotnet/tools:/usr/local/sbin:/usr/local/bin:/usr/sbin:/usr/bin:/sbin:/bin:/usr/games:/usr/local/games:/snap/bin:/tmp/esp/idf/5.5.1/esp-idf
    ESP_IDF_VERSION: 6.1
    IDF_TOOLS_PATH: /tmp/esp
    IDF_PATH: /tmp/esp/idf/5.5.1/esp-idf
    ESP_ROM_ELF_DIR: /tmp/esp/esp-rom-elfs/20241011
    OPENOCD_SCRIPTS: /tmp/esp/openocd-esp32/v0.12.0-esp32-20251215/openocd-esp32/share/openocd/scripts
    IDF_PYTHON_ENV_PATH: /tmp/esp/python/5.5.1/venv
fatal: No names found, cannot describe anything.
WARNING: Git version unavailable, reading from source
ESP-IDF v6.1.0

The installation logs correctly indicate that the tag does not exist but I think the more appropriate behaviour is to fail:

2025-12-29T12:21:12.797604104+00:00 - ERROR - Failed to checkout reference: The reference 'refs/tags/5.5.1' did not exist

Error logs or terminal output

/usr/bin/which apt-get
/usr/bin/apt-get
/usr/bin/sudo apt-get update
Get:1 file:/etc/apt/apt-mirrors.txt Mirrorlist [144 B]
Hit:2 http://azure.archive.ubuntu.com/ubuntu noble InRelease
Hit:6 https://packages.microsoft.com/repos/azure-cli noble InRelease
Get:7 https://packages.microsoft.com/ubuntu/24.04/prod noble InRelease [3600 B]
Get:3 http://azure.archive.ubuntu.com/ubuntu noble-updates InRelease [126 kB]
Get:4 http://azure.archive.ubuntu.com/ubuntu noble-backports InRelease [126 kB]
Get:5 http://azure.archive.ubuntu.com/ubuntu noble-security InRelease [126 kB]
Get:8 https://packages.microsoft.com/ubuntu/24.04/prod noble/main arm64 Packages [58.9 kB]
Get:9 https://packages.microsoft.com/ubuntu/24.04/prod noble/main armhf Packages [11.4 kB]
Get:10 https://packages.microsoft.com/ubuntu/24.04/prod noble/main amd64 Packages [77.2 kB]
Get:11 http://azure.archive.ubuntu.com/ubuntu noble-updates/main amd64 Packages [1684 kB]
Get:12 http://azure.archive.ubuntu.com/ubuntu noble-updates/main Translation-en [311 kB]
Get:13 http://azure.archive.ubuntu.com/ubuntu noble-updates/main amd64 Components [175 kB]
Get:14 http://azure.archive.ubuntu.com/ubuntu noble-updates/main amd64 c-n-f Metadata [15.8 kB]
Get:15 http://azure.archive.ubuntu.com/ubuntu noble-updates/universe amd64 Packages [1506 kB]
Get:16 http://azure.archive.ubuntu.com/ubuntu noble-updates/universe Translation-en [306 kB]
Get:17 http://azure.archive.ubuntu.com/ubuntu noble-updates/universe amd64 Components [378 kB]
Get:18 http://azure.archive.ubuntu.com/ubuntu noble-updates/universe amd64 c-n-f Metadata [31.4 kB]
Get:19 http://azure.archive.ubuntu.com/ubuntu noble-updates/restricted amd64 Packages [2413 kB]
Get:20 http://azure.archive.ubuntu.com/ubuntu noble-updates/restricted Translation-en [550 kB]
Get:21 http://azure.archive.ubuntu.com/ubuntu noble-updates/restricted amd64 Components [212 B]
Get:22 http://azure.archive.ubuntu.com/ubuntu noble-updates/restricted amd64 c-n-f Metadata [516 B]
Get:23 http://azure.archive.ubuntu.com/ubuntu noble-updates/multiverse amd64 Packages [30.3 kB]
Get:24 http://azure.archive.ubuntu.com/ubuntu noble-updates/multiverse Translation-en [6048 B]
Get:25 http://azure.archive.ubuntu.com/ubuntu noble-updates/multiverse amd64 Components [940 B]
Get:26 http://azure.archive.ubuntu.com/ubuntu noble-updates/multiverse amd64 c-n-f Metadata [488 B]
Get:27 http://azure.archive.ubuntu.com/ubuntu noble-backports/main amd64 Packages [40.4 kB]
Get:28 http://azure.archive.ubuntu.com/ubuntu noble-backports/main amd64 Components [7284 B]
Get:29 http://azure.archive.ubuntu.com/ubuntu noble-backports/main amd64 c-n-f Metadata [368 B]
Get:30 http://azure.archive.ubuntu.com/ubuntu noble-backports/universe amd64 Packages [29.5 kB]
Get:31 http://azure.archive.ubuntu.com/ubuntu noble-backports/universe Translation-en [17.9 kB]
Get:32 http://azure.archive.ubuntu.com/ubuntu noble-backports/universe amd64 Components [10.5 kB]
Get:33 http://azure.archive.ubu...

</details>



<!-- START COPILOT CODING AGENT SUFFIX -->

- Fixes espressif/install-esp-idf-action#11

<!-- START COPILOT CODING AGENT TIPS -->
---

✨ Let Copilot coding agent [set things up for you](https://github.com/espressif/install-esp-idf-action/issues/new?title=✨+Set+up+Copilot+instructions&body=Configure%20instructions%20for%20this%20repository%20as%20documented%20in%20%5BBest%20practices%20for%20Copilot%20coding%20agent%20in%20your%20repository%5D%28https://gh.io/copilot-coding-agent-tips%29%2E%0A%0A%3COnboard%20this%20repo%3E&assignees=copilot) — coding agent works faster and does higher quality work when set up for your repo.

[Hahihula]

Great work! Thanks for the fix!