Super epic: Simplify LibreCode GitHub workflow and release architecture #181

Objective

Simplify LibreCode's GitHub automation architecture by removing unnecessary repository layers, placing responsibilities with their natural owners, preserving testability, and retiring LibreCodeCoop/github-workflows when the migration is complete.

Target architecture

nextcloud/.github
        ↓
LibreCodeCoop/.github
        ↓
consumer repositories

Release implementation is owned separately by:

LibreCodeCoop/release-tool
        ↑
consumed by materialized workflows from LibreCodeCoop/.github

There must be no permanent github-workflows hop between upstream, the organization catalog, and consumers.

Child epics

• Organization workflow catalog: Epic: Make .github the single organization workflow catalog .github#58
• Release product consolidation: Epic: Consolidate the complete release product in release-tool release-tool#60
• Final retirement of this repository: Retire github-workflows after ownership migrations #180

Architectural boundaries

LibreCodeCoop/.github owns

• current organization workflow templates;
• upstream Nextcloud workflow provenance, vendoring and pins that are still required;
• LibreCode organization-level patches that are still required;
• deterministic upstream refresh/render/policy tooling;
• workflow synchronization into consumers;
• actions/sync-workflows;
• actions/first-merged-pr-comment;
• tests for the catalog/synchronization layer;
• organization-level workflow adoption, dependency, security and synchronization documentation.

LibreCodeCoop/release-tool owns

• PHP release engine;
• CLI/PHAR;
• release lifecycle GitHub Actions;
• release-specific GitHub/Git/archive infrastructure;
• release contracts and domain behavior;
• release tests;
• release product documentation;
• release versioning.

Public Action API should converge on the actual lifecycle stages:

• actions/prepare
• actions/post-merge
• actions/publication

Existing helper Actions must be treated as implementation details unless an independent public use case is demonstrated.

github-workflows owns nothing permanently

This repository is only a temporary migration source. It must be archived after all current responsibilities have moved or been removed.

Non-negotiable rules

Materialized workflows

Consumer repositories must keep complete workflow YAML files. Do not replace the organization catalog with reusable-workflow callers that hide workflow implementation behind jobs.<name>.uses.

Composite/custom Actions are allowed where they encapsulate procedural implementation while keeping the workflow structure visible.

No legacy preservation by default

Migration is not a copy-everything exercise.

If a workflow, script, test, generated file, compatibility path, manifest or document is not part of the target architecture, remove it from the source repository instead of migrating it.

Do not introduce compatibility shims solely to keep obsolete LibreCodeCoop/github-workflows paths alive.

Known retired item:

• workflow-templates/release-nextcloud-app.yml — remove it, its metadata, and references/tests/docs that only exist for that retired workflow.

Apply the same rule to any other stale artifact found during implementation.

Testability

Reducing layers must not reduce test coverage.

Preserve or improve tests for:

• upstream commit pinning and checksums;
• patch application;
• deterministic rendering;
• actionlint;
• zizmor;
• workflow policy;
• Dependabot-managed Action pins;
• workflow synchronization;
• actions-lock provenance;
• consumer-local patches;
• divergence detection;
• release contracts;
• prepare/post-merge/publication;
• authorization;
• redirect credential safety;
• archive path traversal;
• release artifact validation.

Tests must live with the code they validate.

Python to PHP release migration

Do not translate release Python line-by-line.

Before replacing release-specific Python:

1. create PHPUnit-driven language-independent characterization tests;
2. execute the current Python implementation as a temporary reference;
3. use deterministic fixtures and a local/fake GitHub API;
4. compare observable behavior such as exit codes, stdout/stderr, JSON, Action outputs, filesystem changes, HTTP behavior and archive behavior;
5. implement the PHP equivalent behind simple interfaces;
6. remove Python only after parity is demonstrated.

Prefer minimal PHP infrastructure. Add external SDKs only when a concrete benefit is demonstrated.

Execution order

Work in this order unless a discovered hard dependency requires a documented adjustment.

Phase 0 — Inventory and cleanup

1. Re-read this super epic and both child epics.
2. Refresh the repository inventory before making structural changes.
3. Search LibreCodeCoop and LibreSign for:
   • LibreCodeCoop/github-workflows
   • release-nextcloud-app
   • other obsolete workflow/action paths.
4. Classify every hit as:
   • current → migrate/repoint;
   • retired → remove.
5. Remove clearly retired artifacts that have no valid consumer.

Do not begin large code moves before this inventory is current.

