Provide the maintainer-facing Prepare Release workflow and end-to-end orchestration

[vitormattos]

Parent: #70
Depends on: #71, #72, #73, #74, #75, #78, #79, #80, #81, #82, #83, #84, #87, #88

Goal

Provide one clear GitHub Actions entry point for normal maintainers while composing reusable release stages with explicit contracts.

This is the final orchestration issue. It should not invent new release policy.

Primary UI

Normal release starts from Prepare release via workflow_dispatch for one manually selected release line. The workflow must never auto-select and release all maintained stables.

Inputs:

• branch — required;
• commit/ref — optional advanced override;
• version — optional explicit override;
• channel — alpha / beta / rc / final;
• ignore open backport — boolean;
• create follow-up milestone — boolean/choice;
• mode — normal / security.

The workflow resolves these through #71 into a ReleasePlan.

User journey

Run Prepare release
    ↓
read-only plan/summary
    ↓
generated stable release PR
    ↓
maintainer reviews and merges
    ↓
post-merge revalidation
    ↓
milestone transition
    ↓
GitHub Release draft
    ↓
maintainer reviews draft
    ↓
Publish release
    ↓
existing publisher
    ↓
verification

Normal use must not require a local checkout.

Authorization

Read-only planning may run without release-manager privileges.

Before any mutation such as creating/updating the generated release PR, resolve the triggering actor's repository permission and require the consumer-configured minimum.

For LibreSign v1:

• maintain or admin may start mutating preparation;
• maintain or admin may merge the generated release PR and trigger privileged continuation.

On PR merge, validate merged_by (not merely the workflow actor) against the repository permission API.

Do not authorize through labels or author association.

Merge continuation

Generated PRs carry deterministic identity/provenance.

Continuation after merge verifies:

• PR was merged, not closed;
• PR belongs to the release plan;
• expected base branch;
• final merged state;
• authorized maintainer merge path;
• required stable finalization/aggregate-history synchronization state is valid.

Labels/branch markers identify context but never grant authorization.

Orchestration

Prefer explicit reusable workflow/action/CLI contracts.

Avoid opaque chains of workflow_run when workflow_call, explicit outputs, PR merge events or another explicit contract is clearer.

The orchestrator coordinates existing stages; it must not duplicate their policy.

CLI parity

The reusable CLI supports equivalent:

• plan;
• dry-run;
• diagnostics;
• manual/recovery operations.

The docs describe the manual equivalent.

Step Summary

Every run should clearly show:

• branch/SHA;
• previous release;
• proposed/final version;
• channel;
• bump reason;
• release activity;
• changelog target;
• backport blockers/override;
• milestone decision;
• release PR URL;
• aggregate-history synchronization state;
• draft URL;
• verification result.

Permissions

Use least privilege by stage:

• planning: read-only;
• PR preparation: only permissions needed to create/update generated PRs;
• milestone stage: issues/PR mutation;
• draft stage: release/content mutation;
• publisher: existing consumer-specific permissions.

Do not give the entire workflow broad permissions only because one stage needs them.

Privileged stages use a GitHub App installation token with explicitly documented permissions. Read-only planning should not require that privileged token.

No workflow downloads or executes a floating latest PHAR. The orchestration pins an exact release-tool version and verifies the published checksum before execution.

Acceptance criteria

• complete normal release starts from GitHub web UI;
• branch is the only mandatory repository selection;
• optional overrides validated;
• generated PR merges continue automatically without another manual dispatch;
• privileged stages require authorized paths;
• final publication remains explicit;
• local CLI reproduces same plan;
• end-to-end dry-run covers LibreSign consumer config;
• post-publication continuation consumes PublicationVerification v1 from Verify the published release, artifact and App Store handoff #88;
• no production dependency on #8447.

Definition of done

• the maintainer-facing Prepare release workflow is available and documented;
• it composes existing stage contracts without duplicating release policy in YAML;
• permissions and GitHub App authentication are least-privilege and tested;
• exact release-tool version/checksum handling uses Provide a reusable action for pinned release-tool PHAR execution #87;
• normal, prerelease, backport-blocked/override, security and recovery flows have end-to-end validation;
• publication remains the only final human action after release PR merge;
• no production dependency on #8447 remains.

[vitormattos]

Implementation status: the reusable orchestration is now in main through the preparation, post-merge, publication verification and documentation-sync actions. Authorization is read from the validated consumer config, mutating stages use scoped GitHub App installation tokens, release state is handed off through deterministic artifacts, and the existing publisher remains responsible for package/sign/App Store publication.

LibreSign consumer integration is in LibreSign/libresign#8513 and currently pins github-workflows commit 44c9575c0876a5f10f2bf2e49a95b8f6c50a633a. I am leaving this issue open until that consumer PR is merged and the final end-to-end path is exercised from the repository UI.

[vitormattos]

Completion evidence for #76:

• Production consumer integration is merged in ci: add production release orchestration LibreSign/libresign#8513. The repository now exposes one Prepare release workflow with manual preparation, merged-PR continuation and release-publication verification.
• The reusable stages are in github-workflows main: release-prepare, release-post-merge, release-publication, scoped authorization and deterministic artifact restore.
• github-workflows#117 is merged and publishes the production Prepare release template; the legacy direct-release template is no longer in the public catalog.
• chore: sync workflow catalog .github#37 is merged, so the public organization catalog contains the final template.
• github-workflows v0.4.0 is published at immutable SHA 002f17274ba1eade3351ba81890bf53674b37c43; the template pins its reusable release actions to that release.
• Release-tool acceptance coverage now explicitly exercises the required end-to-end scenarios: normal publication, prerelease identity, open-backport blocker + override, security mode without private-data leakage, stale-state recovery, translation-only/direct maintenance activity, and failed publication with rerunnable stable verification identity. The final scenario coverage was merged in test: complete release lifecycle acceptance scenarios release-tool#14 with PHPUnit, PHAR, PHP quality, Infection, workflow quality and REUSE all green.
• Document the complete LibreSign release lifecycle and manual path LibreSign/documentation#97 is completed and documents the automated/manual lifecycle and recovery path.
• The existing App Store publisher remains the publication mechanism; Publish release is still the final explicit human gate.

A real release is intentionally not created merely to test the workflow. Production behavior is exercised through the same versioned domain contracts, PHAR parity, reusable-action tests and acceptance lifecycle tests, while the live LibreSign workflow is now installed on main.