feat(ci): reusable setup composite action with fbuild-hash pinning (closes #101)

[zackees]

Summary

• Adds FastLED/fbuild/.github/actions/setup composite action for one-line fbuild CI setup (install + cache + env wiring).
• Pins cache keys to the exact installed fbuild content hash (sha256 of the wheel's dist-info RECORD), not just the PyPI version string — protects against silent cache poisoning from re-released wheels or non-registry installs.
• Updates docs/CI_CACHING.md to promote fbuild-hash from optional to required, with a raw-snippet example for consumers who don't want the action dependency.

Why hash-pinning matters

The fbuild cache stores toolchains, frameworks, and build outputs whose layout is tied to fbuild's fingerprint format, response-file generation, and embedded paths. A version string does not discriminate against re-released wheels, dev builds, or different platform tags — any of which can poison a restored cache. Hashing the installed RECORD covers all of those cases and makes fbuild-version: latest safe-by-construction.

Test plan

• CI matrix runs against the action on ubuntu-latest, macos-latest, windows-latest
• Second build in the same job hits cache (see smoke test in .github/actions/setup/README.md)
• Upgrading fbuild between two runs forces a cache miss (hash changes)
• Consumers can read the fbuild-hash output for their own diagnostics

🤖 Generated with Claude Code

Summary by CodeRabbit

• New Features

  • Added a new GitHub composite action for setting up fbuild with automatic caching, environment variable configuration, and cache invalidation based on fbuild content.

• Documentation

  • Added documentation for the new fbuild setup action with usage examples and cache behavior details.
  • Updated CI caching guide to recommend the composite action for streamlined setup.

• Chores

  • Added follow-up tasks for enhancing fbuild cache pinning strategy.

[coderabbitai]

Warning

Rate limit exceeded

@zackees has exceeded the limit for the number of commits that can be reviewed per hour. Please wait 50 minutes and 25 seconds before requesting another review.

Your organization is not enrolled in usage-based pricing. Contact your admin to enable usage-based pricing to continue reviews beyond the rate limit, or try again in 50 minutes and 25 seconds.

⌛ How to resolve this issue?

After the wait time has elapsed, a review can be triggered using the @coderabbitai review command as a PR comment. Alternatively, push new commits to this PR.

We recommend that you space out your commits to avoid hitting the rate limit.

🚦 How do rate limits work?

CodeRabbit enforces hourly rate limits for each developer per organization.

Our paid plans have higher rate limits than the trial, open-source and free plans. In all cases, we re-allow further reviews after a brief timeout.

Please see our FAQ for further information.

ℹ️ Review info

⚙️ Run configuration

Configuration used: Path: .coderabbit.yaml

Review profile: CHILL

Plan: Pro

Run ID: e288fc1b-fc0c-4174-941d-0683ba859d06

📥 Commits

Reviewing files that changed from the base of the PR and between 66f2651 and 844c4fa.

📒 Files selected for processing (3)

• .github/actions/setup/README.md
• .github/actions/setup/action.yml
• docs/CI_CACHING.md

📝 Walkthrough

Walkthrough

This PR introduces a GitHub composite action for setting up fbuild-based CI workflows, complete with documentation. The action installs fbuild via pip, computes a deterministic content hash from the installed distribution's metadata, manages a cache directory, and integrates with actions/cache@v4 for deterministic cache invalidation based on fbuild version changes.

Changes

Cohort / File(s)	Summary
GitHub Composite Action .github/actions/setup/action.yml, .github/actions/setup/README.md	Introduces new setup composite action that installs fbuild, computes an fbuild content hash (sha256 of dist-info RECORD, truncated to 16 hex chars), configures a cache directory under $RUNNER_TEMP, and integrates with actions/cache@v4. Exports FBUILD_CACHE_DIR environment variable and outputs for cache hit, resolved directory, and computed hash. Supports customizable cache key components and optional cache disabling.
Documentation Updates docs/CI_CACHING.md	Shifts primary recommendation from raw actions/cache@v4 snippet to the new composite action. Updates cache strategy documentation to emphasize fbuild content hash (instead of version strings) for cache key derivation, ensuring cache invalidation when installed fbuild contents differ.
Maintenance tasks/todo.md	Adds follow-up TODO to enforce exact fbuild hash pinning in CI caching strategy, including smoke tests for cache invalidation validation.

Sequence Diagram

sequenceDiagram
    participant Step as Workflow Step
    participant Action as Setup Action
    participant PIP as pip/PyPI
    participant Cache as actions/cache@v4
    participant Env as Environment

    Step->>Action: Trigger composite action
    Action->>PIP: Install fbuild (version/latest)
    PIP-->>Action: fbuild installed
    Action->>Action: Compute content hash from dist-info RECORD
    Action->>Action: Resolve cache directory path
    Action->>Cache: Restore cache using key (OS + arch + hash + extras)
    Cache-->>Action: Return cache-hit status
    Action->>Env: Export FBUILD_CACHE_DIR
    Action-->>Step: Return outputs (cache-hit, cache-dir, fbuild-hash)

Loading

Estimated Code Review Effort

🎯 3 (Moderate) | ⏱️ ~20 minutes

Possibly Related Issues

• docs(ci): document cache save/restore design for CI runners (GH Actions, etc.) #92: Directly addresses the issue's request for a GitHub Actions composite action and cache-key strategy based on fbuild content hash (RECORD-based) rather than PyPI version strings.
• feat(ci): ship reusable GitHub Action for fbuild install + cache setup (external consumers) #101: Implements the proposed reusable GitHub composite action for fbuild setup and CI caching exactly as specified in the issue proposal.

Poem

🐰 A fluffy action hops into place,
Computing hashes with fbuild grace,
Cache keys dance with content-proof,
No stale wheels—just truth aloof! 🏃✨

🚥 Pre-merge checks | ✅ 3

✅ Passed checks (3 passed)

Check name	Status	Explanation
Description Check	✅ Passed	Check skipped - CodeRabbit’s high-level summary is enabled.
Title check	✅ Passed	The title clearly and specifically describes the main change: introducing a reusable composite action for CI setup with fbuild-hash pinning, which aligns perfectly with the primary objective of adding a new GitHub Action at .github/actions/setup that pins cache keys to the fbuild content hash.
Docstring Coverage	✅ Passed	No functions found in the changed files to evaluate docstring coverage. Skipping docstring coverage check.

_{✏️ Tip: You can configure your own custom pre-merge checks in the settings.}

✨ Finishing Touches

🧪 Generate unit tests (beta)

• Create PR with unit tests
• Commit unit tests in branch feat/101-setup-action

---

Thanks for using CodeRabbit! It's free for OSS, and your support helps us grow. If you like it, consider giving us a shout-out.

❤️ Share

• X
• Mastodon
• Reddit
• LinkedIn

_{Comment @coderabbitai help to get the list of available commands and usage tips.}