feat: Add `sparse-checkout-aggregate` action
- Dominant language
- Shell
- Stars
- 0
- Forks
- 0
- PR merge metrics
- No merged PRs in 30d
Description
## 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
| Input | Required | Default | Description |
|-------|----------|---------|-------------|
| `sources_file` | Yes | — | Path to sources.yml mapping file |
| `output_dir` | No | `.sources` | Directory for cloned repos |
| `only` | No | — | Single repo to update (incremental mode) |
| `token` | No | `${{ github.token }}` | For private repos |
### Outputs
| Output | Description |
|--------|-------------|
| `sources` | JSON array of `{ key, repo, path, local_path, sha }` |
| `symlinks` | JSON array of `{ source, target }` for symlink-map action |
| `source_shas` | Hash of all repo SHAs for cache key |
### Example Output
```json
// 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)
```yaml
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
```yaml
- 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
```bash
# 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
Contributor guide
Assessment
This issue has not been assessed yet.