clawsec/wiki/modules/automation-release.md

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

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

# 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