feat(ci): manual workflow_dispatch for sign-modules-on-approval

[djm81]

Summary

Adds workflow_dispatch so signing can be run from Actions on dev before this workflow exists on the default branch (main).

Changes

• sign-on-dispatch job: inputs base_branch, version_bump; trusted scripts from integration branch tip; --changed-only vs git merge-base to origin/<base_branch>; push to the branch selected in Run workflow.
• sign-on-approval: renamed from sign; explicit pull_request_review guard in if.
• Concurrency group works for both event types.
• Docs, CHANGELOG, tests (helpers to satisfy code-review CC).

How to verify after merge to dev

Actions → Sign modules on PR approval → Run workflow → branch dev → run.

Made with Cursor

[coderabbitai]

Caution

Review failed

The pull request is closed.

ℹ️ Recent review info

⚙️ Run configuration

Configuration used: Path: .coderabbit.yaml

Review profile: ASSERTIVE

Plan: Pro

Run ID: 8b9d8bdd-c4b1-43bf-af08-b69b01f75706

📥 Commits

Reviewing files that changed from the base of the PR and between 01e7351 and 9bfe5f3.

📒 Files selected for processing (4)

• .github/workflows/sign-modules-on-approval.yml
• CHANGELOG.md
• docs/reference/module-security.md
• tests/unit/workflows/test_sign_modules_on_approval.py

---

📝 Walkthrough

CI/Workflow: Manual workflow_dispatch for sign-modules-on-approval

User-visible behavior and operator surface

• Adds manual workflow dispatch option to the "Sign modules on PR approval" GitHub Actions workflow, enabling operators to trigger module signing from Actions → Sign modules on PR approval → Run workflow by selecting a branch (base_branch: dev/main) and version bump strategy (version_bump: patch/minor/major).
• The manual path executes sign-modules.py --changed-only with merge-base logic against the chosen base_branch, signing changes on the selected branch before the workflow exists on the default branch.
• Retains approval-gated signing for pull requests (PR review events); the existing pull_request_review trigger now requires the workflow to exist on the default branch (main) and will only sign changes based on merge-base to the PR target.

Contract/API impact

No changes to public Python functions, Pydantic models, module boundaries, or CLI surface. This is purely a CI/workflow enhancement.

Testing and quality gates

• Workflow policy tests refactored to validate two separate jobs: sign-on-approval (PR review–gated) and sign-on-dispatch (manual dispatch–gated).
• Test helpers expanded to cover both pull_request_review and workflow_dispatch triggers with their respective input parameters (base_branch, version_bump).
• Added validation for sign-on-dispatch job permissions (contents: write) and secret references.
• Test coverage distinguishes approval-sign vs. dispatch-sign code paths, including different merge-base computation strategies and push targets.

Documentation and CHANGELOG updates

• docs/reference/module-security.md: Updated "Approval-time signing" section to clarify that pull_request_review uses the workflow from the default branch; added alternative manual path instructions via Actions UI with branch/version-bump selection.
• CHANGELOG.md: Added entry documenting workflow_dispatch support for sign-on-dispatch with base-branch–tip trust and merge-base–based change detection, enabling pre-default-branch signing on dev.

Module signing flow changes

• For approval-gated signing (unchanged trigger, clarified execution): Uses base revision tip scripts, detects changes via merge-base to PR target, commits/pushes to the PR head reference.
• For manual dispatch (new job): Uses base-branch tip scripts, detects changes via merge-base to chosen origin/<base_branch>, commits/pushes to the current GITHUB_REF_NAME, enabling signing on non-main branches before workflow promotion.
• Concurrency group updated to include event name, preventing cross-trigger interference between approval and manual runs.

Walkthrough

The PR enhances the module-signing CI workflow by introducing manual workflow_dispatch triggering capability alongside the existing PR-review approval path. A new sign-on-dispatch job validates signing keys, selects trusted scripts from a specified base branch, and signs changed modules with configurable version bumping, while the existing approval flow is refactored into a sign-on-approval job with explicit event-type gating and adjusted checkout behavior.

Changes

