Model reusable Nextcloud app release automation

[vitormattos]

Goal

Turn the current LibreSign release procedure into reusable, testable automation for Nextcloud applications.

Architecture decision

Implement this in the dedicated reusable workflow repository tracked by #4, not in github-governance.

Start with reusable workflows plus testable scripts. Extract a dedicated action only after the interface proves stable across more than one application.

Release plan stage

The first workflow should be non-mutating and produce a release plan that validates:

• target stable branch;
• milestone state and unresolved blockers;
• pending backports;
• generated files;
• current application/release metadata;
• proposed semantic version;
• changelog inputs;
• required credentials and publication prerequisites.

Planning must fail closed when release blockers are present.

Apply stage

A separate explicitly-invoked release workflow should:

• require an explicit version and target branch;
• rerun the plan checks;
• update release metadata;
• prepare or validate the release commit/PR;
• build the final artifact;
• validate the artifact itself;
• create the tag and GitHub Release;
• publish through the existing Nextcloud App Store flow;
• verify publication.

Safety

• planning is the default;
• mutation requires an explicit workflow invocation;
• signing/publication credentials stay in the consumer repository/environment;
• third-party actions use immutable SHA pins with exact version comments;
• release workflows should support protected environments for publication;
• a failed validation must not leave a partial release silently accepted.

Initial consumer

LibreSign should be the first migration target because its current manual release process provides the reference behavior.

Acceptance criteria

• release planning is testable without publishing;
• required backports/blockers prevent release;
• produced artifact is validated;
• release/tag publication is explicit and auditable;
• credentials are not centralized in the shared workflow repository;
• at least one second Nextcloud app can adopt the same interface without product-specific code changes.

[vitormattos]

Shared release automation is now in place. github-workflows v0.2.0 added tested artifact validation and App Store publication verification, and v0.3.0 added the explicit opt-in release apply workflow. Both are published through the organization catalog. Profile Fields adopted the same App Store/apply interface without product-specific release logic. LibreSign keeps its richer product-specific preparation flow in LibreSign/libresign#8447; that PR has been adjusted to keep appstore-build-publish.yml on the catalog-managed filename and preserve LibreSign-only differences through a local patch. The remaining work before closing this issue is validating/merging that LibreSign integration.

[vitormattos]

Implementation checkpoint after validating the current LibreCodeCoop/github-workflows repository.

The release automation foundation now exists, but #5 should remain the tracking issue for the full generic release contract.

Implemented

• actions/release-plan validates an explicit semantic version, current/stable branch match, appinfo/info.xml version, changelog entry, optional closed milestone and arbitrary blocker queries.
• release-nextcloud-app.yml provides an explicit protected-environment apply entry point and re-runs the release plan before creating the GitHub Release.
• appstore-build-publish.yml reacts to the published GitHub Release, builds/packages the app, validates the artifact, attaches it to the release, publishes it to the Nextcloud App Store and verifies publication.
• publication/signing credentials remain in the consumer repository.

Still to model before considering the release automation generic

The caller contract currently assumes the operator already knows and supplies both version and stable_branch. We need to model repository release policy explicitly because not every Nextcloud app has the same branch strategy.

The generic design should cover:

• apps that release directly from the default branch;
• apps that maintain stable* branches;
• release from an explicitly selected branch and, where safe, an immutable commit/ref;
• optional versus required milestones;
• explicit backport policy and pending-backport detection;
• automatic proposal of the next semantic version from repository/app metadata, while keeping the final mutation explicit;
• validation that generated/release metadata has already been prepared, or a separate reviewable preparation PR when it has not;
• a clear distinction between "prepare release", "release plan" and "publish/apply" so that automation never silently mutates source metadata while publishing.

This is the right place to keep those product/release-policy decisions. They should be implemented in github-workflows, not added to the governance ruleset engine.

[vitormattos]

The implementation roadmap is now tracked in LibreCodeCoop/github-workflows as LibreCodeCoop/github-workflows#70.

This keeps #5 as the architecture/product decision and puts executable work next to the workflow platform.

The implementation is intentionally LibreSign-first: reproduce the documented LibreSign release train with composable workflow_call stages, then generalize only after the contracts have been proven in production. The stages are split into discovery/preflight, changelog/version preparation, stable release preparation, milestone transition, sequential publication/verification, and an orchestrator joining them.

LibreSign's published release-process and branch-policy documentation are the source of truth for these stages.