From 6a320e14c05f7dd6844ff4b76d8c659cfc84ca28 Mon Sep 17 00:00:00 2001 From: Mresyzz Date: Wed, 14 Oct 2026 00:34:25 +0800 Subject: [PATCH] docs: publish searchable installer verification guide with workflow download --- .github/workflows/deploy-pages.yml | 2 + docs/command-not-found.html | 3 +- docs/index.html | 2 +- docs/installer-smoke-test.html | 73 ++++++++++++++++++++++++++++++ docs/llms.txt | 1 + docs/sitemap.xml | 1 + 6 files changed, 80 insertions(+), 2 deletions(-) create mode 100644 docs/installer-smoke-test.html diff --git a/.github/workflows/deploy-pages.yml b/.github/workflows/deploy-pages.yml index 5097121..47317b9 100644 --- a/.github/workflows/deploy-pages.yml +++ b/.github/workflows/deploy-pages.yml @@ -25,6 +25,8 @@ jobs: uses: actions/checkout@v4 - name: Setup Pages uses: actions/configure-pages@v5 + - name: Stage downloadable installer workflow + run: cp examples/github-actions/installer-smoke.yml docs/installer-smoke.yml - name: Upload artifact uses: actions/upload-pages-artifact@v3 with: diff --git a/docs/command-not-found.html b/docs/command-not-found.html index e0f6b5e..85f118b 100644 --- a/docs/command-not-found.html +++ b/docs/command-not-found.html @@ -134,7 +134,7 @@

A complete GitHub Actions workflow

- uses: actions/checkout@v7 with: persist-credentials: false - - uses: Mresyzz/opsscript-gate@v0.9.2 + - uses: Mresyzz/opsscript-gate@v0.9.4 with: script-path: install.sh shell: auto @@ -186,6 +186,7 @@

Can I run the check without GitHub Actions?

troubleshooting, or security boundaries. Open the interactive demo. +

Installer returns zero but the program is missing? Verify the installed binary in the same container.

diff --git a/docs/index.html b/docs/index.html index 2439e31..75f1b2e 100644 --- a/docs/index.html +++ b/docs/index.html @@ -534,7 +534,7 @@

Testing a downloading installer? A zero exit code alone does not prove installation succeeded. - Use the installation smoke test guide + Use the installation smoke test guide to check the installed binary inside each container.

diff --git a/docs/installer-smoke-test.html b/docs/installer-smoke-test.html new file mode 100644 index 0000000..09c8c41 --- /dev/null +++ b/docs/installer-smoke-test.html @@ -0,0 +1,73 @@ + + + + + + Installer says success but binary is missing: test installation in CI | OpsScript Gate + + + + + + +
+

Your installer says success. Was the binary actually installed?

+

A failed download can leave an installer with nothing to extract. If the script + continues and ends with a successful echo, CI can turn green even + though the program is missing. Test the installation's result inside the same + container, not just the installer's exit code.

+

Make installation success explicit

+

After running the installer, check its expected binary and execute a harmless, + noninteractive smoke command. Adapt this path and command to your program:

+ 
binary="$HOME/.local/bin/mytool"
+test -x "$binary" || { echo "Installer did not create $binary" >&2; exit 1; }
+"$binary" --version
+

The binary and installer must be checked in the same container. + A separate step on the GitHub runner sees a different filesystem.

+

Add the four-distribution workflow

+

Download installer-smoke.yml

+
    +
  1. Save the workflow as .github/workflows/installer-smoke.yml.
    2. +
  2. Change install.sh to your standalone installer's path.
    3. +
  3. Replace $HOME/.local/bin/mytool and --version with + your installed binary and a smoke command that fails when it cannot start.
    4. +
  4. Review packages, timeout and supported images. Add packaging configuration + to the workflow's trigger paths when archive layout depends on it.
    5. +
  5. Open a pull request or run the workflow manually. Inspect the saved JSON + report for failed images.
    6. +
+

The workflow uses OpsScript Gate v0.9.4 to run Debian 12, Ubuntu 22.04/24.04 + and Alpine 3.20. It embeds the checked-out installer in a subshell, preserves + its failure status and runs the binary check afterwards. An explicit + exit 0 in the installer cannot skip the check.

+

Downloads require network access. The example provisions Bash, + curl, CA certificates and tar. That verifies installation with these prerequisites; + it does not prove the installer works on a bare image. Only the target script + is mounted, so installers requiring sibling repository files need another setup.

+

A real false-success case

+

In a public fork test of Latitude's CLI installer, + an Ubuntu 22.04 job downloaded content that was not gzip. Extraction and moving + the binary failed, but the installer still printed “Installation finished”. + The binary check correctly failed because $HOME/.lsh/lsh was absent.

+

A later run with installation checks passed all four images. + The earlier failure demonstrates why postconditions matter; it does not establish + an Ubuntu-specific defect. These are fork validations, not an upstream endorsement.

+

What a green result proves

+

The tested artifact installed and its smoke command succeeded in that container + during that run. HTTP errors, rate limits or changing release assets can affect + repeat runs. Containers share the host kernel; this is not a full-machine test + or a test of every application feature.

+

Read the source guide · + Diagnose missing commands and interpreters

+
+ + + diff --git a/docs/llms.txt b/docs/llms.txt index 69047af..4139f01 100644 --- a/docs/llms.txt +++ b/docs/llms.txt @@ -25,6 +25,7 @@ a ShellCheck companion, not a replacement for static analysis or a security sand ## Canonical pages - Runtime testing guide: https://mresyzz.github.io/opsscript-gate/command-not-found.html +- Verify installation results: https://mresyzz.github.io/opsscript-gate/installer-smoke-test.html - Problem-first guide: https://github.com/Mresyzz/opsscript-gate/blob/main/docs/command-not-found.md - README and copyable workflow: https://github.com/Mresyzz/opsscript-gate#quickstart - Troubleshooting: https://github.com/Mresyzz/opsscript-gate/blob/main/docs/troubleshooting.md diff --git a/docs/sitemap.xml b/docs/sitemap.xml index f4ca861..53eb407 100644 --- a/docs/sitemap.xml +++ b/docs/sitemap.xml @@ -2,4 +2,5 @@ https://mresyzz.github.io/opsscript-gate/ https://mresyzz.github.io/opsscript-gate/command-not-found.html + https://mresyzz.github.io/opsscript-gate/installer-smoke-test.html