# Module: Automation and Release Pipelines

## Responsibilities
- Enforce repository quality/security checks before merge and deployment.
- Generate and maintain advisory feed updates from automated and community sources.
- Package, sign, and publish skill release artifacts from tag events.
- Build and deploy static website outputs and mirrored release/advisory assets.

## CI/CD Summary (migrated from README)

### Automated workflows
The canonical CI/CD workflow matrix (triggers + responsibilities) is maintained in `CLAUDE.md` under "CI Workflows".

This module intentionally focuses on automation/release-specific workflow behavior and operational details. Additional module-relevant workflows not listed in the core matrix include:
- `pages-verify.yml` (PR-only Pages build/signing verification without publish)
- `wiki-sync.yml` (syncs repository `wiki/` content to GitHub Wiki)

### Skill release pipeline behavior
When a skill is tagged (for example, `soul-guardian-v1.0.0`), the pipeline:
1. Validates `skill.json` version/tag alignment.
2. Enforces signing-key consistency against canonical repo key material.
3. Generates `checksums.json` for SBOM files.
4. Signs and verifies release checksum artifacts.
5. Publishes GitHub Release assets.
6. Supersedes older releases within the same major version (tags remain).
7. Triggers website catalog refresh.

### Signing-key consistency guardrails
Guardrail script:
- `scripts/ci/verify_signing_key_consistency.sh`

Enforced in:
- `.github/workflows/skill-release.yml`
- `.github/workflows/deploy-pages.yml`

### Release versioning and superseding
- New patch/minor release: previous releases in same major line are removed.
- New major release: latest release from previous major line is retained for compatibility.
- Git tags are preserved and can be used to recreate releases when needed.

### Release artifacts
Each skill release includes:
- `checksums.json`
- `skill.json`
- `SKILL.md`
- Additional SBOM-scoped files

Operational docs:
- `wiki/security-signing-runbook.md`
- `wiki/migration-signed-feed.md`

## Key Files
- `.github/workflows/ci.yml`: lint/type/build/security/test matrix.
- `.github/workflows/pages-verify.yml`: PR-only Pages build/signing verification (no publish).
- `.github/workflows/poll-nvd-cves.yml`: daily NVD advisory ingestion.
- `.github/workflows/community-advisory.yml`: issue-label-driven advisory publishing.
- `.github/workflows/skill-release.yml`: release validation, packaging, signing, and publishing.
- `.github/workflows/deploy-pages.yml`: site build + asset mirroring to GitHub Pages.
- `.github/workflows/wiki-sync.yml`: syncs repository `wiki/` into GitHub Wiki.
- `.github/actions/sign-and-verify/action.yml`: shared Ed25519 sign/verify composite action.
- `scripts/prepare-to-push.sh`: local CI-like quality gate.
- `scripts/release-skill.sh`: manual helper for version bump + tag workflow.

## Public Interfaces
| Interface | Trigger | Outcome |
| --- | --- | --- |
| CI workflow | Push/PR on `main` | Fails fast on lint/type/build/test/security regressions. |
| Pages Verify workflow | PR on `main` | Validates Pages build/signing artifacts without production deploy. |
| NVD poll workflow | Cron + dispatch | Updates advisory feed with deduped, normalized CVEs. |
| Community advisory workflow | Issue labeled `advisory-approved` | Opens PR adding signed advisory records. |
| Skill release workflow | Metadata PR changes + tag `<skill>-v*` | PR dry-run/version checks and tagged release publishing. |
| Deploy pages workflow | Successful CI/release run | Publishes site + mirrored artifacts to Pages. |
| Sync wiki workflow | Push `wiki/**` on `main` | Publishes repository wiki content into GitHub Wiki remote. |

## Inputs and Outputs
Inputs/outputs are summarized in the table below.

| Type | Name | Location | Description |
| --- | --- | --- | --- |
| Input | Git refs/events | GitHub Actions event payloads | Determines which workflow path runs. |
| Input | Skill metadata/SBOM | `skills/*/skill.json` | Drives release asset assembly and validation. |
| Input | NVD API data | External API responses | Source CVEs for advisory feed generation. |
| Input | Signing secrets | GitHub Secrets | Private key material for signing artifacts. |
| Output | Signed advisories | `advisories/feed.json(.sig)` + mirrored public files | Consumable signed feed channel. |
| Output | Skill release assets | `release-assets/*` and GitHub release attachments | Installable and verifiable skill artifacts. |
| Output | Website build | `dist/` deployment artifact | Public web frontend and mirrors. |

## Configuration
| Config Point | Location | Notes |
| --- | --- | --- |
| Workflow schedules | `poll-nvd-cves.yml`, `codeql.yml`, `scorecard.yml` | Daily/weekly security automation cadence. |
| Concurrency groups | Workflow `concurrency` blocks | Prevents destructive overlap in key pipelines. |
| Signing key checks | `scripts/ci/verify_signing_key_consistency.sh` | Ensures docs and canonical PEM files align. |
| Local pre-push gating | `scripts/prepare-to-push.sh` | Mirrors CI checks with optional auto-fix. |

## Example Snippets
```yaml
# skill release trigger pattern
on:
  push:
    tags:
      - '*-v[0-9]*.[0-9]*.[0-9]*'
```

```bash
# local all-in-one pre-push gate
./scripts/prepare-to-push.sh
# optional auto-fix
./scripts/prepare-to-push.sh --fix
```

## Edge Cases
- NVD API rate limiting (`403`/`429`) is handled with retry/backoff and can fail workflow on persistent errors.
- Release pipeline blocks on version mismatch between `skill.json` and `SKILL.md` frontmatter.
- Key fingerprint drift between canonical PEM files and docs hard-fails signing-related workflows.
- Deploy workflow intentionally allows unsigned legacy checksums for backward compatibility in some branches.
- Manual helper script has safety checks but includes destructive rollback logic in error branches; use carefully.

## Tests
| Validation Layer | Location |
| --- | --- |
| Workflow execution tests | CI jobs in `.github/workflows/ci.yml` |
| Skill-level unit/property tests | `skills/*/test/*.test.mjs` invoked by CI |
| Local deterministic checks | `scripts/prepare-to-push.sh` |
| Release link checks | `scripts/validate-release-links.sh` |

## Source References
- .github/workflows/ci.yml
- .github/workflows/poll-nvd-cves.yml
- .github/workflows/community-advisory.yml
- .github/workflows/skill-release.yml
- .github/workflows/deploy-pages.yml
- .github/workflows/pages-verify.yml
- .github/workflows/wiki-sync.yml
- .github/workflows/codeql.yml
- .github/workflows/scorecard.yml
- .github/actions/sign-and-verify/action.yml
- scripts/prepare-to-push.sh
- scripts/release-skill.sh
- scripts/validate-release-links.sh
- scripts/ci/verify_signing_key_consistency.sh