aRustyDev / aRustyDev/gh

feat: Add `sparse-checkout-aggregate` action

Open
#4 0 comments 0 reactions 0 assignees View on GitHub
enhancement new-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

Open the contributing guide

Assessment

This issue has not been assessed yet.

Get new issues in your inbox

A short digest of beginner-friendly GitHub issues.