The recommended integration uses the tested composite actions published by LibreCodeCoop/release-tool.
The consumer workflow should orchestrate release stages, not reimplement release policy.
Mutating release steps use short-lived GitHub App installation tokens instead of a long-lived personal access token.
A third-party organization should create and install its own GitHub App in the consumer repository. Follow Configuring the GitHub App for the exact registration settings, repository permissions, installation scope, private-key generation, and Actions secret configuration.
At minimum, the release flow needs to be able to create/update release branches and pull requests, create GitHub Releases, and read Actions state. Configure only the permissions required by the actions you adopt.
Keep the App private key as an Actions secret.
The reusable actions accept the App slug and private key; the default LibreCode App slug is only appropriate where that App is installed.
Use the managed prepare-release.yml template instead of maintaining a private copy of the orchestration. Install sync-workflow-templates.yml beside it so updates to managed workflows arrive as reviewable pull requests.
The updater has its own authentication contract and needs Workflows: write in addition to Contents and Pull requests write access. Those permissions are not required by the release App itself. See the workflow synchronization guide.
A normal consumer workflow has three entry points:
workflow_dispatchfor release preparation;pull_request_target: closedfor post-merge finalization;release: publishedfor publication verification.
pull_request_target is intentional for the post-merge event because generated release commits use [skip ci]. The job itself must still validate that the closed PR:
- was merged;
- came from a generated
release-tool/branch; - contains the release preparation marker.
Do not run mutation logic for arbitrary pull requests.
The public building blocks are:
- lifecycle:
actions/prepare,actions/post-merge,actions/publication; - supporting release operations:
actions/stable-select,actions/artifact-validate,actions/metadata-inspect,actions/release-notes,actions/release-preflight,actions/appstore-publication-wait.
Consumers should call these Actions instead of downloading the PHAR or duplicating release-tool command bootstrap in workflow YAML. The Actions resolve the matching product version from this repository's VERSION file and verify the published PHAR checksum internally.
Pin Actions to an immutable commit SHA. Do not duplicate the release-tool semantic version in consumer shell, and do not reference main or a floating tag in production release automation.
The consumer repository supplies:
.nextcloud-release.yml;- GitHub App credentials;
- publisher workflow;
- project packaging command;
- changelog/version files;
- stable branches and milestones.
The shared tooling supplies:
- release planning;
- authorization checks;
- deterministic preparation;
- state contracts;
- history synchronization;
- milestone transition;
- release draft generation;
- publication verification.
Treat pull_request_target workflows carefully because they run in the base repository security context.
The release workflow should:
- check out the trusted base/release branch, not arbitrary PR code;
- validate the generated PR metadata before mutation;
- keep permissions empty at workflow level and grant them per job;
- use short-lived GitHub App tokens for mutations;
- pin third-party Actions by immutable SHA.
These properties are part of the reference integration and should not be weakened when adapting it.
LibreCodeCoop/release-tool is the source of truth for release behavior and its public release Actions. LibreCodeCoop/.github owns LibreCode's managed workflow templates that orchestrate those Actions. LibreSign's .github/workflows/prepare-release.yml is the reference consumer and should be materialized from that catalog rather than becoming a second implementation.