Repository navigation
440 lines (440 loc) · 21.7 KB
/
Copy pathcontinuous-integration.yml
File metadata and controls
440 lines (440 loc) · 21.7 KB
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
218
219
220
221
222
223
224
225
226
227
228
229
230
231
232
233
234
235
236
237
238
239
240
241
242
243
244
245
246
247
248
249
250
251
252
253
254
255
256
257
258
259
260
261
262
263
264
265
266
267
268
269
270
271
272
273
274
275
276
277
278
279
280
281
282
283
284
285
286
287
288
289
290
291
292
293
294
295
296
297
298
299
300
301
302
303
304
305
306
307
308
309
310
311
312
313
314
315
316
317
318
319
320
321
322
323
324
325
326
327
328
329
330
331
332
333
334
335
336
337
338
339
340
341
342
343
344
345
346
347
348
349
350
351
352
353
354
355
356
357
358
359
360
361
362
363
364
365
366
367
368
369
370
371
372
373
374
375
376
377
378
379
380
381
382
383
384
385
386
387
388
389
390
391
392
393
394
395
396
397
398
399
400
401
402
403
404
405
406
407
408
409
410
411
412
413
414
415
416
417
418
419
420
421
422
423
424
425
426
427
428
429
430
431
432
433
434
435
436
437
438
439
440
# Use `continuous-integration.yml` from both your pull request and default-branch
# workflows. Pin the same reviewed commit in each caller. An application can use
# lint and tests without enabling Composer package publication.
#
# ```yaml
# permissions: {}
# jobs:
# checks:
# uses: hoverkraft-tech/ci-github-php/.github/workflows/continuous-integration.yml@<commit-sha>
# permissions:
# contents: read
# id-token: write
# ```
#
# Define `lint:ci` and `test:ci` in `composer.json`. These are explicit project commands;
# they execute even when dependency installation scripts are disabled. An empty
# `lint` or `test` input disables that job; `test: "false"` also disables tests. Missing named scripts fail the job. `lint` also accepts a JSON object such as
# `lint: '{"command":"lint:custom"}'`, or `"false"` to skip linting.
#
# Use `runs-on` for a JSON array of Linux runner labels, for example
# `runs-on: '["self-hosted", "linux"]'`. Every job uses those labels.
# Docker must be available for the PHP version discovery action.
# Set `checks: false` to skip lint, tests, dependency review and distribution checks.
#
# ### Runtime and dependencies
#
# With no `php-versions` input, CI reads `composer.json`'s `require.php` and
# discovers released stable versions from PHP.net using Composer's constraint parser.
# Discovery runs in its own container without changing the runner's PHP installation.
# It tests the newest compatible patch of every matching minor, including end-of-life
# versions still allowed by the project. Prereleases are excluded. Missing or invalid
# constraints and release-catalog failures stop discovery instead of choosing an arbitrary runtime.
# The highest discovered version runs lint and package checks and publishes coverage.
# Set `php-versions` explicitly to override the matrix, for example `'["8.2", "8.5"]'`.
# The last explicit entry is primary; an empty entry delegates to the setup action,
# which honors `.php-version` and Composer platform overrides before automatic discovery.
# See [PHP version selection](../../actions/get-php-versions/README.md#local-docker-builds) for local Docker builds.
#
# Composer projects with or without a committed lockfile are supported. Each
# project is installed independently. By default, setup installs the root manifest
# and `tools/composer.json` when it exists. It does not search nested directories.
# Use `composer-directories` to override discovery, for example `["."]` for the root
# only or `[".", "dev-tools"]` for another tooling directory. Only Composer's download cache is shared between
# runs; dependencies are installed and platform requirements checked each time.
#
# Installation scripts and plugins are disabled by default. Use
# `ignore-scripts: false` when installation hooks are required. Use
# `ignore-plugins: false` for a project with explicit Composer `allow-plugins`
# configuration, such as PHPStan's extension installer. These options affect
# installation, not explicit lint or test commands.
#
# For custom jobs, call `actions/setup-php` after checkout, then the individual
# lint or test actions. `install-dependencies: false` prepares the runtime
# without installing the project, for example before isolated package checks.
#
# ### Reports and coverage
#
# The lint and test actions reuse `ci-github-common/actions/quality/parse-ci-reports` for
# GitHub annotations and job summaries. The test action runs your Composer script unchanged. The script selects its test tool,
# preparation, configuration and report formats. For PHPUnit, keep the everyday test
# command and add a CI script:
#
# ```json
# {
# "scripts": {
# "test": "phpunit --configuration tests/phpunit.xml",
# "test:ci": "@test --log-junit=junit.xml --coverage-cobertura=cobertura.xml"
# }
# }
# ```
#
# The action sets `CI=true` and adds no test-runner arguments. JUnit reports are
# parsed even after the command fails. The same Composer command runs on every PHP
# version; only the last version publishes coverage. The `coverage` option controls
# publication, not collection. Set it to an empty string to skip coverage publication;
# omit coverage arguments from your script when collection is not needed.
#
# For Codecov, use `--coverage-clover=clover.xml` in the script and configure:
#
# ```yaml
# with:
# test: '{"coverage":"codecov"}'
# ```
#
# Codecov requires `id-token: write` and repository access. The action discovers
# Clover reports, falling back to Cobertura. For GitHub coverage summaries, generate
# Cobertura. Add generated report files to `.gitignore`. Clean any retained report
# files in your project command if it reuses an existing workspace.
#
# The lint and test actions upload only parsed native reports, including after a
# failed command, and retain them for seven days. Their `report-artifact-id`
# output identifies the artifact; it is empty when no supported reports were
# found. Test artifacts include coverage only with `coverage: github`.
# Codecov upload remains separate. Console-only lint output creates no artifact;
# configure a supported file report such as PHPStan Checkstyle for consolidation.
#
# Individual comments are disabled by default, keeping producer jobs read-only.
# When calling an action directly, set `comment: true` and grant
# `pull-requests: write` to opt in. Human and bot actors follow the same rules;
# fork PRs keep summaries, annotations and artifacts without commenting.
#
# For custom producer jobs named `lint` and `test`, leave individual comments
# disabled and add one final job using the common reporting workflow:
#
# ```yaml
# reports:
# needs: [lint, test]
# if: always()
# uses: hoverkraft-tech/ci-github-common/.github/workflows/ci-reports.yml@d606f77fad305ef07dfde3db5270f5e324019c97 # 4.2.4
# permissions:
# contents: read
# pull-requests: write
# with:
# job-results: ${{ toJSON(needs) }}
# ```
#
# This updates one comment each for tests, coverage and lint, with details
# collapsed. Keep producer job IDs aligned with the shared reporter's contract;
# when wrapping producers in reusable workflows, use matching caller and inner
# job IDs. The full CI workflow uses inner `lint` and `test` jobs; use the
# individual actions when you need to compose them with this final reporter.
# Keep producer jobs as required checks: report publication does not replace them.
#
# Preparation belongs in the Composer script, with report arguments attached only
# to the test command:
#
# ```json
# {
# "scripts": {
# "test:ci": [
# "@test:load-fixtures",
# "@test --log-junit=junit.xml --coverage-clover=clover.xml"
# ]
# }
# }
# ```
#
# Pest and Codeception projects use the same contract; define their commands and
# report options in Composer. No test-runner selection is needed in the action.
# Use `command` for a script name other than `test:ci`. Group custom settings in one
# input, omitting fields that use defaults:
#
# ```yaml
# with:
# test: '{"coverage":"codecov","cache":".cache"}'
# ```
#
# The test `cache` option can retain a directory of generated test fixtures or results. Do not
# cache `vendor`; Composer installation manages dependencies.
#
# Dependency review runs only on pull requests. PHP CodeQL analysis is not part of
# the workflow because PHP is not a supported CodeQL language. Run your PHP static
# analyzer through the lint script.
#
# ### Generated application files and documentation
#
# Projects needing asset compilation or generated code keep those steps in their
# Composer commands or dedicated caller jobs. PHP libraries need no generic build
# step; Composer distributes committed source selected by Git export rules.
#
# For API documentation, use `documentation.yml`, with optional `runs-on` labels
# for a Linux runner supporting Docker. It uses the project's phpDocumentor
# configuration when present, otherwise `src/`, and uploads a site containing
# `phpdoc/`. Run it during pull request validation and restore its `artifact-id` into
# `_site` for a separate deployment job using `ci-github-publish` actions. Site
# publishing and project-specific documentation transformations remain in the caller.
#
# ### Package checks
#
# Set `package: "true"` for a public Composer package at the Git repository root. The
# test action snapshots the checked-out commit using `git archive`, respecting
# `.gitattributes` `export-ignore` and `export-subst`. Uncommitted files and generated
# build output are not included.
#
# The test action validates `composer.json`, verifies declared PSR autoload paths,
# autoload files, and binaries, installs the archive in an isolated consumer with
# production dependencies, checks platform requirements, and loads the autoloader.
# Installation hooks and plugins remain disabled in that consumer.
#
# Distribution testing is disabled by default. Omit `package` or pass `"false"` to skip it.
# The input is a string, so boolean values must be quoted. A JSON object enables
# distribution testing with specific options; unknown options and non-string `tests` fail
# configuration validation.
#
# Use `tests` only for behavior specific to your package, such as rendering a
# template or invoking a CLI:
#
# ```yaml
# with:
# package: '{"tests":"my-cli --help"}'
# ```
#
# Commands execute in the consumer, with `vendor/bin`
# on `PATH` and `PACKAGE_NAME`, `PACKAGE_INSTALL_PATH`, and `PACKAGE_ARCHIVE_PATH`
# available. The temporary consumer is removed after success or failure. Modifying
# the temporary source archive fails validation. Nothing is uploaded: this tests
# the files GitHub will distribute, without adding a package publication step.
#
# Package checks run on the primary PHP version. The source test matrix remains
# responsible for compatibility across every supported PHP version. Release callers should depend on successful validation with `needs`.
name: Continuous integration
on:
workflow_call:
inputs:
runs-on:
description: JSON array of Linux runner labels. Applies to every job, including the configuration job.
type: string
default: '["ubuntu-latest"]'
checks:
description: Enable lint, tests, dependency review and optional distribution checks.
type: boolean
default: true
working-directory:
description: Composer project directory relative to the checkout.
type: string
default: .
php-versions:
description: Optional JSON array overriding Composer-based PHP discovery. Empty discovers the newest stable compatible patch per minor. The last version runs lint/package checks and publishes coverage. An empty entry uses the setup action default.
type: string
default: ""
extensions:
description: PHP extensions forwarded to setup-php.
type: string
default: mbstring, dom, xml, xmlwriter, curl, zip, intl
composer-directories:
description: Optional JSON array of Composer directories relative to working-directory. Empty installs the root project and tools/composer.json when present, without recursive discovery.
type: string
default: ""
ignore-scripts:
description: Disable Composer installation scripts. Explicit project commands still run.
type: boolean
default: true
ignore-plugins:
description: Disable Composer plugins during installation. When false, Composer allow-plugins configuration still applies.
type: boolean
default: true
lint:
description: Composer lint script name or a JSON object with `command` (default `lint:ci`). Pass "false", "null" or an empty string to disable.
type: string
default: "true"
test:
description: |
Run the Composer `test:ci` script unchanged, or provide another script name.
Pass "false", "null" or an empty string to disable tests.
A JSON object groups test options: `command` (default `test:ci`),
`coverage` (`github`, `codecov` or empty), and `cache` (one directory relative to working-directory).
Configure report/coverage generation in the Composer script itself.
Coverage is published on the last PHP version only; the command controls collection on every version. Codecov requires id-token: write.
Example: `{"coverage":"codecov","cache":".cache"}`.
type: string
default: "true"
package:
description: |
Validate a public Composer source distribution from the Git repository root.
Pass "false" (the default) to disable, "true" for archive and autoload checks,
or a JSON object with `tests` for additional commands in an isolated Composer consumer.
Quote booleans because this input has type string. Example: `{"tests":"my-cli --help"}`.
vendor/bin is on PATH; PACKAGE_NAME, PACKAGE_INSTALL_PATH and PACKAGE_ARCHIVE_PATH identify the package.
Unknown options and non-string tests are rejected before distribution checks.
type: string
default: "false"
dependency-review:
description: Review dependency changes on pull requests.
type: boolean
default: true
permissions: {}
jobs:
configuration:
runs-on: ${{ fromJSON(inputs.runs-on) }}
permissions:
contents: read
outputs:
versions: ${{ steps.config.outputs.versions }}
primary-version: ${{ steps.config.outputs.primary-version }}
lint: ${{ steps.config.outputs.lint }}
test: ${{ steps.config.outputs.test }}
package-enabled: ${{ steps.package-config.outputs.enabled }}
package-tests: ${{ steps.package-config.outputs.tests }}
steps:
- uses: actions/checkout@3d3c42e5aac5ba805825da76410c181273ba90b1 # v7.0.1
if: inputs.checks && inputs.php-versions == ''
with:
persist-credentials: false
- id: versions
if: inputs.checks && inputs.php-versions == ''
uses: $/actions/get-php-versions
with:
working-directory: ${{ inputs.working-directory }}
- id: package-config
uses: actions/github-script@3a2844b7e9c422d3c10d287c895573f7108da1b3 # v9.0.0
env:
PACKAGE_INPUT: ${{ inputs.package }}
with:
script: |
let config;
try {
config = JSON.parse(process.env.PACKAGE_INPUT.trim() || 'false');
} catch {
throw new Error('package must be true, false, or a JSON object.');
}
if (typeof config !== 'boolean' && (!config || typeof config !== 'object' || Array.isArray(config))) {
throw new Error('package must be true, false, or a JSON object.');
}
const enabled = config !== false;
if (typeof config === 'boolean') config = {};
const unknown = Object.keys(config).filter(key => key !== 'tests');
if (unknown.length) throw new Error(`Unknown package options: ${unknown.join(', ')}.`);
const { tests = '' } = config;
if (typeof tests !== 'string') throw new Error('package.tests must be a string.');
core.setOutput('enabled', enabled);
core.setOutput('tests', tests);
- id: config
uses: actions/github-script@3a2844b7e9c422d3c10d287c895573f7108da1b3 # v9.0.0
env:
VERSIONS: ${{ inputs.php-versions || steps.versions.outputs.php-versions }}
LINT: ${{ inputs.lint }}
TEST: ${{ inputs.test }}
with:
script: |-
const versions = process.env.VERSIONS.trim() ? JSON.parse(process.env.VERSIONS) : [''];
if (!Array.isArray(versions) || !versions.length || versions.length > 20 || versions.some(version => typeof version !== 'string' || (version && !/^\d+\.\d+(?:\.\d+)?$/.test(version))) || new Set(versions).size !== versions.length) {
throw new Error('php-versions must be a JSON array of unique numeric PHP versions.');
}
function options(name, input, defaults) {
const value = input.trim();
if (['', 'false', 'null'].includes(value)) return null;
let config;
if (value === 'true') config = {};
else if (value.startsWith('{') || value.startsWith('[')) {
try { config = JSON.parse(value); } catch { throw new Error(name + ' must contain valid JSON.'); }
} else config = {command: value};
if (!config || typeof config !== 'object' || Array.isArray(config)) throw new Error(name + ' must be a script name or a JSON object.');
const unknown = Object.keys(config).filter(key => !Object.hasOwn(defaults, key));
if (unknown.length) throw new Error('Unknown ' + name + ' options: ' + unknown.join(', ') + '.');
config = {...defaults, ...config};
for (const [key, option] of Object.entries(config)) {
if (typeof option !== 'string') throw new Error(name + '.' + key + ' must be a string.');
}
if (!config.command.trim() || config.command.startsWith('-') || /\s/.test(config.command)) throw new Error(name + '.command must name a Composer script.');
return config;
}
const lint = options('lint', process.env.LINT, {command: 'lint:ci'});
const test = options('test', process.env.TEST, {command: 'test:ci', coverage: 'github', cache: ''});
if (test && !['', 'github', 'codecov'].includes(test.coverage)) throw new Error('test.coverage must be github, codecov or empty.');
const cache = test?.cache;
if (cache && (cache === '.' || cache.startsWith('/') || cache.includes('\\') || cache.split('/').includes('..') || /[\r\n*?]/.test(cache))) {
throw new Error('test.cache must be one directory inside working-directory.');
}
core.setOutput('lint', JSON.stringify(lint));
core.setOutput('test', JSON.stringify(test));
core.setOutput('versions', versions);
core.setOutput('primary-version', versions.at(-1));
dependency-review:
if: inputs.checks && github.event_name == 'pull_request' && inputs.dependency-review
runs-on: ${{ fromJSON(inputs.runs-on) }}
permissions:
contents: read
steps:
- uses: actions/checkout@3d3c42e5aac5ba805825da76410c181273ba90b1
with:
persist-credentials: false
- uses: actions/dependency-review-action@a1d282b36b6f3519aa1f3fc636f609c47dddb294
lint:
if: inputs.checks && needs.configuration.outputs.lint != 'null'
needs: configuration
runs-on: ${{ fromJSON(inputs.runs-on) }}
permissions:
contents: read
steps:
- uses: actions/checkout@3d3c42e5aac5ba805825da76410c181273ba90b1
with:
persist-credentials: false
- uses: $/actions/setup-php
with:
working-directory: ${{ inputs.working-directory }}
php-version: ${{ needs.configuration.outputs.primary-version }}
extensions: ${{ inputs.extensions }}
composer-directories: ${{ inputs.composer-directories }}
ignore-scripts: ${{ inputs.ignore-scripts }}
ignore-plugins: ${{ inputs.ignore-plugins }}
- uses: $/actions/lint
with:
working-directory: ${{ inputs.working-directory }}
command: ${{ fromJSON(needs.configuration.outputs.lint).command }}
test:
if: inputs.checks && needs.configuration.outputs.test != 'null'
needs: configuration
runs-on: ${{ fromJSON(inputs.runs-on) }}
permissions:
contents: read
id-token: write
strategy:
fail-fast: false
matrix:
php-version: ${{ fromJSON(needs.configuration.outputs.versions) }}
steps:
- uses: actions/checkout@3d3c42e5aac5ba805825da76410c181273ba90b1
with:
persist-credentials: false
- uses: $/actions/setup-php
with:
working-directory: ${{ inputs.working-directory }}
php-version: ${{ matrix.php-version }}
extensions: ${{ inputs.extensions }}
composer-directories: ${{ inputs.composer-directories }}
ignore-scripts: ${{ inputs.ignore-scripts }}
ignore-plugins: ${{ inputs.ignore-plugins }}
- if: fromJSON(needs.configuration.outputs.test).cache != ''
uses: actions/cache@55cc8345863c7cc4c66a329aec7e433d2d1c52a9 # v6.1.0
with:
path: ${{ inputs.working-directory }}/${{ fromJSON(needs.configuration.outputs.test).cache }}
key: php-tests-${{ runner.os }}-${{ matrix.php-version }}-${{ inputs.working-directory }}-${{ fromJSON(needs.configuration.outputs.test).cache }}-${{ hashFiles(format('{0}/**/composer.json', inputs.working-directory)) }}
restore-keys: php-tests-${{ runner.os }}-${{ matrix.php-version }}-${{ inputs.working-directory }}-${{ fromJSON(needs.configuration.outputs.test).cache }}-
- uses: $/actions/test
with:
working-directory: ${{ inputs.working-directory }}
command: ${{ fromJSON(needs.configuration.outputs.test).command }}
coverage: ${{ matrix.php-version == needs.configuration.outputs.primary-version && fromJSON(needs.configuration.outputs.test).coverage || '' }}
package:
if: inputs.checks && needs.configuration.outputs.package-enabled == 'true'
needs: configuration
runs-on: ${{ fromJSON(inputs.runs-on) }}
permissions:
contents: read
steps:
- uses: actions/checkout@3d3c42e5aac5ba805825da76410c181273ba90b1
with:
persist-credentials: false
- uses: $/actions/setup-php
with:
working-directory: ${{ inputs.working-directory }}
php-version: ${{ needs.configuration.outputs.primary-version }}
extensions: ${{ inputs.extensions }}
ignore-scripts: ${{ inputs.ignore-scripts }}
install-dependencies: "false"
coverage: none
- uses: $/actions/package/test
with:
working-directory: ${{ inputs.working-directory }}
commands: ${{ needs.configuration.outputs.package-tests }}