Skip to content

Commit 48e225f

Browse files
CybotTMCybotTM
authored
feat: add reusable CI workflows for TYPO3-Documentation repos (#56)
Add centralized, reusable GitHub Actions workflows that can be called by repositories across the TYPO3-Documentation organization: - backport.yml: Backport merged PRs via korthout/backport-action - docs-render.yml: Documentation rendering check - php-quality.yml: Code quality (CS Fixer, PHPStan, XML lint) - php-tests.yml: PHP test matrix (unit + integration) All actions are SHA-pinned. Reusable workflows execute in this repo's context, so only this repo's action allow-list needs maintenance. Ref: TYPO3-Documentation/TYPO3CMS-Reference-CoreApi#6414
1 parent ade6db6 commit 48e225f

5 files changed

Lines changed: 316 additions & 0 deletions

File tree

‎.github/workflows/reusable-backport.yml‎

Lines changed: 26 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,26 @@
1+
name: Backport
2+
on:
3+
workflow_call:
4+
inputs:
5+
label-pattern:
6+
description: 'Label pattern for backport branches (e.g. "backport *")'
7+
type: string
8+
default: 'backport *'
9+
10+
jobs:
11+
backport:
12+
permissions:
13+
contents: write
14+
pull-requests: write
15+
name: Backport
16+
runs-on: ubuntu-latest
17+
if: >
18+
github.event_name == 'pull_request_target' &&
19+
github.event.pull_request.merged == true &&
20+
contains(toJson(github.event.pull_request.labels), 'backport')
21+
steps:
22+
- name: Backport
23+
uses: korthout/backport-action@4aaf0e03a94ff0a619c9a511b61aeb42adea5b02 # v4.2.0
24+
with:
25+
label_pattern: "${{ inputs.label-pattern }}"
26+
merge_method: "none"

‎.github/workflows/reusable-docs-render.yml‎

Lines changed: 33 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,33 @@
1+
name: Documentation Rendering
2+
on:
3+
workflow_call:
4+
inputs:
5+
python-version:
6+
description: 'Python version'
7+
type: string
8+
default: '3.12'
9+
10+
jobs:
11+
render:
12+
permissions:
13+
contents: read
14+
name: Render Documentation
15+
runs-on: ubuntu-latest
16+
steps:
17+
- name: Checkout
18+
uses: actions/checkout@de0fac2e4500dabe0009e67214ff5f5447ce83dd # v6.0.2
19+
20+
- name: Set up Python
21+
uses: actions/setup-python@a309ff8b426b58ec0e2a45f0f869d46889d02405 # v6.2.0
22+
with:
23+
python-version: "${{ inputs.python-version }}"
24+
25+
- name: Render documentation
26+
run: |
27+
if [ -f "composer.json" ] && grep -q "typo3/guides-cli" composer.json; then
28+
composer install --no-interaction --no-progress --prefer-dist
29+
vendor/bin/guides --no-progress Documentation
30+
else
31+
pip install typo3-docs-theme
32+
typo3-docs-theme render Documentation
33+
fi

‎.github/workflows/reusable-php-quality.yml‎

Lines changed: 89 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,89 @@
1+
name: PHP Quality
2+
on:
3+
workflow_call:
4+
inputs:
5+
php-version:
6+
description: 'PHP version for quality checks'
7+
type: string
8+
default: '8.2'
9+
run-cs-fixer:
10+
description: 'Run PHP CS Fixer'
11+
type: boolean
12+
default: true
13+
cs-fixer-command:
14+
description: 'CS Fixer command'
15+
type: string
16+
default: 'make test-cs-fixer'
17+
run-phpstan:
18+
description: 'Run PHPStan'
19+
type: boolean
20+
default: true
21+
phpstan-command:
22+
description: 'PHPStan command'
23+
type: string
24+
default: 'make test-phpstan'
25+
run-xml-lint:
26+
description: 'Run XML lint'
27+
type: boolean
28+
default: false
29+
xml-lint-command:
30+
description: 'XML lint command'
31+
type: string
32+
default: 'make test-xml-lint'
33+
php-extensions:
34+
description: 'PHP extensions to install'
35+
type: string
36+
default: ''
37+
run-environment:
38+
description: 'RUN_ENVIRONMENT value'
39+
type: string
40+
default: 'local'
41+
42+
jobs:
43+
quality:
44+
permissions:
45+
contents: read
46+
name: Quality
47+
runs-on: ubuntu-latest
48+
steps:
49+
- name: Checkout
50+
uses: actions/checkout@de0fac2e4500dabe0009e67214ff5f5447ce83dd # v6.0.2
51+
52+
- name: Install PHP
53+
uses: shivammathur/setup-php@44454db4f0199b8b9685a5d763dc37cbf79108e1 # 2.36.0
54+
with:
55+
coverage: none
56+
php-version: "${{ inputs.php-version }}"
57+
extensions: "${{ inputs.php-extensions }}"
58+
59+
- name: Get Composer cache directory
60+
id: composer-cache
61+
run: echo "dir=$(composer config cache-files-dir)" >> "$GITHUB_OUTPUT"
62+
63+
- name: Cache Composer dependencies
64+
uses: actions/cache@cdf6c1fa76f9f475f3d7449005a359c84ca0f306 # v5.0.3
65+
with:
66+
path: ${{ steps.composer-cache.outputs.dir }}
67+
key: php-${{ inputs.php-version }}-composer-${{ hashFiles('**/composer.lock') }}
68+
restore-keys: php-${{ inputs.php-version }}-composer-
69+
70+
- name: Install dependencies
71+
run: composer install --no-interaction --no-progress --prefer-dist
72+
73+
- name: PHP CS Fixer
74+
if: inputs.run-cs-fixer
75+
run: ${{ inputs.cs-fixer-command }}
76+
env:
77+
RUN_ENVIRONMENT: ${{ inputs.run-environment }}
78+
79+
- name: PHPStan
80+
if: inputs.run-phpstan
81+
run: ${{ inputs.phpstan-command }}
82+
env:
83+
RUN_ENVIRONMENT: ${{ inputs.run-environment }}
84+
85+
- name: XML Lint
86+
if: inputs.run-xml-lint
87+
run: ${{ inputs.xml-lint-command }}
88+
env:
89+
RUN_ENVIRONMENT: ${{ inputs.run-environment }}

‎.github/workflows/reusable-php-tests.yml‎

Lines changed: 77 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,77 @@
1+
name: PHP Tests
2+
on:
3+
workflow_call:
4+
inputs:
5+
php-versions:
6+
description: 'JSON array of PHP versions'
7+
type: string
8+
default: '["8.2", "8.3", "8.4", "8.5"]'
9+
dependency-versions:
10+
description: 'Composer dependency versions (locked/highest/lowest)'
11+
type: string
12+
default: 'locked'
13+
test-unit-command:
14+
description: 'Unit test command'
15+
type: string
16+
default: 'make test-unit'
17+
test-integration-command:
18+
description: 'Integration test command (empty to skip)'
19+
type: string
20+
default: ''
21+
php-extensions:
22+
description: 'PHP extensions to install'
23+
type: string
24+
default: ''
25+
run-environment:
26+
description: 'RUN_ENVIRONMENT value'
27+
type: string
28+
default: 'local'
29+
30+
jobs:
31+
tests:
32+
permissions:
33+
contents: read
34+
name: "Tests (PHP ${{ matrix.php }})"
35+
runs-on: ubuntu-latest
36+
strategy:
37+
fail-fast: false
38+
matrix:
39+
php: ${{ fromJson(inputs.php-versions) }}
40+
steps:
41+
- name: Checkout
42+
uses: actions/checkout@de0fac2e4500dabe0009e67214ff5f5447ce83dd # v6.0.2
43+
44+
- name: Install PHP
45+
uses: shivammathur/setup-php@44454db4f0199b8b9685a5d763dc37cbf79108e1 # 2.36.0
46+
with:
47+
coverage: none
48+
php-version: "${{ matrix.php }}"
49+
extensions: "${{ inputs.php-extensions }}"
50+
51+
- name: Get Composer cache directory
52+
id: composer-cache
53+
run: echo "dir=$(composer config cache-files-dir)" >> "$GITHUB_OUTPUT"
54+
55+
- name: Cache Composer dependencies
56+
uses: actions/cache@cdf6c1fa76f9f475f3d7449005a359c84ca0f306 # v5.0.3
57+
with:
58+
path: ${{ steps.composer-cache.outputs.dir }}
59+
key: php-${{ matrix.php }}-composer-${{ hashFiles('**/composer.lock') }}
60+
restore-keys: php-${{ matrix.php }}-composer-
61+
62+
- name: Install dependencies
63+
run: composer install --no-interaction --no-progress --prefer-dist
64+
env:
65+
COMPOSER_NO_DEV: "0"
66+
67+
- name: Run unit tests
68+
if: inputs.test-unit-command != ''
69+
run: ${{ inputs.test-unit-command }}
70+
env:
71+
RUN_ENVIRONMENT: ${{ inputs.run-environment }}
72+
73+
- name: Run integration tests
74+
if: inputs.test-integration-command != ''
75+
run: ${{ inputs.test-integration-command }}
76+
env:
77+
RUN_ENVIRONMENT: ${{ inputs.run-environment }}

‎README.md‎

Lines changed: 91 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -1,5 +1,96 @@
11
# Build and Deployment Pipelines for TYPO3 Documentation
22

3+
## Reusable CI Workflows
4+
5+
Centralized, reusable GitHub Actions workflows for repositories in the
6+
[TYPO3-Documentation](https://github.com/TYPO3-Documentation) organization.
7+
8+
### Why
9+
10+
The TYPO3-Documentation org enforces a GitHub Actions **allow-list** with
11+
SHA-pinned actions. This creates two maintenance challenges:
12+
13+
1. **Composite actions break the allow-list.** Actions like
14+
`ramsey/composer-install` internally call `actions/cache@v4`, which the
15+
caller's allow-list must also approve. When the inner action updates its
16+
SHA, all callers break silently.
17+
18+
2. **~60 workflow files across ~29 repos** must each be updated when action
19+
SHAs change, backport tooling breaks, or CI patterns evolve.
20+
21+
Reusable workflows solve both problems: they execute in their **own**
22+
context (this repository), so only *this* repo's action references need to
23+
stay current. Callers reference a single workflow by tag/SHA and inherit
24+
all updates automatically.
25+
26+
### Available Reusable Workflows
27+
28+
| Workflow | Purpose |
29+
|----------|--------|
30+
| [`reusable-backport.yml`](.github/workflows/reusable-backport.yml) | Backport merged PRs via `korthout/backport-action` |
31+
| [`reusable-docs-render.yml`](.github/workflows/reusable-docs-render.yml) | Documentation rendering check |
32+
| [`reusable-php-quality.yml`](.github/workflows/reusable-php-quality.yml) | Code quality: CS Fixer, PHPStan, XML lint |
33+
| [`reusable-php-tests.yml`](.github/workflows/reusable-php-tests.yml) | PHP test matrix (unit + integration) |
34+
35+
### Usage
36+
37+
Call a workflow from your repository's workflow file:
38+
39+
```yaml
40+
name: CI
41+
on:
42+
push:
43+
branches: [main]
44+
pull_request:
45+
46+
jobs:
47+
tests:
48+
uses: TYPO3-Documentation/t3docs-ci-deploy/.github/workflows/reusable-php-tests.yml@main
49+
with:
50+
php-versions: '["8.2", "8.3", "8.4"]'
51+
test-unit-command: 'make test-unit'
52+
53+
quality:
54+
uses: TYPO3-Documentation/t3docs-ci-deploy/.github/workflows/reusable-php-quality.yml@main
55+
with:
56+
php-version: '8.2'
57+
58+
docs:
59+
uses: TYPO3-Documentation/t3docs-ci-deploy/.github/workflows/reusable-docs-render.yml@main
60+
```
61+
62+
Backport workflow (in a separate workflow file triggered on PRs):
63+
64+
```yaml
65+
name: Backport
66+
on:
67+
pull_request_target:
68+
types:
69+
- closed
70+
- labeled
71+
72+
jobs:
73+
backport:
74+
uses: TYPO3-Documentation/t3docs-ci-deploy/.github/workflows/reusable-backport.yml@main
75+
with:
76+
label-pattern: "backport *"
77+
```
78+
79+
Each workflow accepts optional inputs with sensible defaults.
80+
See the individual workflow files for the full list of inputs.
81+
82+
### Action SHA Pins
83+
84+
All actions are SHA-pinned to verified commits. Current pins:
85+
86+
| Action | Version | SHA |
87+
|--------|---------|-----|
88+
| `actions/checkout` | v6.0.2 | `de0fac2e4500dabe0009e67214ff5f5447ce83dd` |
89+
| `actions/cache` | v5.0.3 | `cdf6c1fa76f9f475f3d7449005a359c84ca0f306` |
90+
| `actions/setup-python` | v6.2.0 | `a309ff8b426b58ec0e2a45f0f869d46889d02405` |
91+
| `shivammathur/setup-php` | 2.36.0 | `44454db4f0199b8b9685a5d763dc37cbf79108e1` |
92+
| `korthout/backport-action` | v4.2.0 | `4aaf0e03a94ff0a619c9a511b61aeb42adea5b02` |
93+
394
## ViewHelper Reference
495

596
The Fluid ViewHelper Reference is generated automatically based on the PHP source files.

0 commit comments

Comments
 (0)