feat(run-digger-action): add digger-version input

action.yml

@@ -232,6 +232,10 @@ inputs:
     description: "(orchestrator only) the spec to pass onto digger cli"
     required: false
     default: ""
+  digger-version:
+    description: "Pre-compiled version of digger CLI to install. Must correspond to a valid release tag (vX.Y.Z). This value overrides the version derived from the github.action_ref."
+    required: false
+    default: ""
 
 outputs:
   output:
@@ -245,6 +249,30 @@ runs:
       run: echo digger run ${{ inputs.id }}
       shell: bash
 
+    - name: Determine binary mode (local, build, or pre-built)
+      id: determine-binary-mode
+      env:
+        LOCAL_DEV_MODE: ${{ inputs.local-dev-mode }}
+        INPUT_DIGGER_VERSION: ${{ inputs.digger-version }}
+        ACTION_REF: ${{ github.action_ref }}
+      run: |
+        set -euo pipefail
+
+        if [[ ! ( -z "$INPUT_DIGGER_VERSION" || "$INPUT_DIGGER_VERSION" =~ ^v[0-9]+\.[0-9]+\.[0-9]+$ ) ]]; then
+          echo "::error::Invalid digger-version input $INPUT_DIGGER_VERSION. Must be empty string or match vX.Y.Z"
+          exit 1
+        fi
+
+        if [[ "$LOCAL_DEV_MODE" == "true" ]]; then
+          BINARY_MODE="local"    # Use locally compiled binary (for development)
+        elif [[ -n "$INPUT_DIGGER_VERSION" || "$ACTION_REF" == v* ]]; then
+          BINARY_MODE="prebuilt" # Install prebuilt binary from release
+        else
+          BINARY_MODE="build"    # Build from source at runtime
+        fi
+        echo "binary-mode=${BINARY_MODE}" >> ${GITHUB_OUTPUT}
+      shell: bash
+
     - name: Validate Input Configuration for Google
       run: |
         if [[ -z ${{ toJSON(inputs.google-auth-credentials) }} && -z "${{ inputs.google-workload-identity-provider }}" ]]; then
@@ -257,7 +285,7 @@ runs:
         exit 1
       shell: bash
       if: inputs.setup-google-cloud == 'true'
-    - uses: actions/checkout@v4
+    - uses: actions/checkout@08eba0b27e820071cde6df949e0beb9ba4906955 # v4.3.0
       with:
         clean: false
         ref: refs/pull/${{ github.event.issue.number }}/merge
@@ -396,15 +424,15 @@ runs:
       with:
         go-version-file: "${{ github.action_path }}/cli/go.mod"
         cache: false
-      if: ${{ !startsWith(github.action_ref, 'v') }}
+      if: ${{ steps.determine-binary-mode.outputs.binary-mode != 'prebuilt' }}
 
     - name: Determine Golang cache paths
       id: golang-env
       run: |
         echo "build-cache-path=$(go env GOCACHE)" >>"$GITHUB_OUTPUT"
         echo "module-cache-path=$(go env GOMODCACHE)" >>"$GITHUB_OUTPUT"
       shell: bash
-      if: ${{ !startsWith(github.action_ref, 'v') }}
+      if: ${{ steps.determine-binary-mode.outputs.binary-mode != 'prebuilt' }}
 
     - name: Copy Digger CLI go.sum for cache key
       run: |
@@ -416,7 +444,7 @@ runs:
           cp "$GITHUB_ACTION_PATH/cli/go.sum" "$GITHUB_WORKSPACE/.digger.go.sum"
         fi
       shell: bash
-      if: ${{ !startsWith(github.action_ref, 'v') }}
+      if: ${{ steps.determine-binary-mode.outputs.binary-mode != 'prebuilt' }}
 
     - name: Adding required env vars for next step
       uses: actions/github-script@f28e40c7f34bde8b3046d885e986cb6290c5673b # v7.1.0
@@ -434,7 +462,7 @@ runs:
       shell: bash
 
     - name: build and run digger
-      if: ${{ !startsWith(github.action_ref, 'v') && inputs.local-dev-mode == 'false' }}
+      if: ${{ steps.determine-binary-mode.outputs.binary-mode == 'build' }}
       shell: bash
       env:
         PLAN_UPLOAD_DESTINATION: ${{ inputs.upload-plan-destination }}
