aRustyDev / aRustyDev/mdbook-htmx
feat(ci): Implement cross-repo-validate compliance for docs sync
- Dominant language
- Rust
- Stars
- 0
- Forks
- 1
- PR merge metrics
- No merged PRs in 30d
Description
## Summary
The `cross-repo-validate` action in `aRustyDev/docs` has been updated with new requirements for sync PRs. This issue tracks the changes needed in `mdbook-htmx`'s cross-repo-sync workflow to comply with validation.
## Current State vs Required State
### 1. Branch Pattern
| Aspect | Current | Required |
|--------|---------|----------|
| Format | `docs-sync//` | `docs-sync/` |
| SHA location | In branch name | In manifest only |
| Purpose | Unique per commit | Stable for CI reruns |
**Why**: Stable branch pattern allows re-running CI without creating duplicate PRs.
### 2. Manifest Location
| Aspect | Current | Required |
|--------|---------|----------|
| Location | PR diff (file in commit) | PR body (between markers) |
| Format | JSON file | JSON in HTML comments |
**Required PR body format**:
```markdown
{
"$schema": "https://schemas.arusty.dev/cross-repo-sync/manifest/v1",
"version": "1.0",
"source": { ... },
"target": { ... },
"sync": { ... },
"files": [ ... ],
"checks": [ ... ]
}
```
### 3. Manifest Schema
The manifest must include:
```json
{
"$schema": "https://schemas.arusty.dev/cross-repo-sync/manifest/v1",
"version": "1.0",
"source": {
"repository": "aRustyDev/mdbook-htmx",
"sha": "<40-char-sha>",
"ref": "refs/heads/main",
"workflow_run_id": ""
},
"target": {
"repository": "aRustyDev/docs",
"branch": "docs-sync/mdbook-htmx",
"path_prefix": "library/gh/mdbook-htmx"
},
"sync": {
"type": "docs",
"id": "",
"timestamp": ""
},
"files": [
{
"path": "library/gh/mdbook-htmx/README.md",
"sha256": "<64-char-hash>"
}
],
"checks": [
{
"name": "lint",
"id": "",
"result": "passed",
"attestation": {
"id": ""
},
"timestamp": ""
}
]
}
```
### 4. Attestation Architecture
| Component | Required Action |
|-----------|-----------------|
| **Check attestations** | For each check, use `gh attestation attest` on check result JSON |
| **Root attestation** | Use `gh attestation attest` on final manifest |
| **PR body** | Include root attestation ID as HTML comment |
**Flow**:
1. For each check (lint, build, etc.):
- Run check
- Output result to JSON
- `gh attestation attest `
- Add attestation ID to manifest's `checks[].attestation.id`
2. When all checks complete:
- `gh attestation attest `
- Include manifest + root attestation ID in PR body
### 5. Labels
| Aspect | Required |
|--------|----------|
| Label | `docs-sync` (matches `-sync` pattern) |
| Timing | Applied when PR is created |
## Implementation Checklist
- [ ] Update branch naming to stable pattern (`docs-sync/mdbook-htmx`)
- [ ] Generate manifest with required schema fields
- [ ] Implement check attestations (for each check step)
- [ ] Implement root attestation on manifest
- [ ] Embed manifest in PR body between markers
- [ ] Include root attestation ID as HTML comment
- [ ] Apply `docs-sync` label to PR
- [ ] Compute SHA256 hashes for all synced files
## Reference
- [cross-repo-validate action](https://github.com/aRustyDev/docs/blob/main/.github/actions/cross-repo-validate/README.md)
- [Manifest schema](https://github.com/aRustyDev/docs/blob/main/.github/schemas/sync-manifest.schema.json)
- [Validation workflow](https://github.com/aRustyDev/docs/blob/main/.github/workflows/validate-sync-pr.yml)
## Priority
High - sync PRs will fail validation until this is implemented.
Contributor guide
Assessment
This issue has not been assessed yet.