Introduce the GitHub Actions Workflow Standards page by johnbillion · Pull Request #159 · WordPress/wpcs-docs

johnbillion · 2026-05-03T11:54:41Z

Work has been ongoing recently to improve the quality and security of GitHub Actions workflow files in the wordpress-develop and gutenberg repos. Examples:

While the Actionlint and Zizmor tools that we now use are great for surfacing problems in workflow files, we also need good user-facing documentation that provides guidance on addressing common issues and what automation is in place.

Members of the security team have been working on this page and it's already live at https://developer.wordpress.org/coding-standards/wordpress-coding-standards/github-actions/. It now needs to be moved into the docs repo alongside the other pages.

dingo-d

I had just one comment, otherwise looks good 👍🏼

jrfnl · 2026-05-05T10:44:38Z

@johnbillion You seem to be mixing two different tasks in this single PR:

Adding a new page
Improving the security of the GH Actions workflow(s) for this repo.

As those are different decision points, with different justifications, could you please move the workflow changes to their own PR ?

johnbillion · 2026-05-06T12:25:31Z

could you please move the workflow changes to their own PR ?

Done: #161

desrosj

@johnbillion some small suggestions. Some may be a bit deeper than you're looking to go in this high-level guide, and some are stylistic preferences.

desrosj · 2026-05-06T20:43:25Z

+
+```yaml
+- name: Print title
+  run: echo "Title: ${PR_TITLE}"


Small nit and admittedly a personal preference, but I prefer that run: comes last in the step definition because it ensures the reader notices all conditions, variables, environments, etc. before reading the actual command that is run.

desrosj · 2026-05-06T20:44:43Z

+**Correct:**
+
+```yaml
+- uses: actions/github-script@...


Same preference comment here about the uses: being last. However, I feel more strongly that any inputs passed should be immediately after the uses: line.

desrosj · 2026-05-06T20:47:57Z

+
+Writing to `$GITHUB_ENV` or `$GITHUB_PATH` from a shell script is dangerous if the input is user-controlled, because an attacker can inject arbitrary environment variables or prepend to `PATH`.
+
+- Only write to `$GITHUB_ENV` or `$GITHUB_OUTPUT` with values that are fully controlled by the workflow, not with values derived from pull request content, issue bodies, commit messages, or other user-controllable inputs.


Should we include an example about how to do this properly by wrapping $GITHUB_OUTPUT in double quotes?

desrosj · 2026-05-06T20:49:07Z

+- uses: actions/checkout@de0fac2e4500dabe0009e67214ff5f5447ce83dd # v6.0.2
+```
+
+Always include a version comment after the SHA to make the pinned version human-readable. When updating an action, update both the SHA and the version comment.


May be worth noting that the version specified within the online comment must match the actual version tag published by the action's repository.

desrosj · 2026-05-06T20:52:00Z

+
+Using GitHub Actions caching in workflows that produce release artifacts is risky. A cache can be poisoned by an attacker in a separate workflow, allowing the poisoned cache to inject malicious content into a release.
+
+Avoid using `actions/cache` or built-in caching features in workflows that build and publish packages or release artifacts. If caching is necessary in such workflows, ensure the cache key is scoped tightly and the cache contents are verified before use.


Cache poisoning can also occur when a workflow specifies restore-keys. We should explicitly discourage the use of partial cache key matching patterns in favor of explicit hash-based keys where the hash was produced using the relevant lock files.

rodrigoprimo

Looks good to me overall. I left a couple of inline comments with questions about small things that caught my attention.

rodrigoprimo · 2026-05-07T14:00:34Z

+
+Writing to `$GITHUB_ENV` or `$GITHUB_PATH` from a shell script is dangerous if the input is user-controlled, because an attacker can inject arbitrary environment variables or prepend to `PATH`.
+
+- Only write to `$GITHUB_ENV` or `$GITHUB_OUTPUT` with values that are fully controlled by the workflow, not with values derived from pull request content, issue bodies, commit messages, or other user-controllable inputs.


The paragraph above flags writing to $GITHUB_ENV or $GITHUB_PATH, but this line mentions writing to $GITHUB_ENV or $GITHUB_OUTPUT. Should it say $GITHUB_PATH instead of $GITHUB_OUTPUT? I might be missing something, as I'm not super familiar with how GitHub Actions uses those environment variables.

rodrigoprimo · 2026-05-07T14:22:07Z

+
+**Incorrect:**
+
+```yaml


