feat(ci): official composite GitHub Action to install bashunit (#695)

Chemaclass · web-flow · commit 01961bea44af · 2026-06-07T16:33:00.000+02:00
diff --git a/.github/workflows/test-action.yml b/.github/workflows/test-action.yml
@@ -0,0 +1,48 @@
+name: Test action
+
+on:
+  pull_request:
+    paths:
+      - 'action.yml'
+      - 'install.sh'
+      - '.github/workflows/test-action.yml'
+  push:
+    branches:
+      - main
+
+concurrency:
+  group: test-action-${{ github.workflow }}-${{ github.ref }}
+  cancel-in-progress: ${{ github.ref != 'refs/heads/main' }}
+
+permissions:
+  contents: read
+
+jobs:
+  test-action:
+    name: "Install via action - ${{ matrix.os }}"
+    runs-on: ${{ matrix.os }}
+    timeout-minutes: 10
+    strategy:
+      fail-fast: false
+      matrix:
+        os: [ubuntu-latest, macos-latest]
+    steps:
+      - uses: actions/checkout@v4
+
+      - name: Install bashunit via the action
+        id: bashunit
+        uses: ./
+        with:
+          version: latest
+          directory: vendor/bashunit
+
+      - name: Verify the binary is installed and runnable
+        env:
+          BASHUNIT_PATH: ${{ steps.bashunit.outputs.path }}
+          BASHUNIT_INSTALLED_VERSION: ${{ steps.bashunit.outputs.version }}
+        run: |
+          set -euo pipefail
+          test -x "$BASHUNIT_PATH"
+          test -n "$BASHUNIT_INSTALLED_VERSION"
+          # add-to-path defaults to true, so "bashunit" resolves on PATH
+          bashunit --version
diff --git a/CHANGELOG.md b/CHANGELOG.md
@@ -2,6 +2,14 @@
 
 ## Unreleased
 
+### Added
+- Official `TypedDevs/bashunit` GitHub Action: composite action to install bashunit, pinnable by commit SHA for immutable, zizmor-friendly installs (`add-to-path` and `verify-checksum` inputs, `path`/`version` outputs)
+- `install.sh` optional sha256 checksum verification via `BASHUNIT_VERIFY_CHECKSUM=true` (validates the download against the release `checksum` asset)
+
+### Fixed
+- `install.sh` creates nested target directories (`mkdir -p`), so non-existing parent folders no longer fail the install
+- `install.sh` now fails loudly (non-zero exit, no bogus binary) when a version cannot be downloaded, instead of silently reporting success
+
 ## [0.37.0](https://github.com/TypedDevs/bashunit/compare/0.36.0...0.37.0) - 2026-06-03
 
 ### Added
diff --git a/action.yml b/action.yml
@@ -0,0 +1,64 @@
+name: Install bashunit
+description: Install the bashunit testing framework binary at a pinned, immutable version.
+author: TypedDevs
+
+branding:
+  icon: check-circle
+  color: green
+
+inputs:
+  version:
+    description: 'bashunit version to install (e.g. "0.37.0") or "latest".'
+    required: false
+    default: latest
+  directory:
+    description: 'Directory, relative to the workspace, where the bashunit binary is installed.'
+    required: false
+    default: lib
+  add-to-path:
+    description: 'Add the install directory to $GITHUB_PATH so you can run "bashunit" directly.'
+    required: false
+    default: 'true'
+  verify-checksum:
+    description: 'Verify the downloaded binary against the release sha256 checksum asset.'
+    required: false
+    default: 'true'
+
+outputs:
+  path:
+    description: Path to the installed bashunit binary, relative to the workspace.
+    value: ${{ steps.install.outputs.path }}
+  version:
+    description: The installed bashunit version (e.g. "0.37.0").
+    value: ${{ steps.install.outputs.version }}
+
+runs:
+  using: composite
+  steps:
+    - id: install
+      shell: bash
+      env:
+        BASHUNIT_VERSION: ${{ inputs.version }}
+        BASHUNIT_DIRECTORY: ${{ inputs.directory }}
+        BASHUNIT_ADD_TO_PATH: ${{ inputs.add-to-path }}
+        BASHUNIT_VERIFY_CHECKSUM: ${{ inputs.verify-checksum }}
+        BASHUNIT_ACTION_PATH: ${{ github.action_path }}
+      run: |
+        set -euo pipefail
+
+        target_dir="$BASHUNIT_DIRECTORY"
+        case "$target_dir" in
+          /*) ;;
+          *) target_dir="$GITHUB_WORKSPACE/$target_dir" ;;
+        esac
+
+        "$BASHUNIT_ACTION_PATH/install.sh" "$target_dir" "$BASHUNIT_VERSION"
+
+        echo "path=$BASHUNIT_DIRECTORY/bashunit" >> "$GITHUB_OUTPUT"
+
+        version="$(NO_COLOR=1 "$target_dir/bashunit" --version | awk 'NR==1{print $NF}')"
+        echo "version=$version" >> "$GITHUB_OUTPUT"
+
+        if [ "$BASHUNIT_ADD_TO_PATH" = "true" ]; then
+          echo "$target_dir" >> "$GITHUB_PATH"
+        fi
diff --git a/docs/installation.md b/docs/installation.md
@@ -222,7 +222,38 @@ Downloading 'bashunit' to 'lib'...
 
 ## GitHub Actions
 
+The official `TypedDevs/bashunit` action installs the binary in one step.
+Pin it to a commit SHA for an immutable, supply-chain-safe install
+(keeps static analyzers such as [zizmor](https://github.com/woodruffw/zizmor) happy):
+
 ::: code-group
+```yaml-vue [via action]
+# .github/workflows/bashunit-tests.yml
+name: Tests
+on: [pull_request, push]
+jobs:
+  tests:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+      # Pin to a commit SHA; the comment tracks the human-readable tag.
+      - uses: TypedDevs/bashunit@<commit-sha> # {{ pkg.version }}
+        with:
+          version: '{{ pkg.version }}' # or "latest" (default)
+          directory: lib               # optional, "lib" by default
+          add-to-path: 'true'          # optional, "true" by default
+          verify-checksum: 'true'      # optional, "true" by default
+      # add-to-path puts the binary on $PATH, so just call "bashunit":
+      - run: bashunit tests
+```
+
+**Inputs:** `version` (default `latest`), `directory` (default `lib`), `add-to-path` (default `true`), `verify-checksum` (default `true`).
+**Outputs:** `path` (binary path relative to the workspace), `version` (installed version).
+
+`verify-checksum` validates the downloaded binary against the release `checksum`
+asset (sha256) and fails the install on any mismatch. Set it to `false` only when
+pinning a release published before checksum assets existed.
+
 ```yaml [via install.sh]
 # .github/workflows/bashunit-tests.yml
 name: Tests
diff --git a/install.sh b/install.sh
@@ -11,6 +11,55 @@ function is_git_installed() {
   command -v git >/dev/null 2>&1
 }
 
+function compute_sha256() {
+  if command -v shasum >/dev/null 2>&1; then
+    shasum -a 256 "$1" | awk '{print $1}'
+  elif command -v sha256sum >/dev/null 2>&1; then
+    sha256sum "$1" | awk '{print $1}'
+  else
+    echo ""
+  fi
+}
+
+# Verify the downloaded 'bashunit' file against the release 'checksum' asset.
+# Arguments: $1 - the bashunit download URL. Exits 1 (and removes the binary)
+# on any failure so a tampered or unverifiable download never looks successful.
+function verify_checksum() {
+  local url=$1
+  local checksum_url="${url%/bashunit}/checksum"
+
+  local expected
+  if command -v curl >/dev/null 2>&1; then
+    expected=$(curl -fsSL --retry 3 --retry-delay 2 "$checksum_url" 2>/dev/null | awk '{print $1}')
+  else
+    expected=$(wget -qO- "$checksum_url" 2>/dev/null | awk '{print $1}')
+  fi
+
+  if [ -z "$expected" ]; then
+    echo "Error: could not download checksum from $checksum_url" >&2
+    rm -f bashunit
+    exit 1
+  fi
+
+  local actual
+  actual=$(compute_sha256 bashunit)
+  if [ -z "$actual" ]; then
+    echo "Error: no sha256 tool (shasum/sha256sum) available to verify checksum" >&2
+    rm -f bashunit
+    exit 1
+  fi
+
+  if [ "$actual" != "$expected" ]; then
+    echo "Error: checksum mismatch for bashunit '$TAG'" >&2
+    echo "  expected: $expected" >&2
+    echo "  actual:   $actual" >&2
+    rm -f bashunit
+    exit 1
+  fi
+
+  echo "> Checksum verified ($actual)"
+}
+
 function build_and_install_beta() {
   echo "> Downloading non-stable version: 'beta'"
 
@@ -44,13 +93,25 @@ function install() {
     echo "> Downloading the latest version: '$TAG'"
   fi
 
+  local url="$BASHUNIT_GIT_REPO/releases/download/$TAG/bashunit"
   if command -v curl >/dev/null 2>&1; then
-    curl -L -O -J "$BASHUNIT_GIT_REPO/releases/download/$TAG/bashunit" 2>/dev/null
+    curl -fL --retry 3 --retry-delay 2 -O -J "$url" 2>/dev/null
   elif command -v wget >/dev/null 2>&1; then
-    wget "$BASHUNIT_GIT_REPO/releases/download/$TAG/bashunit" 2>/dev/null
+    wget --tries=3 "$url" 2>/dev/null || wget "$url" 2>/dev/null
   else
-    echo "Cannot download bashunit: curl or wget not found."
+    echo "Cannot download bashunit: curl or wget not found." >&2
+    exit 1
   fi
+
+  if [ ! -f "bashunit" ]; then
+    echo "Error: failed to download bashunit '$TAG' from $url" >&2
+    exit 1
+  fi
+
+  if [ "${BASHUNIT_VERIFY_CHECKSUM:-false}" = "true" ]; then
+    verify_checksum "$url"
+  fi
+
   chmod u+x "bashunit"
 }
 
@@ -92,7 +153,7 @@ TAG="$LATEST_BASHUNIT_VERSION"
 
 cd "$(dirname "$0")"
 rm -f "$DIR"/bashunit
-[ -d "$DIR" ] || mkdir "$DIR"
+[ -d "$DIR" ] || mkdir -p "$DIR"
 cd "$DIR"
 
 if [[ $VERSION == 'beta' ]]; then
diff --git a/tests/acceptance/install_test.sh b/tests/acceptance/install_test.sh
@@ -29,11 +29,13 @@ function tear_down_after_script() {
 function set_up() {
   rm -f ./lib/bashunit
   rm -f ./deps/bashunit
+  rm -rf ./tmp_install
 }
 
 function tear_down() {
   rm -f ./lib/bashunit
   rm -f ./deps/bashunit
+  rm -rf ./tmp_install
 }
 
 function test_install_downloads_the_latest_version() {
@@ -49,6 +51,9 @@ function test_install_downloads_the_latest_version() {
 
   output="$(./install.sh)"
 
+  if [ ! -f "$installed_bashunit" ]; then
+    bashunit::skip "transient download failure" && return
+  fi
   assert_string_starts_with "$(printf "> Downloading the latest version: '")" "$output"
   assert_string_ends_with "$(printf "\n> bashunit has been installed in the 'lib' folder")" "$output"
   assert_file_exists "$installed_bashunit"
@@ -75,6 +80,9 @@ function test_install_downloads_in_given_folder() {
 
   output="$(./install.sh deps)"
 
+  if [ ! -f "$installed_bashunit" ]; then
+    bashunit::skip "transient download failure" && return
+  fi
   assert_string_starts_with "$(printf "> Downloading the latest version: '")" "$output"
   assert_string_ends_with "$(printf "\n> bashunit has been installed in the 'deps' folder")" "$output"
   assert_file_exists "$installed_bashunit"
@@ -88,6 +96,63 @@ function test_install_downloads_in_given_folder() {
   assert_string_starts_with "$(printf "\e[1m\e[32mbashunit\e[0m - ")" "$version"
 }
 
+function test_install_downloads_in_nested_folder() {
+  if [[ "$ACTIVE_INTERNET" -eq 1 ]]; then
+    bashunit::skip "no internet connection" && return
+  fi
+  if [[ "$HAS_DOWNLOADER" -eq 0 ]]; then
+    bashunit::skip "curl or wget not installed" && return
+  fi
+
+  local installed_bashunit="./tmp_install/nested/bashunit"
+  local output
+
+  output="$(./install.sh tmp_install/nested)"
+
+  if [ ! -f "$installed_bashunit" ]; then
+    bashunit::skip "transient download failure" && return
+  fi
+  assert_string_ends_with \
+    "$(printf "\n> bashunit has been installed in the 'tmp_install/nested' folder")" \
+    "$output"
+  assert_file_exists "$installed_bashunit"
+}
+
+function test_install_fails_loudly_on_unknown_version() {
+  if [[ "$ACTIVE_INTERNET" -eq 1 ]]; then
+    bashunit::skip "no internet connection" && return
+  fi
+  if [[ "$HAS_DOWNLOADER" -eq 0 ]]; then
+    bashunit::skip "curl or wget not installed" && return
+  fi
+
+  assert_general_error "$(./install.sh tmp_install 99.99.99 2>&1)"
+  assert_file_not_exists "./tmp_install/bashunit"
+}
+
+function test_install_verifies_checksum_when_enabled() {
+  if [[ "$ACTIVE_INTERNET" -eq 1 ]]; then
+    bashunit::skip "no internet connection" && return
+  fi
+  if [[ "$HAS_DOWNLOADER" -eq 0 ]]; then
+    bashunit::skip "curl or wget not installed" && return
+  fi
+  if ! command -v shasum >/dev/null 2>&1 && ! command -v sha256sum >/dev/null 2>&1; then
+    bashunit::skip "no sha256 tool available" && return
+  fi
+
+  local output
+  output="$(BASHUNIT_VERIFY_CHECKSUM=true ./install.sh tmp_install 0.37.0 2>&1)"
+
+  if [ ! -f "./tmp_install/bashunit" ]; then
+    bashunit::skip "transient download failure" && return
+  fi
+  assert_contains "Checksum verified" "$output"
+  assert_file_exists "./tmp_install/bashunit"
+  assert_same "$(printf "\e[1m\e[32mbashunit\e[0m - 0.37.0")" \
+    "$(./tmp_install/bashunit --version)"
+}
+
 function test_install_downloads_the_given_version() {
   if [[ "$ACTIVE_INTERNET" -eq 1 ]]; then
     bashunit::skip "no internet connection" && return
@@ -101,6 +166,9 @@ function test_install_downloads_the_given_version() {
 
   output="$(./install.sh lib 0.9.0)"
 
+  if [ ! -f "$installed_bashunit" ]; then
+    bashunit::skip "transient download failure" && return
+  fi
   local expected
   expected="> Downloading a concrete version: '0.9.0'
 > bashunit has been installed in the 'lib' folder"
@@ -125,6 +193,9 @@ function test_install_downloads_the_given_version_without_dir() {
   local output
   output="$(./install.sh 0.19.0)"
 
+  if [ ! -f "$installed_bashunit" ]; then
+    bashunit::skip "transient download failure" && return
+  fi
   assert_same \
     "$(
       printf "%s\n" \
@@ -163,6 +234,9 @@ function test_install_downloads_the_non_stable_beta_version() {
 
   output="$(./install.sh deps beta)"
 
+  if [ ! -f "$installed_bashunit" ]; then
+    bashunit::skip "transient download failure" && return
+  fi
   local expected
   expected="> Downloading non-stable version: 'beta'
 > bashunit has been installed in the 'deps' folder"