Cohort / File(s)	Summary
Workflow Enhancement .github/workflows/sign-modules-on-approval.yml	Added workflow_dispatch trigger with base_branch and version_bump inputs; split approval and dispatch logic into separate sign-on-approval and sign-on-dispatch jobs; refactored concurrency grouping; updated signing invocation to use --changed-only, git merge-base, and explicit base-ref selection per trigger type.
Documentation Updates CHANGELOG.md, docs/reference/module-security.md	Updated changelog with new dispatch-triggered signing capability; clarified module-security docs to specify workflow definition sourced from default branch for pull_request_review, and documented alternate manual dispatch path via GitHub Actions UI with explicit MERGE_BASE-based signing behavior.
Test Coverage Expansion tests/unit/workflows/test_sign_modules_on_approval.py	Refactored test assertions with helper functions; expanded coverage to validate both pull_request_review and workflow_dispatch triggers; split job assertions for sign-on-approval and sign-on-dispatch with distinct shell-content checks (e.g., approval uses BASE_REF, dispatch uses MERGE_BASE and git merge-base); consolidated secret reference validation.

Sequence Diagram

sequenceDiagram
    actor User
    participant GHA as GitHub Actions
    participant Scripts as Signing Scripts
    participant Git as Git/Origin
    participant Manifest as Manifest Files

    User->>GHA: Trigger workflow_dispatch<br/>(base_branch=dev, version_bump=minor)
    GHA->>GHA: Validate SIGNING_KEY secret present
    GHA->>Scripts: Checkout trusted scripts<br/>from base_branch
    GHA->>Git: Checkout PR branch
    GHA->>Git: Compute merge-base<br/>vs origin/base_branch
    GHA->>Scripts: Run sign-modules.py<br/>--changed-only --bump-version minor
    Scripts->>Manifest: Sign changed modules
    Manifest->>GHA: Manifest files staged
    GHA->>Git: Commit & push to<br/>GITHUB_REF_NAME
    Git->>User: Signing complete,<br/>changes pushed

Loading

Estimated code review effort

🎯 3 (Moderate) | ⏱️ ~25 minutes

Possibly related issues

• [Change] CI-Driven Module Signing On PR Approval #500: Directly modifies the same PR-approval module-signing CI workflow to add/enhance signing behavior and related trigger logic.
• [Change] CI-Driven Module Signing On PR Approval specfact-cli-modules#185: Directly modifies the same signing workflow to introduce approval-gated CI signing and related dispatch paths.

Possibly related PRs

• Feature/ci module sign on approval #504: Modifies module-signing CI workflows with approval/dispatch paths, git merge-base, and updated sign-modules invocations.
• feat(ci): module signing on PR approval and manual workflow_dispatch #503: Directly related; modifies the same approval-triggered and manual workflow_dispatch signing paths, including sign-on-approval/sign-on-dispatch jobs, inputs, and supporting tests/docs.

Suggested labels

module-system, enhancement

✨ Finishing Touches

📝 Generate docstrings

• Create stacked PR
• Commit on current branch

🧪 Generate unit tests (beta)

• Create PR with unit tests
• Commit unit tests in branch feature/sign-modules-on-approval-workflow-dispatch

---

_{Comment @coderabbitai help to get the list of available commands and usage tips.}

[chatgpt-codex-connector]

💡 Codex Review

Here are some automated review suggestions for this pull request.

Reviewed commit: 9bfe5f3bb3

ℹ️ About Codex in GitHub

Your team has set up Codex to review pull requests in this repo. Reviews are triggered when you

• Open a pull request for review
• Mark a draft as ready
• Comment "@codex review".

If Codex has suggestions, it will comment; otherwise it will react with 👍.

Codex can also answer questions or update the PR. Try commenting "@codex address that feedback".

[chatgpt-codex-connector]

Do not depend on workflow_dispatch before default-branch rollout

This change is intended to let maintainers run the signer from dev before the workflow exists on main, but workflow_dispatch does not fire unless the workflow file is already present on the default branch, so the new manual path cannot be used in the rollout window it is meant to cover. In that state, approval-time signing is still blocked and the operational guidance added in this commit fails.

Useful? React with 👍 / 👎.

[chatgpt-codex-connector]

Prevent no-op defaults for manual signing on dev

The new dispatch input defaults base_branch to dev, but when operators run this workflow on branch dev (the documented bootstrap flow), git merge-base HEAD origin/dev resolves to HEAD, so --changed-only --base-ref "$MERGE_BASE" selects no module changes and silently skips signing. This makes the default path ineffective unless users override the input each time.

Useful? React with 👍 / 👎.