Phase 1 — Establish release behavioral safety net

Implement release-tool#55 first.

• Import the release-specific Python implementation only as a temporary reference fixture.
• Build PHP-driven characterization tests.
• Cover security-sensitive and failure behavior.
• Make CI require the reference behavior before starting the rewrite.

This phase is a prerequisite for replacing release Python.

Phase 2 — Consolidate release-tool

Execute the remaining work in release-tool#60.

Recommended order:

1. behavioral compatibility harness;
2. define PHP infrastructure boundaries;
3. port release-specific behavior into PHP;
4. reduce helper Actions to internal implementation where appropriate;
5. expose the public lifecycle Actions;
6. unify versioning;
7. migrate release documentation;
8. update organization templates to point to release-tool.

Do not remove the reference Python until parity is achieved.

Phase 3 — Move the workflow catalog to .github

Execute LibreCodeCoop/.github#58.

Recommended order:

1. move current upstream provenance/vendor/patch data;
2. move render/refresh/policy tooling and tests;
3. move current workflow templates;
4. move sync-workflows;
5. move first-merged-pr-comment;
6. configure Dependabot directly for /workflow-templates;
7. remove the old catalog publication hop;
8. determine whether workflow-catalog.json still has a real purpose; remove it if it only served the old publication model;
9. reconcile and rewrite documentation.

Phase 4 — Consumer cutover

Review every current consumer individually.

Known references include:

LibreCodeCoop/extract

Managed workflow files currently reference LibreCodeCoop/github-workflows.

Repoint current functionality to the new owner.

LibreCodeCoop/profile_fields

Known files include:

• .github/workflows/release-nextcloud-app.yml
• .github/workflows/sync-workflow-templates.yml
• .github/workflows/appstore-build-publish.yml

Do not repoint the retired release-nextcloud-app.yml to a compatibility path. Decide whether the repository should adopt the current prepare-release model; otherwise remove the retired workflow.

LibreSign/libresign

Known files include:

• .github/workflows/prepare-release.yml
• .github/workflows/release-metadata.yml
• .github/workflows/first-merged-pr-comment.yml
• .github/workflows/nightly-release.yml
• .github/workflows/sync-workflow-templates.yml

Move current Action references to their new immutable owners.

LibreSign/documentation

Update release-process documentation so it describes the resulting architecture, not the transition state.

Phase 5 — End-to-end validation

Before retiring this repository, validate real flows:

1. nextcloud/.github → LibreCodeCoop/.github → consumer;
2. consumer sync no-op after successful adoption;
3. consumer-local patch application;
4. divergence detection;
5. release prepare → post-merge → publication;
6. nightly workflow with release-tool-owned helpers;
7. dependency updates on organization workflow templates.

Review actual workflow logs, not only static tests.

Phase 6 — Remove the old architecture

Only after cutover:

• remove catalog-publish.yml;
• remove sync_catalog.py if it has no remaining role;
• remove old VERSION/repository release machinery;
• remove stale generated outputs;
• remove superseded docs;
• remove tests that only validate deleted behavior;
• remove remaining legacy Action paths;
• remove compatibility references.

Phase 7 — Final audit and archival

Search both organizations again for:

• LibreCodeCoop/github-workflows
• release-nextcloud-app
• obsolete Action names/paths;
• documentation naming the old source-of-truth model.

Resolve every remaining current reference.

Then:

• confirm both destination epics are complete;
• confirm Retire github-workflows after ownership migrations #180 exit criteria;
• archive this repository.

Change-management rules

For each meaningful unit of work:

• use an appropriate branch and pull request;
• keep PR scope aligned with one issue or clearly documented group of tightly coupled issues;
• run relevant tests before opening/updating the PR;
• inspect the final diff;
• monitor CI;
• fix failures before considering the issue complete;
• update the corresponding issue with important discoveries, changed assumptions, migration caveats or validated outcomes.

Do not put secrets, token values, private keys, credentials, or secret contents in issues, commits, logs or documentation. Public secret/variable names and required permission descriptions are fine.

Definition of done

This program is complete when:

• LibreCodeCoop/.github is the single workflow-catalog intermediary;
• LibreCodeCoop/release-tool owns the entire release product;
• consumers retain materialized workflows;
• current consumer references use the new owners;
• retired functionality is removed rather than shimmed;
• documentation matches the actual implementation;
• tests and real workflow executions validate the new architecture;
• no active reference to LibreCodeCoop/github-workflows remains;
• this repository is archived.