@@ -485,10 +513,10 @@ runs:
         cd $GITHUB_WORKSPACE
         digger
 
-    - name: run digger
-      if: ${{ startsWith(github.action_ref, 'v') && inputs.local-dev-mode == 'false' }}
+    - name: download, install, and run digger
+      if: ${{ steps.determine-binary-mode.outputs.binary-mode == 'prebuilt' }}
       env:
-        actionref: ${{ github.action_ref }}
+        DIGGER_VERSION: ${{ inputs.digger-version || github.action_ref }}
         PLAN_UPLOAD_DESTINATION: ${{ inputs.upload-plan-destination }}
         PLAN_UPLOAD_S3_ENCRYPTION_ENABLED: ${{ inputs.upload-plan-destination-s3-encryption-enabled }}
         PLAN_UPLOAD_S3_ENCRYPTION_TYPE: ${{ inputs.upload-plan-destination-s3-encryption-type }}
@@ -525,16 +553,16 @@ runs:
         set -euo pipefail
 
         echo "🔧 Downloading Digger CLI..."
-        echo "Runner OS: ${{ runner.os }}, Arch: ${{ runner.arch }}, Action Ref: ${actionref}"
+        echo "Runner OS: ${{ runner.os }}, Arch: ${{ runner.arch }}, Digger Version: ${DIGGER_VERSION}"
 
         if [[ ${{ inputs.ee }} == "true" ]]; then
           if [[ ${{ inputs.fips }} == "true" ]]; then
-            DOWNLOAD_URL="https://github.com/diggerhq/digger/releases/download/${actionref}/digger-ee-cli-${{ runner.os }}-${{ runner.arch }}-fips"
+            DOWNLOAD_URL="https://github.com/diggerhq/digger/releases/download/${DIGGER_VERSION}/digger-ee-cli-${{ runner.os }}-${{ runner.arch }}-fips"
           else
-            DOWNLOAD_URL="https://github.com/diggerhq/digger/releases/download/${actionref}/digger-ee-cli-${{ runner.os }}-${{ runner.arch }}"
+            DOWNLOAD_URL="https://github.com/diggerhq/digger/releases/download/${DIGGER_VERSION}/digger-ee-cli-${{ runner.os }}-${{ runner.arch }}"
           fi
         else
-          DOWNLOAD_URL="https://github.com/diggerhq/digger/releases/download/${actionref}/digger-cli-${{ runner.os }}-${{ runner.arch }}"
+          DOWNLOAD_URL="https://github.com/diggerhq/digger/releases/download/${DIGGER_VERSION}/digger-cli-${{ runner.os }}-${{ runner.arch }}"
         fi
 
         echo "Downloading from: $DOWNLOAD_URL"
@@ -543,12 +571,12 @@ runs:
           echo "Failed to download Digger CLI from $DOWNLOAD_URL"
           echo ""
           echo "Possible reasons:"
-          echo "1. The release ${actionref} might not exist"
+          echo "1. The release ${DIGGER_VERSION} might not exist"
           echo "2. Binary for ${{ runner.os }}-${{ runner.arch }} might not be available"
           echo "3. Network connectivity issues"
           echo ""
           echo "Suggestions:"
-          echo "- Check if release ${actionref} exists at: https://github.com/diggerhq/digger/releases"
+          echo "- Check if release ${DIGGER_VERSION} exists at: https://github.com/diggerhq/digger/releases"
           echo "- Verify the architecture combination is supported"
           echo "- Try using a different release version"
           exit 1
@@ -572,9 +600,9 @@ runs:
         digger
 
     - name: run digger in local dev mode
-      if: ${{ inputs.local-dev-mode == 'true' }}
+      if: ${{ steps.determine-binary-mode.outputs.binary-mode == 'local' }}
       env:
