[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

---

Status update (2026-07-04)

• All 7 original reusable workflows are on main; reusable-backport.yml is in production in 9 repos (mostly via SHA pins added in June, which have already drifted — see ADR-003 below).
• Only blog_example still uses the broken m-kuhn/backport@30b6e83 — tracked in [TASK] Migrate remaining repos to shared reusable workflows #5; migration PR open: blog_example#188.
• Version-branch drift (action bumps only reach main, never the maintained 12.4/13.4/14.3 branches) was root-caused via FrontendLocalization#136 / #137; per-repo Dependabot target-branch PRs now cover 10 repos.
• New PRs in this repo: [TASK] Add reusable Node command workflow #15 (first Node.js reusable) and [FEATURE] Add CI gate for the shared reusable workflows (lint, security, conformance, freshness) #16 (CI gate: actionlint, yamllint, zizmor, conformance — answers question 4 below).

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.

• [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 —
  Merged as a slimmed-down version: concise README.md documenting all workflows with adoption status. The originally planned RST Documentation structure and ADR-001/ADR-002 did not land and would need a new PR if still wanted.

Phase 2: Consumer repos (after Phase 1)

• [TASK] Migrate workflows to shared reusable workflows from .github TYPO3CMS-Tutorial-GettingStarted#792 — merged 2026-03-23.
• [TASK] Migrate backport to shared reusable workflow TYPO3CMS-Reference-CoreApi#6414 — closed unmerged; the backport migration was completed directly on main instead (SHA-pinned). Remaining inline workflows tracked in [TASK] Migrate remaining repos to shared reusable workflows #5.
• [TASK] Migrate backport and documentation workflows to shared reusable workflows TYPO3CMS-Tutorial-Editors#258 — open. Migrates backport.yml + documentation.yml to @main references.
• [TASK] Migrate CI to shared reusable workflows render-guides#1196 — open, approved. Migrates all 6 CI jobs in main.yaml to shared workflows. PHP 8.1 intentionally dropped from the matrix (see [TASK] Raise minimum PHP to 8.2, update DDEV to PHP 8.2 and Node.js 20 render-guides#1183, merged).

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. Now backed by production evidence: the June SHA-pin migrations have already drifted across two commits (161f3be vs 46ed94f), so most consumers miss the latest backport fixes.
• [TASK] Migrate remaining repos to shared reusable workflows #5 — Tracking issue for the remaining migrations (updated 2026-07: backport done in 5/6 repos via SHA pins; blog_example still broken; inline test/documentation workflows remain).

Phase 4: Hardening & freshness (new, June/July 2026)

• [TASK] Add reusable Node command workflow #15 — reusable-node-command.yml, first Node.js reusable (consumer: render-guides theme-js-tests).
• [FEATURE] Add CI gate for the shared reusable workflows (lint, security, conformance, freshness) #16 — CI gate for this repo: actionlint, yamllint --strict, zizmor security audit, conformance script (README table ↔ files, documented inputs), hash-locked tooling, Dependabot with cooldown. Includes zizmor-driven hardening of the existing reusables.
• Dependabot target-branch config for maintained version branches — 10 per-repo PRs open (12.4/13.4/14.3; blog_example 12.4/13.4), e.g. [TASK] Enable Dependabot workflow updates on maintained version branches TYPO3CMS-Guide-FrontendLocalization#138.
• Follow-ups from [FEATURE] Add CI gate for the shared reusable workflows (lint, security, conformance, freshness) #16: backport token modernization (create-github-app-token v1 → v3 with scoped permissions), behavioral smoke tests once [TASK] Add reusable Node command workflow #15 is merged, required status checks via branch protection.

---

Available Shared Workflows

All on main:

Workflow	Purpose
reusable-backport.yml	Automated backporting via labels (production, 9 repos)
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	Docker-based doc rendering test
reusable-apply-precommit.yml	Scheduled pre-commit whitespace fixes
reusable-php-command.yml	Generic PHP + Composer + command
reusable-node-command.yml	Generic Node.js + npm command — pending #15

---

Key Decisions

Decision	Rationale	Reference
Use .github repo (not t3docs-ci-deploy)	Org community health repo — workflows automatically trusted, no allow-list config needed	Discussion in #3 (planned ADR-002 not landed)
Centralize workflows	Single point of maintenance for action versions, consistent behavior, faster incident response	Discussion in #3 (planned ADR-001 not landed)
Reference @main (not @SHA)	SHA-pinning shared workflows reintroduces per-repo maintenance — the June SHA-pin drift proves it	ADR-003 in #6 (proposed)
Gate main with CI	@main consumers need every merge validated: lint, security audit, conformance, freshness	#16

---

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 (open, refreshed 2026-07-04)
• [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 (merged 2026-03-20)
• [TASK] Replace ramsey/composer-install to fix org action allow-list render-guides#1195 — Replace ramsey/composer-install (closed unmerged; interim fix, superseded)
• [TASK] Add reusable CI workflows for TYPO3-Documentation repos t3docs-ci-deploy#56 — Original shared workflows placement (merged; superseded by .github repo)

---

Questions for maintainers

1. Merge order — Does the proposed Phase 1 → 2 → 3 → 4 order work for you? (Phase 1 is complete.)
2. Versioning — Please review [TASK] Add ADR-003: Versioning strategy for shared workflow references #6 (ADR-003); the SHA-pin drift makes this decision urgent.
3. GettingStarted as test ground — Done: [TASK] Migrate workflows to shared reusable workflows from .github TYPO3CMS-Tutorial-GettingStarted#792 merged 2026-03-23 and has been stable since.
4. Branch protection — Concretely proposed via [FEATURE] Add CI gate for the shared reusable workflows (lint, security, conformance, freshness) #16 (CI gate); remaining admin step: mark the four gate jobs as required status checks.

[CybotTM]

@garvinhicking, I updated this for your convenience.