The YAML code blocks on the published page are not syntax-highlighted. They render as <code class=""> rather than <code class="language-yaml"> like the PHP and CSS blocks do on other pages. Do you know if ```yaml fences work with the importer? I don't know whether the published page was generated from a version of this Markdown file.

GaryJones

Also, the PR body still says "This PR also fixes some issues in the qa.yml workflow file in this repo so it adheres to these standards.", even though that was moved out.

GaryJones · 2026-05-12T10:26:04Z

 <h2>Language-specific Standards</h2>
 <ul>
 		<li><a href="https://developer.wordpress.org/coding-standards/wordpress-coding-standards/css/">CSS Coding Standards</a></li>
+		<li><a href="https://developer.wordpress.org/coding-standards/wordpress-coding-standards/github-actions/">GitHub Actions Workflow Standards</a></li>


It’s slotted under “Language-specific Standards” alongside CSS/HTML/JS/PHP. GitHub Actions isn’t a language; it’s YAML config for a CI platform. This will read oddly to anyone scanning the index, and it implies a parity (“this is a WordPress coding standard”) that the content doesn’t quite live up to. A separate “Infrastructure / Tooling Standards” grouping would be more honest, and would leave room for similar future docs (Composer, npm, Docker).

GaryJones · 2026-05-12T10:27:34Z

+
+GitHub Actions workflows operate in a highly privileged software supply chain environment. Workflows can access repository secrets, push code, create releases, publish packages, and interact with external services. A security weakness in a workflow file can have severe consequences.
+
+WordPress uses two complementary linting tools to help maintain the quality and security of workflow files in the `.github/workflows` directory: [Actionlint](https://github.com/rhysd/actionlint) and [Zizmor](https://github.com/zizmorcore/zizmor). This page documents the tools and how contributors should address errors or warnings that they report.


The scope is undefined. The doc says “WordPress uses…” then only names wordpress-develop as an enforcement point. Does this apply to Gutenberg? Plugin/theme contributors? The wpcs-docs repo itself? The PR body hints at all of them, but the page should state its scope explicitly — otherwise it’s a guideline dressed as a standard.

The end goal is to add enforcement of these practices org-wide to ensure all repositories remain secure. But that will take time.

That said, we could maybe add a section linking to the repositories enforcing this to date. Gutenberg runs a workflow, but I don't believe it is configured as a check that is required to pass currently. I could be wrong on that and would need to check.

GaryJones · 2026-05-12T10:29:28Z

@@ -0,0 +1,185 @@
+# GitHub Actions Workflow Standards


There's a title vs content imbalance here. It's called “GitHub Actions Workflow Standards”, but the substance is almost entirely Zizmor audit findings rephrased. Actionlint gets one paragraph and zero concrete examples. Either rename it to something like “Workflow Security Standards”, or beef up the Actionlint side (common findings, shellcheck guidance, expression typing pitfalls).

For a document presented as the standard, I’d expect at least a mention of:

timeout-minutes (DoS / runaway jobs)

Concurrency controls (concurrency: block)

GITHUB_TOKEN scoping vs PATs

etc.

GaryJones · 2026-05-12T10:31:17Z

+      contents: read
+```
+
+### Artipacked credentials


This is a Zizmor audit name. For readers who’ve never used Zizmor, it’s jargon. “Persistent checkout credentials (Zizmor: artipacked)” reads more naturally.

GaryJones · 2026-05-12T10:32:44Z

+
+Using GitHub Actions caching in workflows that produce release artifacts is risky. A cache can be poisoned by an attacker in a separate workflow, allowing the poisoned cache to inject malicious content into a release.
+
+Avoid using `actions/cache` or built-in caching features in workflows that build and publish packages or release artifacts. If caching is necessary in such workflows, ensure the cache key is scoped tightly and the cache contents are verified before use.


“Scope the cache key tightly and verify the cache contents before use” — how? A concrete example or a hard rule (“don’t cache in release workflows, full stop”) would be more useful than the current half-advice.

Introduce the GitHub Actions Workflow Standards page.

512bf7e

johnbillion requested review from dingo-d and rodrigoprimo May 3, 2026 11:54

dingo-d reviewed May 5, 2026

View reviewed changes

Comment thread wordpress-coding-standards/github-actions.md Outdated

dingo-d approved these changes May 5, 2026

View reviewed changes

johnbillion moved this to In progress in WordPress Project Build Tooling May 6, 2026

johnbillion added this to WordPress Project Build Tooling May 6, 2026

Add a link to gh.

9a907eb

johnbillion force-pushed the github-actions-standards branch from ab12d32 to 9a907eb Compare May 6, 2026 12:10

johnbillion mentioned this pull request May 6, 2026

Harden the GitHub Actions workflow #161

Open

johnbillion moved this from In progress to In review in WordPress Project Build Tooling May 6, 2026

desrosj reviewed May 6, 2026

View reviewed changes

rodrigoprimo reviewed May 7, 2026

View reviewed changes

GaryJones requested changes May 12, 2026

View reviewed changes


		Writing to `$GITHUB_ENV` or `$GITHUB_PATH` from a shell script is dangerous if the input is user-controlled, because an attacker can inject arbitrary environment variables or prepend to `PATH`.

		- Only write to `$GITHUB_ENV` or `$GITHUB_OUTPUT` with values that are fully controlled by the workflow, not with values derived from pull request content, issue bodies, commit messages, or other user-controllable inputs.


		Using GitHub Actions caching in workflows that produce release artifacts is risky. A cache can be poisoned by an attacker in a separate workflow, allowing the poisoned cache to inject malicious content into a release.

		Avoid using `actions/cache` or built-in caching features in workflows that build and publish packages or release artifacts. If caching is necessary in such workflows, ensure the cache key is scoped tightly and the cache contents are verified before use.


		GitHub Actions workflows operate in a highly privileged software supply chain environment. Workflows can access repository secrets, push code, create releases, publish packages, and interact with external services. A security weakness in a workflow file can have severe consequences.

		WordPress uses two complementary linting tools to help maintain the quality and security of workflow files in the `.github/workflows` directory: [Actionlint](https://github.com/rhysd/actionlint) and [Zizmor](https://github.com/zizmorcore/zizmor). This page documents the tools and how contributors should address errors or warnings that they report.


		Incorrect:

		```yaml

Conversation

johnbillion commented May 3, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Uh oh!

dingo-d left a comment

Choose a reason for hiding this comment

Uh oh!

Uh oh!

jrfnl commented May 5, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Uh oh!

johnbillion commented May 6, 2026

Uh oh!

desrosj left a comment

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

rodrigoprimo left a comment

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

GaryJones left a comment

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

6 participants

johnbillion commented May 3, 2026 •

edited

Loading

jrfnl commented May 5, 2026 •

edited

Loading