Super epic: Simplify LibreCode GitHub workflow and release architecture

[vitormattos]

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.

[vitormattos]

Phase 0 inventory refresh — initial findings

Current references and classification:

• LibreCodeCoop/extract: several workflows still use remote reusable-workflow callers from LibreCodeCoop/github-workflows/.github/workflows/*. These are current CI functions, but the consumption model is obsolete. They must be converted to materialized workflows during consumer cutover, not merely repointed.
• LibreCodeCoop/profile_fields:
  • .github/workflows/release-nextcloud-app.yml is a retired release path and should be removed, not redirected.
  • .github/workflows/sync-workflow-templates.yml is current and should move to the new catalog/helper owner after the catalog migration.
  • .github/workflows/appstore-build-publish.yml contains current release helper references that must move to release-tool ownership after the release compatibility/consolidation phases.
• LibreSign/libresign: current references exist in prepare-release, release-metadata, nightly-release, first-merged-pr-comment, and sync-workflow-templates. These remain current behavior and will be cut over only after the destination implementations are validated.
• LibreSign/documentation: release-process docs still describe github-workflows as orchestration owner; update after implementation cutover so documentation describes the final architecture.
• Source repository drift confirmed: workflow-catalog.json does not list release-nextcloud-app, but workflow-templates/release-nextcloud-app.yml, its properties metadata, license sidecar, and a workflow-family documentation entry still exist. This is a clearly retired artifact and will be removed in Phase 0.

Architectural discovery: extract demonstrates an existing reusable-workflow consumption path, while the target architecture requires complete materialized workflows in consumers. Consumer migration therefore needs to replace that model rather than preserve it.

No execution-order change is needed. I am removing only the clearly retired source artifact now, then proceeding to release-tool#55 before any large structural migration.

[vitormattos]

Phase 0 cleanup completed: #182 was merged as c63cc243322c6c7d4fe6580adae6c8c9fa7ebe89 after actionlint, zizmor, REUSE, workflow-policy, and Python test checks all passed. The retired release-nextcloud-app template, catalog metadata sidecar, license sidecar, and stale workflow-family documentation entry are now removed from the source repository. No compatibility path was retained. The remaining inventory findings are intentionally carried forward to their ordered migration phases (notably materializing current reusable-workflow consumers during consumer cutover).

[vitormattos]

Phase 1 completed. LibreCodeCoop/release-tool#55 landed via release-tool#61 (34cadc7defa914397dc852eb63c5a5cde6f5a6ec) with all repository gates green. The compatibility harness is process-based, uses deterministic local/fake GitHub fixtures, preserves redirect credential and archive traversal safety checks, and isolates implementation details behind a test target so the same scenarios can be exercised by the PHP port. Proceeding in the documented order to Phase 2 / release-tool#57.

[vitormattos]

Phase 1 is complete. LibreCodeCoop/release-tool#61 merged as 34cadc7defa914397dc852eb63c5a5cde6f5a6ec; release-tool#55 is closed. The compatibility suite is PHPUnit-driven, keeps Python only as isolated test fixtures with recorded provenance, exercises authorization, stable selection, artifact validation/restore security, and release-note behavior against deterministic local fixtures/fake HTTP, and passed PHPUnit, PHP quality, Infection, PHAR, workflow quality, and REUSE on the merge candidate. Phase 2 has started with release-tool#57; the first PHP port slice is PR #62.

[vitormattos]

All implementation phases are complete.

• release-tool consolidation epic is closed;
• .github catalog epic is closed;
• LibreSign, extract and profile_fields consumers are cut over;
• documentation reflects the resulting architecture;
• github-workflows implementation was removed in PR chore: retire github-workflows repository #183 and its main branch contains only retirement/license/security files;
• no current consumer file checked directly depends on this repository.

The only remaining program-level condition is the GitHub repository archive/read-only setting. GitHub currently reports archived=false, and the installed connector does not expose repository administration mutations. Keeping this super epic open until that single administrative action is performed, after which #180 and this issue can be closed.

[vitormattos]

Final program re-audit on 2026-09-24:

• release-tool#60 is closed;
• Epic: Make .github the single organization workflow catalog .github#58 is closed;
• no current code-search hit remains for LibreCodeCoop/github-workflows across LibreCodeCoop or LibreSign;
• no current code-search hit remains for retired release-nextcloud-app across either organization;
• github-workflows main contains only retirement/license/security files;
• repository state is still archived=false.

Therefore Phases 0–7 implementation work is complete except for the final repository archive/read-only administration flag. There is no remaining code change to make without inventing work or preserving obsolete compatibility. Once the repository is archived, #180 and this super epic can be closed.

[vitormattos]

LibreSign release-workflow correction is complete.

Merged:

• ci: keep release-tool implementation out of workflows LibreSign/libresign#8683 on main;
• [stable35] ci: backport release-tool cutover to stable35 LibreSign/libresign#8680 on stable35;
• [stable34] ci: backport release-tool cutover to stable34 LibreSign/libresign#8681 on stable34;
• [stable33] ci: backport release-tool cutover to stable33 LibreSign/libresign#8682 on stable33.

The follow-up removes the accidental consumer-side exposure introduced by #8679: no manual Release Tool PHAR bootstrap/checksum blocks and no direct consumer calls to internal release commands. Current main uses pinned Release Tool Actions for stable selection, artifact validation, release notes, metadata inspection, prepare, post-merge, and publication.

GitHub code search still surfaces old pre-merge commits containing the temporary PHAR/bootstrap implementation, but direct reads of current main confirm those blocks are gone. No current LibreSign workflow references LibreCodeCoop/github-workflows.

Program state remains blocked only on archiving LibreCodeCoop/github-workflows itself (archived=false).

[vitormattos]

Final audit found two residual items after the earlier implementation cutover:

1. LibreCodeCoop/release-tool still contained the one-shot .github/workflows/publish-v0.10.16.yml publisher. This was migration/release residue and has now been removed by release-tool#74.
2. The temporary Python reference harness remained under tests/Fixtures/PythonReference after parity had already been demonstrated. release-tool#75 removes that retired implementation while preserving the behavioral/security scenarios against the PHP target.

Documentation source in LibreSign/documentation is current and no longer references LibreCodeCoop/github-workflows, and gh-pages contains the corrected generated HTML. However, the public custom domain docs.libresign.coop is still serving substantially older content. LibreSign/documentation#104 tracks that publication/origin discrepancy.

Because the published documentation is still stale, I am not treating archival as fully complete yet even though organization code search has no current LibreCodeCoop/github-workflows references.

[vitormattos]

Final technical audit completed after the follow-up cleanup.

Validated current state:

• release-tool#74 removed the forgotten one-shot publish-v0.10.16.yml publisher;
• release-tool#75 removed the temporary release-specific Python reference implementation after parity, while retaining the behavioral/security scenarios against PHP;
• release-tool#76 aligned the architecture documentation with the actual public Action boundary;
• current release-tool/.github/workflows contains only the normal CI/release workflows; no version-specific one-shot publisher remains;
• searches across LibreCodeCoop and LibreSign return no current LibreCodeCoop/github-workflows references;
• searches across both organizations return no current release-nextcloud-app references;
• LibreSign/documentation source contains no current github-workflows references;
• the generated gh-pages release-process HTML is current and describes release-tool/.github ownership correctly. External web search still exposes a several-days-old crawl of the previous docs, which is stale indexing rather than a current repository dependency; documentation#104 tracks live-domain/search refresh verification.

There is no remaining technical dependency on this repository. The only program exit action still outstanding is setting LibreCodeCoop/github-workflows to archived/read-only; GitHub currently reports archived=false.