feat: Add `symlink-map` action
- Dominant language
- Shell
- Stars
- 0
- Forks
- 0
- PR merge metrics
- No merged PRs in 30d
Description
## Summary
Create a reusable GitHub Action that creates symlinks from an explicit list or mapping file.
## Use Case
After sparse-checkout-aggregate clones documentation sources, create symlinks to make them accessible to the build tool (e.g., mdbook).
## Specification
### Inputs
| Input | Required | Default | Description |
|-------|----------|---------|-------------|
| `links` | No* | — | JSON array of `{ source, target }` |
| `mapping_file` | No* | — | Path to mapping file (must match schema) |
| `source_prefix` | No | — | Prefix for source paths (with mapping_file) |
| `target_prefix` | No | — | Prefix for target paths (with mapping_file) |
| `clean` | No | `false` | Remove existing symlinks in target dirs first |
*One of `links` or `mapping_file` required.
### Example Usage
```yaml
# From job outputs (preferred)
- uses: arustydev/gha/symlink-map@v1
with:
links: ${{ steps.aggregate.outputs.symlinks }}
# OR from mapping file
- uses: arustydev/gha/symlink-map@v1
with:
mapping_file: sources.yml
source_prefix: .sources
target_prefix: books
```
### Links Format
```json
[
{ "source": ".sources/ai/docs/src", "target": "books/ai" },
{ "source": ".sources/just/docs/src", "target": "books/just" }
]
```
## Implementation Notes
- Validate source paths exist before creating symlinks
- Create parent directories for targets if needed
- Use relative symlinks where possible
- Support `clean` mode to remove stale symlinks
- Validate against schema when using mapping_file
## Schema
Schema will be published at `https://schemas.arusty.dev/gha/symlink-map/v1.schema.json`
See: arustydev/schemas for schema definition.
## Related
- Part of docs aggregation workflow extraction
- Consumes outputs from `sparse-checkout-aggregate` action
- Schema tracked in arustydev/schemas
Contributor guide
Assessment
This issue has not been assessed yet.