feat: human-in-the-loop override approval for blocked promotions

[toddysm]

Summary

Adds an optional approve/deny override gate to the promote-from-quarantine workflows. When a scanned image fails the CVE threshold and approval is enabled, a tracking issue is filed and a Slack notification is sent; a maintainer can /approve or /deny via issue comment (or workflow_dispatch) to promote the image despite the failing threshold or close it out.

What's included

New reusable composite actions

• notify-slack — post Block Kit status messages to a Slack incoming webhook (notify-slack reusable composite action #65)
• manage-issue — idempotent tracking-issue lifecycle (open-or-update / comment / close / get) with embedded JSON metadata as the source of truth (manage-issue reusable composite action #66)
• verify-approver — enforce minimum repo permission for approvers (verify-approver reusable composite action #67)

Changes

• attach-scan-report — record com.cssc.scan.override* provenance annotations (Extend attach-scan-report with override provenance annotations #68)
• _promote-from-quarantine.yml / _promote-from-quarantine-sbom.yml — enable_approval input + slack_webhook secret; file issue + notify Slack on blocked images (Extend _promote-from-quarantine{,-sbom}.yml: notify + open issue on block #69)
• _promote-override.yml (reusable) + promote-override.yml (caller) — execute the maintainer decision (New reusable workflow _promote-override.yml + caller promote-override.yml #70)
• Docs: design doc, workflow-actions, workflow-naming, workflows overview (Docs: document override-approval workflow + actions #71)

Design

See promote-from-quarantine-override-approval.md.

Validation

• get_errors: clean (only benign SLACK_WEBHOOK "Context access might be invalid" until the secret is configured)
• shellcheck -S warning: clean on all run blocks
• Issue-body metadata round-trip tested (incl. CRLF handling)

Before enabling in production

1. Configure repo secrets SLACK_WEBHOOK and GHCR_DELETE_TOKEN.
2. Opt a per-image caller in via enable_approval: true + pass slack_webhook. Existing callers are unchanged and backward-compatible.

Tracking

Closes #64
Closes #65
Closes #66
Closes #67
Closes #68
Closes #69
Closes #70
Closes #71

[Copilot]

Pull request overview

Adds an optional human-in-the-loop approval/deny override path for promote-from-quarantine workflows when an image is blocked by the CVE threshold, using a GitHub tracking issue + Slack notifications as the audit/interaction surface.

Changes:

• Introduces composite actions to (a) notify Slack, (b) manage a per-image+tag tracking issue with embedded JSON metadata, and (c) verify approver permissions.
• Extends promote-from-quarantine reusable workflows with an enable_approval input and (when blocked) issue+Slack creation to drive later override decisions.
• Adds a new override workflow pair (promote-override.yml caller + _promote-override.yml reusable) and updates docs/design documentation accordingly.

Reviewed changes

Copilot reviewed 12 out of 12 changed files in this pull request and generated 5 comments.

Show a summary per file

File	Description
docs/reference/workflow-actions.md	Documents new actions and override-related inputs (includes a duplicated input table section).
docs/contributing/workflow-naming.md	Adds naming guidance for the new promote override workflow.
docs/architecture/workflows/promote-from-quarantine-workflows.md	Updates architecture notes to reflect optional approval/notification behavior.
docs/architecture/workflows/promote-from-quarantine-override-approval.md	New design doc describing the override approval architecture and security posture.
.github/workflows/promote-override.yml	New caller workflow that triggers overrides via issue comments or manual dispatch.
.github/workflows/_promote-override.yml	New reusable workflow implementing approve/deny behavior, provenance recording, and notifications.
.github/workflows/_promote-from-quarantine.yml	Adds enable_approval + blocked-image issue/Slack notification path.
.github/workflows/_promote-from-quarantine-sbom.yml	Same as above for SBOM-based scanning/promotion path.
.github/actions/verify-approver/action.yml	New composite action to authorize override approvers based on repo permission.
.github/actions/notify-slack/action.yml	New composite action to post Block Kit messages to a Slack webhook.
.github/actions/manage-issue/action.yml	New composite action for idempotent tracking-issue lifecycle + metadata round-trip.
.github/actions/attach-scan-report/action.yml	Extends scan-report referrer to optionally include override provenance annotations.

---

💡 Add Copilot custom instructions for smarter, more guided reviews. Learn how to get started.