feat: Add `sparse-checkout-aggregate` action

Start with the sources.yml format, the example GitHub Actions usage, and the listed sparse-checkout commands. Define how full and incremental aggregation, caching, private-repository access, and the JSON outputs should behave, then verify the action against the documented examples and output shapes.

Summary

Create a reusable GitHub Action that clones/updates multiple repositories using git sparse checkout based on a mapping file (sources.yml).

Use Case

Aggregate documentation from multiple repositories into a single build. Supports both full re-aggregation and incremental single-repo updates with caching.

Specification

Inputs

Outputs

Example Output

// sources
[
  { "key": "ai", "repo": "arustydev/ai", "path": "docs/src", "local_path": ".sources/ai/docs/src", "sha": "abc123" },
  { "key": "just", "repo": "arustydev/just", "path": "docs/src", "local_path": ".sources/just/docs/src", "sha": "def456" }
]

// symlinks
[
  { "source": ".sources/ai/docs/src", "target": "books/ai" },
  { "source": ".sources/just/docs/src", "target": "books/just" }
]

Sources File Format (sources.yml)

books:
  ai:
    repo: arustydev/ai
    path: docs/src
    ref: main
    title: "AI Configuration"
  just:
    repo: arustydev/just
    path: docs/src
    ref: main
    title: "Justfile Library"

Example Usage

- uses: arustydev/gha/sparse-checkout-aggregate@v1
  id: aggregate
  with:
    sources_file: sources.yml
    only: ${{ github.event.client_payload.source_repo }}

Implementation Notes

Sparse Checkout Commands

# New clone
git clone --filter=blob:none --sparse --depth=1 \
    "https://github.com/$repo.git" ".sources/$key"
git -C ".sources/$key" sparse-checkout set "$path"

# Update existing
git -C ".sources/$key" fetch origin "$ref"
git -C ".sources/$key" checkout "origin/$ref" -- "$path"

Key Features

• Use --filter=blob:none for minimal data transfer
• Support incremental updates via only input
• Output structured JSON for downstream actions
• Calculate SHA hash for each repo for cache invalidation
• Handle private repos via token input

Related

• Part of docs aggregation workflow extraction
• Outputs consumed by symlink-map action
• Triggered by trigger-remote-workflow action