Skip to content

Commit 93bd114

Browse files
justlevinejustlevine
committed
docs: add workflow readme
1 parent e76bb15 commit 93bd114

File tree

1 file changed

+179
-0
lines changed

1 file changed

+179
-0
lines changed

‎.github/workflows/README.md‎

Lines changed: 179 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,179 @@
1+
# GitHub Workflows
2+
3+
This directory contains GitHub Actions workflows for WordPress plugin development. Some are **reusable** workflows designed to be consumed by other repositories using `axewp/plugin-infra`; others are **internal** workflows for this repository's own CI/CD.
4+
5+
## Reusable Workflows
6+
7+
The following reusable workflows are available for consumption by downstream plugins:
8+
9+
| Workflow | Purpose | Inputs |
10+
| ------------------------------------------------------------------------------ | ------------------------------------ | -------------------------------------------------------------------------------------------------- |
11+
| [reusable-phpunit.yml](reusable-phpunit.yml) | Run PHPUnit tests | `php-version`, `wp-version`, `coverage`, `multisite` |
12+
| [reusable-codeception.yml](reusable-codeception.yml) | Run Codeception tests | `php-version`, `wp-version`, `coverage`, `multisite`, `functional`, `acceptance`, `wpunit`, `unit` |
13+
| [reusable-phpstan.yml](reusable-phpstan.yml) | Run PHPStan static analysis | `php-version` |
14+
| [reusable-phpcs.yml](reusable-phpcs.yml) | Run PHPCS coding standards | `php-version` |
15+
| [reusable-e2e.yml](reusable-e2e.yml) | Run Playwright E2E tests | `php-version` |
16+
| [reusable-jest.yml](reusable-jest.yml) | Run Jest unit tests | `coverage` |
17+
| [reusable-lint-js.yml](reusable-lint-js.yml) | Run ESLint, Stylelint, Prettier, TSC | None |
18+
| [reusable-build.yml](reusable-build.yml) | Build plugin artifact | `php-version`, `artifact-name`, `artifact-path` |
19+
| [reusable-wp-playground-pr-preview.yml](reusable-wp-playground-pr-preview.yml) | Post WP Playground preview | `run-id`, `artifact-prefix`, `artifact-filename`, `artifacts-to-keep` |
20+
21+
---
22+
23+
### reusable-phpunit.yml
24+
25+
Runs PHPUnit tests in a Docker environment using `wp-env`.
26+
27+
- **Inputs:**
28+
- `php-version` (string, required): PHP version to use.
29+
- `wp-version` (string, default: `latest`): WordPress version (`latest`, `trunk`, or `X.Y`).
30+
- `coverage` (boolean, default: `false`): Enable code coverage.
31+
- `multisite` (boolean, default: `false`): Run multisite tests.
32+
- **Secrets:**
33+
- `CODECOV_TOKEN` (optional): Token for uploading coverage to Codecov.
34+
35+
**Example Usage:**
36+
37+
```yaml
38+
jobs:
39+
phpunit:
40+
uses: AxeWP/plugin-infra/.github/workflows/reusable-phpunit.yml@main
41+
with:
42+
php-version: '8.3'
43+
wp-version: 'latest'
44+
coverage: true
45+
secrets:
46+
CODECOV_TOKEN: ${{ secrets.CODECOV_TOKEN }}
47+
```
48+
49+
### reusable-codeception.yml
50+
51+
Runs Codeception acceptance, functional, and wpunit tests.
52+
53+
- **Inputs:**
54+
- `php-version` (string, required): PHP version to use.
55+
- `wp-version` (string, default: `latest`): WordPress version.
56+
- `coverage` (boolean, default: `false`): Enable code coverage.
57+
- `multisite` (boolean, default: `false`): Run multisite tests.
58+
- `functional` (boolean, default: `true`): Run functional tests.
59+
- `acceptance` (boolean, default: `true`): Run acceptance tests.
60+
- `wpunit` (boolean, default: `true`): Run WPUnit tests.
61+
- `unit` (boolean, default: `true`): Run unit tests.
62+
- **Secrets:**
63+
- `CODECOV_TOKEN` (optional): Token for uploading coverage to Codecov.
64+
65+
### reusable-phpstan.yml
66+
67+
Runs PHPStan static analysis.
68+
69+
- **Inputs:**
70+
- `php-version` (string, required): PHP version to use.
71+
72+
### reusable-phpcs.yml
73+
74+
Runs PHPCS coding standards check.
75+
76+
- **Inputs:**
77+
- `php-version` (string, required): PHP version to use.
78+
79+
### reusable-e2e.yml
80+
81+
Runs Playwright E2E tests.
82+
83+
- **Inputs:**
84+
- `php-version` (string, required): PHP version to use.
85+
86+
### reusable-jest.yml
87+
88+
Runs Jest unit tests for JavaScript.
89+
90+
- **Inputs:**
91+
- `coverage` (boolean, default: `true`): Enable code coverage.
92+
- **Secrets:**
93+
- `CODECOV_TOKEN` (optional): Token for uploading coverage to Codecov.
94+
95+
### reusable-lint-js.yml
96+
97+
Runs ESLint, Stylelint, Prettier, and TypeScript checks.
98+
99+
- **Inputs:** None.
100+
101+
### reusable-build.yml
102+
103+
Builds the plugin for production and creates a zip artifact.
104+
105+
- **Inputs:**
106+
- `php-version` (string, required): PHP version to use.
107+
- `artifact-name` (string, required): Name of the artifact to upload.
108+
- `artifact-path` (string, required): Path of the artifact to upload.
109+
110+
### reusable-wp-playground-pr-preview.yml
111+
112+
Posts a WordPress Playground preview button to Pull Request descriptions.
113+
114+
- **Inputs:**
115+
- `run-id` (string, required): The workflow run ID to download artifacts from.
116+
- `artifact-prefix` (string, default: `plugin-skeleton-d-pr`): Prefix for the artifact name.
117+
- `artifact-filename` (string, default: `plugin-skeleton-d.zip`): Filename of the zip inside the artifact.
118+
- `artifacts-to-keep` (string, default: `2`): Number of artifacts to keep per PR.
119+
120+
---
121+
122+
## Internal Workflows
123+
124+
The following workflows are used internally by this repository and are not designed for reuse:
125+
126+
| Workflow | Trigger | Purpose |
127+
| -------------------------------------------------- | --------------------------------------------------------- | ------------------------------------------------- |
128+
| [ci.yml](ci.yml) | Push to `main`, PRs to `main`/`release/**` | Lint `composer.json`, check Prettier formatting |
129+
| [release.yml](release.yml) | Push to `main`, `workflow_dispatch` | Automated releases via `release-please` |
130+
| [pr-title.yml](pr-title.yml) | PR events (open, sync, edit, reopen, ready) | Validate PR titles follow Conventional Commits |
131+
| [copilot-setup-steps.yml](copilot-setup-steps.yml) | Push/PR to `copilot-setup-steps.yml`, `workflow_dispatch` | Configure GitHub Copilot coding agent environment |
132+
133+
---
134+
135+
## Secrets
136+
137+
| Secret | Required By | Notes |
138+
| --------------- | ----------------------------------------------------------- | ----------------------------------------------------- |
139+
| `CODECOV_TOKEN` | `reusable-phpunit`, `reusable-jest`, `reusable-codeception` | Optional — coverage uploads fail silently if missing. |
140+
| `GITHUB_TOKEN` | `reusable-wp-playground-pr-preview`, `pr-title.yml` | Automatically provided by GitHub. |
141+
142+
## Usage Example
143+
144+
```yaml
145+
# .github/workflows/ci.yml
146+
147+
name: CI
148+
on: [push, pull_request]
149+
jobs:
150+
lint:
151+
uses: AxeWP/plugin-infra/.github/workflows/reusable-lint-js.yml@main
152+
phpstan:
153+
uses: AxeWP/plugin-infra/.github/workflows/reusable-phpstan.yml@main
154+
with:
155+
php-version: '8.3'
156+
phpunit:
157+
uses: AxeWP/plugin-infra/.github/workflows/reusable-phpunit.yml@main
158+
with:
159+
php-version: '8.3'
160+
secrets:
161+
CODECOV_TOKEN: ${{ secrets.CODECOV_TOKEN }}
162+
```
163+
164+
## Local Testing
165+
166+
You can test these workflows locally using [act](https://github.com/nektos/act).
167+
168+
```bash
169+
# Test a local workflow
170+
act -W .github/workflows/ci.yml
171+
172+
# Test a reusable workflow directly, passing inputs and secrets
173+
act -W .github/workflows/reusable-codeception.yml \
174+
--input php-version=8.3 \
175+
--input wp-version=latest \
176+
--input coverage=true \
177+
--input acceptance=false \
178+
--secret CODECOV_TOKEN=<your-token>
179+
```

0 commit comments

Comments
 (0)