[TASK] Shared Reusable Workflows — Maintainer Guide & Checklist

[CybotTM]

Overview

This issue provides a complete guide through the shared reusable workflows initiative for the TYPO3 Documentation organization. It consolidates all related PRs, issues, decisions, and action items in one place.

Goal: Centralize GitHub Actions workflows in TYPO3-Documentation/.github so that ~29 documentation repositories share a single maintained set of CI/CD workflows instead of each maintaining their own inline copies.

Background: The initiative started with TYPO3-Documentation/TYPO3CMS-Reference-CoreApi#6414 after the broken m-kuhn/backport@30b6e83 action (missing dist/index.js) required individual fixes across repos.
Workflows were initially placed in t3docs-ci-deploy (TYPO3-Documentation/t3docs-ci-deploy#56), then moved to .github per suggestion by @jaapio, implemented by @linawolf.

cc: @linawolf @garvinhicking @jaapio

---

Merge Checklist

PRs should be reviewed and merged in this order:

Phase 1: Foundation (.github repo)

• [BUGFIX] Fix backport label_pattern default to use regex with capture group #4 —
  Fix reusable-backport.yml default label_pattern from glob (backport *) to regex with capture group (^backport ([^ ]+)$).
  korthout/backport-action requires a regex to extract the target branch.
  Merge first — fixes a bug on main.

• [TASK] Add reusable workflows for documentation testing, pre-commit, and PHP commands #2 —
  Add three new reusable workflows:

  • reusable-test-documentation.yml — Docker-based documentation rendering test
  • reusable-apply-precommit.yml — Scheduled pre-commit whitespace fixes with auto-PR
  • reusable-php-command.yml — Generic PHP + Composer + run command

• [TASK] Add concise README with workflow status #3 —
  Documentation and architecture decisions:

  • Enhanced README.md documenting all 7 workflows
  • TYPO3-style RST Documentation under /Documentation
  • ADR-001: Rationale for shared reusable workflows
  • ADR-002: Choice of .github repo over t3docs-ci-deploy

Phase 2: Consumer repos (after Phase 1)

These can be merged in any order once Phase 1 is complete:

• [TASK] Migrate backport to shared reusable workflow TYPO3CMS-Reference-CoreApi#6414 —
  Migrate backport.yml to shared workflow.
  Depends on: [BUGFIX] Fix backport label_pattern default to use regex with capture group #4

• [TASK] Migrate backport and documentation workflows to shared reusable workflows TYPO3CMS-Tutorial-Editors#258 —
  Migrate backport.yml + documentation.yml to shared workflows.
  Depends on: [BUGFIX] Fix backport label_pattern default to use regex with capture group #4, [TASK] Add reusable workflows for documentation testing, pre-commit, and PHP commands #2

• [TASK] Migrate CI to shared reusable workflows render-guides#1196 —
  Migrate all 6 CI jobs in main.yaml to shared workflows (tests, quality, composer-normalize, test-docs, test-rendertest, validate-monorepo).
  Note: PHP 8.1 intentionally dropped from test matrix (see also [TASK] Raise minimum PHP to 8.2, update DDEV to PHP 8.2 and Node.js 20 render-guides#1183).
  Depends on: [TASK] Add reusable workflows for documentation testing, pre-commit, and PHP commands #2

• [TASK] Migrate workflows to shared reusable workflows from .github TYPO3CMS-Tutorial-GettingStarted#792 —
  Migrate test-documentation.yml + apply-precommit.yml to shared workflows.
  backport.yml was already migrated by @linawolf.
  Depends on: [TASK] Add reusable workflows for documentation testing, pre-commit, and PHP commands #2

Phase 3: Strategy & future work

• [TASK] Add ADR-003: Versioning strategy for shared workflow references #6 — ADR-003: Versioning strategy for workflow references (@main vs @tag vs @SHA). Requesting maintainer feedback. Current PRs use @main; the already-merged GettingStarted backport uses @SHA. The ADR recommends @main to avoid reintroducing per-repo maintenance burden.

• [TASK] Migrate remaining repos to shared reusable workflows #5 — Tracking issue for migrating the remaining 6 repos (TCA, Typoscript, ViewHelper, SitePackage, FrontendLocalization, blog_example). To be done after the initial batch is proven stable.

---

Available Shared Workflows

After #2 is merged, the repository provides 7 reusable workflows:

Workflow	On main	Purpose
reusable-backport.yml	✅	Automated backporting via labels
reusable-docs-render.yml	✅	Python/Composer-based doc rendering
reusable-php-quality.yml	✅	PHP CS Fixer + PHPStan
reusable-php-tests.yml	✅	PHP unit/integration test matrix
reusable-test-documentation.yml	After #2	Docker-based doc rendering test
reusable-apply-precommit.yml	After #2	Scheduled pre-commit whitespace fixes
reusable-php-command.yml	After #2	Generic PHP + Composer + command

---

Key Decisions

Decision	Rationale	Reference
Use .github repo (not t3docs-ci-deploy)	Org community health repo — workflows automatically trusted, no allow-list config needed	ADR-002 in #3
Centralize workflows	Single point of maintenance for action versions, consistent behavior, faster incident response	ADR-001 in #3
Reference @main (not @SHA)	SHA-pinning shared workflows reintroduces per-repo maintenance — defeats the purpose	ADR-003 in #6 (proposed)

---

Related PRs (not part of this initiative but relevant)

• [TASK] Update and SHA-pin all GitHub Actions render-guides#1184 — SHA-pin all GitHub Actions in render-guides (by @CybotTM)
• [TASK] Raise minimum PHP to 8.2, update DDEV to PHP 8.2 and Node.js 20 render-guides#1183 — Raise minimum PHP to 8.2 (by @CybotTM)
• [TASK] Replace ramsey/composer-install to fix org action allow-list render-guides#1195 — Replace ramsey/composer-install to fix allow-list (interim fix, by @CybotTM)
• [TASK] Add reusable CI workflows for TYPO3-Documentation repos t3docs-ci-deploy#56 — Original shared workflows placement (superseded by .github repo)

---

Questions for maintainers

1. Merge order — Does the proposed Phase 1 → Phase 2 → Phase 3 order work for you?
2. Versioning — Please review [TASK] Add ADR-003: Versioning strategy for shared workflow references #6 (ADR-003) for the @main vs @tag vs @SHA decision.
3. GettingStarted as test ground — @linawolf suggested using GettingStarted for initial testing. Should we mark [TASK] Migrate workflows to shared reusable workflows from .github TYPO3CMS-Tutorial-GettingStarted#792 as the first consumer to merge?
4. Branch protection — Should we add branch protection rules to this repo given that a broken push to main affects all consumers?