Let a GitHub Action Download the Right Prebuilt Binary

If your GitHub Action runs a compiled program, it can download a prebuilt binary instead of building it on every run. To pick the right release, it needs to know which version the workflow asked for, the v0 in uses: owner/action@v0.

GitHub has a variable for this, github.action_ref, but it can be empty or hold another action’s version. The path to the action’s own code is more reliable. The runner downloads that code to a folder named after the version and gives the action’s steps its path in $GITHUB_ACTION_PATH.

Who’s who

I recently built rotguard , a link checker that rewrites redirected and dead links. It runs on this blog every week. Each run involves 3 things:

Download or build

rotguard is written in Rust, so it needs a binary on the runner before it can check any links. Building it from source took 22 to 36 seconds with a warm build cache and about 2.5 minutes without one. Downloading and installing it from a GitHub release took about a second.

Whether rotguard downloads the binary or builds it depends on what comes after @ in the workflow’s uses: line. That value is a git ref, such as a tag (v0), a branch (main) or a commit SHA. For @v0, rotguard downloads the binary for the release that v0 points to. For @main, it builds from source.

Why github.action_ref isn’t enough

GitHub puts the ref in github.action_ref. In a composite action like rotguard, it has 2 problems:

Reading the ref from the folder path

Before the job starts, the runner downloads rotguard’s code to a folder whose path ends with the ref. For @v0, the path looks like this:

/home/runner/work/_actions/rdiachenko/rotguard/v0

rotguard’s steps get this path in $GITHUB_ACTION_PATH and use it to find files such as Cargo.toml. The ref is the part of that path after _actions/<owner>/<repo>/:

ref="${GITHUB_ACTION_PATH#*/_actions/*/*/}"

If a branch name contains a slash, reading only what comes after the final / gives you an incomplete ref. A branch called release/v0.2.0 gets this path:

/home/runner/work/_actions/rdiachenko/rotguard/release/v0.2.0

Reading only v0.2.0 would make rotguard try to download a release binary instead of building the branch, because v0.2.0 looks like a release tag. The # expansion removes the shortest prefix that matches the pattern. Here that prefix ends at rotguard/, leaving the full ref release/v0.2.0.

Figure 1 shows the whole run. Either way, the binary ends up where the last step expects it.

Flowchart: the workflow uses rotguard@v0 and starts the job; the runner downloads rotguard's code to a folder named v0; if the ref looks like a release tag, rotguard downloads the binary from GitHub Releases in under 1 s, otherwise it builds it; either way rotguard then runs the binary.
Figure 1. One run of rdiachenko/rotguard@v0, from the workflow’s uses: line to the step that runs the binary

The download step

Here’s the first step from rotguard’s action.yml , with the error messages omitted and shorter curl flags. It tries to download a binary if the ref looks like a release tag (v0 or v0.3.0) and the runner is on Linux with an x64 or ARM64 CPU. Otherwise, it sets mode=build:

rotguard/action.yml
- id: fetch
  shell: bash
  run: |
    ref="${GITHUB_ACTION_PATH#*/_actions/*/*/}"
    ref_pattern='^v[0-9]+(\.[0-9]+\.[0-9]+)?$'
    target=''
    if [[ $RUNNER_OS == Linux && $ref =~ $ref_pattern ]]; then
      case "$RUNNER_ARCH" in
        X64) target=x86_64-unknown-linux-musl ;;
        ARM64) target=aarch64-unknown-linux-musl ;;
      esac
    fi
    if [ -z "$target" ]; then
      echo "mode=build" >> "$GITHUB_OUTPUT"
      exit 0
    fi
    version=$("$GITHUB_ACTION_PATH/scripts/cargo-version.sh" "$GITHUB_ACTION_PATH/Cargo.toml")
    asset="rotguard-$version-$target"
    base="https://github.com/rdiachenko/rotguard/releases/download/v$version"
    cd "$RUNNER_TEMP"
    curl -fsSL --retry 3 --max-time 120 -o "$asset" "$base/$asset"
    curl -fsSL --retry 3 --max-time 120 -o SHA256SUMS "$base/SHA256SUMS"
    grep -F " $asset" SHA256SUMS | sha256sum -c -
    mkdir -p "$GITHUB_ACTION_PATH/target/release"
    install -m 755 "$asset" "$GITHUB_ACTION_PATH/target/release/rotguard"
    echo "mode=release" >> "$GITHUB_OUTPUT"

Where the version comes from

The v0 in the uses: line does more than pass the pattern check. It decides which commit of rotguard the runner downloads. v0 is a tag that moves to each new 0.x release, and today it points at the “Release 0.3.0” commit. The runner’s log shows it:

Download action repository 'rdiachenko/rotguard@v0'
  (SHA:8bd224b18bc8cf10c1cbfc8239f3f4d8113b17bc)

The Cargo.toml in that commit says version = "0.3.0", so the fetch step asks for rotguard-0.3.0-x86_64-unknown-linux-musl. With @v0.2.1, the runner downloads the commit tagged v0.2.1, and the step gets the 0.2.1 binary. The name v0 stays the same across releases, so the step gets the exact version from the Cargo.toml that came with the code.

This only works if the release binaries are available before v0 moves. rotguard’s release workflow runs when a vX.Y.Z tag is pushed. It checks the tag against Cargo.toml, builds both Linux binaries, publishes them with SHA256SUMS, and moves v0 to the new commit last. If it moved v0 to the 0.4.0 commit first, a job could pick up that commit, read 0.4.0 from Cargo.toml, and try to download a binary that doesn’t exist yet.

The result

Here’s how long it took to get the binary ready in the same weekly job before and after switching to @v0.

@main, cold cache   2.5 min     install Rust, build
@main, warm cache   22-36 s     install Rust, restore the cache, build
@v0                 0.4-1.0 s   download, check the checksum, install

This relies on the runner’s folder layout. If the layout changes and rotguard stops finding a ref that looks like a release tag, it builds from the code the runner downloaded. That takes longer, but the job still runs the requested version.

Also available via RSS, YouTube, Telegram, or X (@rdiachenko)
Questions or ideas? Email me