Setup kam

Install kam in your GitHub Actions runner with Rust stable, version-aware caching, optional Commitizen setup, and template import.

Important

• The action will attempt to install Commitizen (python-commitizen) via uv when install-commitizen is 'true' (default). Verification prefers module invocation (python -m commitizen) and falls back to the cz CLI if present. If Commitizen cannot be verified and require-commitizen is 'true', the action will fail; otherwise it will continue and emit a warning.
• The action performs preflight checks for required tools (such as curl) and will fail fast with guidance if missing.
• kam is installed with cargo install after the action resolves the requested version. Set kam-version to pin a release; leave it empty to use the latest version discovered from crates.io with a GitHub Releases fallback.
• To avoid unnecessary recompilation when a later step in the job fails after a successful build, this action saves the compiled kam artifacts to the GitHub Actions cache immediately after installation. The cache save is guarded so it only runs when a working kam binary is present, and it is executed with an always()-style guard so that it will still attempt to save the build even if later steps fail. Keep enable-cache: 'true' (the default) and ensure files used in the cache key (for example Cargo.lock) are present so the cache can be reliably restored on subsequent runs.

Usage

Basic example:

name: CI with kam
on: [push, pull_request]

jobs:
  build:
    runs-on: ubuntu-24.04
    steps:
      - uses: actions/checkout@v4
      - name: Setup kam
        uses: MemDeco-WG/setup-kam@2a0e9193a7e84dc7da78e99af586f8a4bb823bcb
        with:
          github-token: ${{ secrets.GITHUB_TOKEN }}
      - run: kam --version

With template import and caching:

- name: Setup kam (with template)
  uses: MemDeco-WG/setup-kam@2a0e9193a7e84dc7da78e99af586f8a4bb823bcb
  with:
    github-token: ${{ secrets.GITHUB_TOKEN }}        # optional (recommended)
    enable-cache: 'true'                             # optional, default true
    cache-targets: 'cargo,kam'                       # optional, default all
    cache-version: 'v2'                              # optional cache namespace
    template-url: https://example.com/template.zip   # optional
    kam-version: '0.3.1'                             # optional, pin version

Inputs

• github-token (optional): Default ${{ github.token }}. Use this if you need authenticated access to private releases/assets.
• enable-cache (optional): 'true' (default) or 'false' to disable caching.
• cache-targets (optional): Comma-separated cache targets, or 'all' / 'none'. Supported values: cargo, pip, npm, yarn, pnpm, bun, kam. Matching is exact after normalization, so pnpm will not accidentally enable npm.
• cache-version (optional): Cache namespace version. Default 'v2'. Change it when you need to intentionally invalidate setup-kam caches.
• kam-version (optional): Pin a specific kam version to install (e.g., '0.1.2'). When set, network lookup for the latest version is skipped and the pinned version will be used for installation and cache keys.
• template-url (optional): URL to a template archive (e.g., .zip, .tgz, .tar.gz). The URL must include a filename and extension; if you download manually, preserve the extension or provide the extracted directory path to kam tmpl import.
• install-commitizen (optional): 'true' (default) or 'false'. Attempt to install commitizen via uv. If you prefer not to install commitizen in the runner, set to 'false'.
• require-commitizen (optional): 'false' (default) or 'true'. When 'true' the action will fail if commitizen cannot be verified after attempted installation.

Outputs

• latest-version: Resolved kam version (from crates.io/GitHub or pinned).
• installed-version: Currently installed kam version (string, or empty).
• should-install: 'true' if the action decided to install kam.

Notes

• Rust stable is installed through dtolnay/rust-toolchain; kam itself is installed directly through Cargo rather than through the deprecated actions-rs/cargo action.
• The action attempts to install python-commitizen and verifies it's callable (preferring python -m commitizen and falling back to cz if present). This behavior is controlled by install-commitizen and require-commitizen inputs; if verification fails and require-commitizen is 'true', the action will fail, otherwise it will continue with a warning.
• The action performs preflight checks for required tools (e.g., curl and archive utilities if template-url points to an archive) and will fail early with guidance if they are missing.
• Pin uses: to a reviewed commit so workflow behavior stays reproducible.