-        actionref: ${{ github.action_ref }}
+        DIGGER_VERSION: ${{ github.action_ref }}
         PLAN_UPLOAD_DESTINATION: ${{ inputs.upload-plan-destination }}
         PLAN_UPLOAD_S3_ENCRYPTION_ENABLED: ${{ inputs.upload-plan-destination-s3-encryption-enabled }}
         PLAN_UPLOAD_S3_ENCRYPTION_TYPE: ${{ inputs.upload-plan-destination-s3-encryption-type }}

docs/ce/howto/versioning.mdx

@@ -1,50 +1,64 @@
 ---
-title: "Specifying version"
-description: "For serious usecases always use a pinned version which is of the form @vX.Y.Z since this will download a compiled binary. In addition to being faster to run, it is also more secure than using a commit from a branch"
+title: "Specifying Version"
 ---
 
 <Warning>
-  For serious usecases always use a pinned version which is of the form @vX.Y.Z
-  since this will download a compiled binary. In addition to being faster to run, it
-  is also more secure than using a commit from a branch
+  For production use cases it is best to pin the version of the action with the commit hash (e.g. `-uses: diggerhq/digger@<COMMIT_HASH>`) of the desired release 
+  AND specify the `digger-version` input to be a tagged release (`vX.Y.Z`). 
+
+  This provides the security of ensuring the same action code is executed each time with the performance of using a pre-compiled Digger binary.
 </Warning>
 
-## Use vLatest tag
+## Commit Hash + digger-version input (Production recommendation)
+
+For production usage, we recommend pinning the action to the commit hash of a released version AND specifying a Digger CLI version via the `digger-version` input.
 
-The default and recommended way of versioning Digger is to use the vLatest tag, which always points to the latest release. The difference compared to just specifying "latest" is that it is a release with pre-built binaries, so it is faster than building from a branch, which using "latest" effectively does.
+Specifying the action commit hash is the only way to ensure the same version of a GitHub Action is executed each time and helps protect against supply chain attacks such as [CVE-2025-30066](https://www.wiz.io/blog/github-action-tj-actions-changed-files-supply-chain-attack-cve-2025-30066).
+
+The `digger-version` input enables pinning to the hash while ALSO using a pre-built Digger cli binary.
 
 ```
 - name: digger
-  uses: diggerhq/digger@vX.Y.Z
-  env:
-    ...
+  uses: diggerhq/digger@<COMMIT_HASH_OF_TAGGED_RELEASE> # vX.Y.Z
+  with:
+    digger-version: vX.Y.Z
 ```
 
-## Use a pinned version
+## vLatest (Convenient auto-upgrades)
 
-To pin a specific release of Digger, you can use `@vX.Y.Z` tag in your workflow file:
+For non-production use cases, you can specify the `vLatest` tag to use the latest tagged release for the digger action and the Digger CLI.
+
+The difference compared to just specifying "latest" is that it is a release with pre-built binaries, so it is faster than building from a branch, which using "latest" effectively does.
 
 ```
 - name: digger
-  uses: diggerhq/digger@vX.Y.Z
-  env:
-    ...
+  uses: diggerhq/digger@vLatest
 ```
 
-## Use latest commit from a branch
+## vX.Y.Z (Simple and stable)
+
+If you aren't worried about supply chain attacks but want stability of using a specific release, you can pin the action to a specific release of Digger.
+
+This will infer the Digger cli version to use based on the version of the action using `github.action_ref` and install the corresponding pre-built binary.
+
+```
+- name: digger
+  uses: diggerhq/digger@vX.Y.Z
+```
 
-You can also run latest commit from a specific branch
+## Commit Hash Only (Build a specific CLI version from source at runtime)
 
-Only use this at your own risk in non-production scenarios. This can break things!
+If you want to use an unreleased version of the Digger CLI (e.g. test something on a feature branch or a yet to be released commit from `develop`),
+you can specify the action with that commit hash AND omit the `digger-version` input.
 
 <Warning>
-  Only use this at your own risk in non-production scenarios. This can break
-  things!
+  Only use this at your own risk in non-production scenarios. This can break things!
 </Warning>
 
 ```
 - name: digger
-  uses: diggerhq/digger@yolo-lets-do-it
-  env:
-    ...
+  uses: diggerhq/digger@<YOLO_COMMIT_HASH>
+  with:
+    # OMIT THE digger-version INPUT
+    # digger-input: ""
 ```