Skip to content

README.md

Latest commit

 

History

History
123 lines (99 loc) · 5.25 KB

README.md

File metadata and controls

123 lines (99 loc) · 5.25 KB

ghr install composite action

Install one or more tools from GitHub releases inside a workflow, and cache the results across runs.

- uses: cataggar/ghr/actions/install@v0.3.0  # pin to the matching ghr release
  with:
    tools: |
      BurntSushi/ripgrep@14.1.1
      sharkdp/fd@v10.2.0

Each line of tools: is either spec or spec <minisign-pubkey> (a single whitespace-separated pair). An inline key requests minisign verification for that one spec and overrides the action-level minisign: default. Empty lines and # comments are ignored.

The action ships in the same git repository as ghr and shares its release stream: a tag like v0.3.0 pins both the action body and the ghr-bin PyPI package the action installs. Pick the tag from the releases page; pin to a specific commit SHA for full reproducibility.

A cache-hit on subsequent runs restores the tool directory and skips the install entirely. The cache key is os + arch + sorted(tools, including inline keys) + ghr version, so adding a tool, changing a tool's inline key, or bumping the action's tag invalidates the cache cleanly.

Inputs

Input Default Description
tools (required) Newline-separated entries. Each entry is owner/repo[@tag] (or owner/repo/file[@tag]), optionally followed by a single whitespace-separated minisign pubkey. Empty lines and lines starting with # are ignored.
cache true Cache the installed tools across runs.
minisign (empty) Default base64 minisign public key applied to every tools: line that does not include its own inline key. When set, ghr requires a .minisig sidecar (fail-closed). Inline per-spec keys override this default for that one spec.
skip-verify false Umbrella: skip every verification step (checksum, minisign, sigstore, authenticode).
skip-checksum false Skip just the checksum-sidecar verification step.
skip-minisign false Skip just the minisign verification step. Bypasses the fail-closed "sidecar published but no key" behavior.
skip-sigstore false Skip just the sigstore-bundle verification step.
skip-authenticode false Skip just the Authenticode (Windows PE) verification step.
keep-going false Continue past per-spec failures; exit non-zero with a summary if any spec failed.
ghr-version (derived from action ref) Override the ghr-bin version installed. Default: derived from the action's git ref (e.g. @v0.3.0 → ghr-bin==0.3.0). Pass latest to install the latest from PyPI.

Outputs

Output Description
cache-hit 'true' when the tool cache was restored from a prior run.

What it does

  1. pipx install ghr-bin (pre-installed on GitHub-hosted runners).
  2. Sets GHR_TOOL_DIR, GHR_BIN_DIR, GHR_CACHE_DIR to user-writable subdirectories of $RUNNER_TEMP, and prepends GHR_BIN_DIR to $GITHUB_PATH.
  3. Parses every tools: line into a spec [key] pair, validating the optional key shape (56-char base64, RW/RU prefix).
  4. Computes a stable cache key from the sorted list of spec [key] pairs + ghr version + OS/arch.
  5. Restores the cache via actions/cache@v4 (pinned by SHA).
  6. On cache miss, runs ghr install with every spec (and its inline key, when present) as positional arguments.
  7. Runs ghr list as a sanity check.

Examples

Verify with minisign (action-level default)

- uses: cataggar/ghr/actions/install@v1
  with:
    tools: jedisct1/minisign@0.12
    minisign: RWQf6LRCGA9i53mlYecO4IzT51TGPpvWucNSCh1CBM0QTaLn73Y7GFO3

Per-spec inline minisign keys

Different tools can be verified against different keys in a single action invocation. An inline key on a tools: line overrides the action-level minisign: default for that spec.

- uses: cataggar/ghr/actions/install@v1
  with:
    tools: |
      jedisct1/minisign@0.12 RWQf6LRCGA9i53mlYecO4IzT51TGPpvWucNSCh1CBM0QTaLn73Y7GFO3
      BurntSushi/ripgrep@14.1.1
      sharkdp/fd@v10.2.0

Skip a single verification step

Selectively bypass one verifier when its sidecar is broken or unavailable in a given release, while keeping the others active.

- uses: cataggar/ghr/actions/install@v1
  with:
    tools: BurntSushi/ripgrep@14.1.1
    skip-checksum: 'true'   # checksum-sidecar bypass; minisign + sigstore still apply

Continue past per-spec failures

- uses: cataggar/ghr/actions/install@v1
  with:
    tools: |
      BurntSushi/ripgrep@14.1.1
      sharkdp/fd@v10.2.0
      maybe/missing@1.0
    keep-going: 'true'

Pinning

The action shares git tags with the ghr CLI: @v0.3.0 references the action body and pins ghr-bin (via the ghr-version input default) to the matching release. To explicitly pin the installed binary to a different release, pass ghr-version:. For full reproducibility, pin to a commit SHA: cataggar/ghr/actions/install@<sha> # v0.3.0.