From 512bf7ed31fa27345132eecfc5eb9a7aa5d03909 Mon Sep 17 00:00:00 2001
From: John Blackbourn <john@johnblackbourn.com>
Date: Sun, 3 May 2026 12:37:51 +0100
Subject: [PATCH 1/5] Introduce the GitHub Actions Workflow Standards page.

---
 index.md                                     |   1 +
 manifest.json                                |   6 +
 wordpress-coding-standards.md                |   1 +
 wordpress-coding-standards/github-actions.md | 185 +++++++++++++++++++
 4 files changed, 193 insertions(+)
 create mode 100644 wordpress-coding-standards/github-actions.md

diff --git a/index.md b/index.md
index d7c7e94..46c704d 100644
--- a/index.md
+++ b/index.md
@@ -6,6 +6,7 @@ WordPress is a big project with thousands of contributors. It's important that b
 <ul>
 	<li><a href="https://developer.wordpress.org/coding-standards/wordpress-coding-standards/accessibility/">Accessibility Coding Standards</a></li>
 	<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>
 	<li><a href="https://developer.wordpress.org/coding-standards/wordpress-coding-standards/html/">HTML Coding Standards</a></li>
 	<li><a href="https://developer.wordpress.org/coding-standards/wordpress-coding-standards/javascript/">JavaScript Coding Standards</a></li>
 	<li><a href="https://developer.wordpress.org/coding-standards/wordpress-coding-standards/php/">PHP Coding Standards</a></li>
diff --git a/manifest.json b/manifest.json
index 0fe8c6d..8f5f677 100644
--- a/manifest.json
+++ b/manifest.json
@@ -24,6 +24,12 @@
 		"parent": "wordpress-coding-standards",
 		"markdown_source": "https://github.com/WordPress/wpcs-docs/blob/master/wordpress-coding-standards/css.md"
 	},
+	"wordpress-coding-standards/github-actions": {
+		"title": "GitHub Actions Workflow Standards",
+		"slug": "github-actions",
+		"parent": "wordpress-coding-standards",
+		"markdown_source": "https://github.com/WordPress/wpcs-docs/blob/master/wordpress-coding-standards/github-actions.md"
+	},
 	"wordpress-coding-standards/html": {
 		"title": "HTML Coding Standards",
 		"slug": "html",
diff --git a/wordpress-coding-standards.md b/wordpress-coding-standards.md
index 1c3f581..93c1302 100644
--- a/wordpress-coding-standards.md
+++ b/wordpress-coding-standards.md
@@ -13,6 +13,7 @@ If you are planning to contribute to WordPress core, you need to familiarize you
 <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>
 		<li><a href="https://developer.wordpress.org/coding-standards/wordpress-coding-standards/html/">HTML Coding Standards</a></li>
 		<li><a href="https://developer.wordpress.org/coding-standards/wordpress-coding-standards/javascript/">JavaScript Coding Standards</a></li>
 		<li><a href="https://developer.wordpress.org/coding-standards/wordpress-coding-standards/php/">PHP Coding Standards</a></li>
diff --git a/wordpress-coding-standards/github-actions.md b/wordpress-coding-standards/github-actions.md
new file mode 100644
index 0000000..43e903c
--- /dev/null
+++ b/wordpress-coding-standards/github-actions.md
@@ -0,0 +1,185 @@
+# GitHub Actions Workflow Standards
+
+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.
+
+## Actionlint
+
+Actionlint is a static checker for workflow files. It focuses primarily on correctness: syntax validation, type checking for expressions, validation of inputs for actions and reusable workflows, syntax checking of shell scripts, and other common mistakes. See the [Actionlint documentation](https://github.com/rhysd/actionlint) for details.
+
+Actionlint runs on pull requests and on pushes to the main branches on [the wordpress-develop repo](https://github.com/WordPress/wordpress-develop). It reports its findings as check results, just like the unit test and coding standards workflows. A failing Actionlint check must be fixed before the changes in the PR can be committed.
+
+## Zizmor
+
+Zizmor is a security-focused linter for workflow files. It detects template injection vulnerabilities, excessive permissions, dangerous triggers, unpinned dependencies, credential persistence, and dozens of other security weaknesses. See the [Zizmor documentation](https://docs.zizmor.sh/audits/) for details.
+
+Zizmor also runs on pull requests and on pushes to the main branches on [the wordpress-develop repo](https://github.com/WordPress/wordpress-develop) and reports its findings to [GitHub Code Scanning](https://docs.github.com/en/code-security/code-scanning/introduction-to-code-scanning/about-code-scanning). This means:
+
+- Results are available on the Security → Code Scanning tab of the repo for users with administrative permission on the repo.
+- Errors and warnings that are newly introduced in a pull request will cause the code scanning check to fail. A "Code scanning results" status check will report failures, with inline annotations on the affected file and line.
+- Existing issues act as a baseline and won't affect new pull requests until they are fixed or dismissed.
+
+## Running locally
+
+If you're making changes to workflow files in the `.github/workflows` directory, you can run both linting tools locally before pushing. Actionlint and Zizmor are both available via package managers for all operating systems, as well as via Docker images.
+
+- [Actionlint installation instructions](https://github.com/rhysd/actionlint/blob/main/docs/install.md)
+- [Zizmor installation instructions](https://docs.zizmor.sh/installation/)
+
+### Running Actionlint
+
+From the root of the repository, run:
+
+```
+actionlint
+```
+
+### Running Zizmor
+
+From the root of the repository, run (note the trailing period):
+
+```
+zizmor .
+```
+
+To enable the online audits that check for known-vulnerable actions and impostor commits, provide a GitHub token:
+
+```
+GH_TOKEN=$(gh auth token) zizmor .
+```
+
+Some findings that are reported locally may be suppressed in the repository's Code Scanning settings. If you encounter a locally reported finding that does not appear in Code Scanning results, check whether it has been dismissed.
+
+## Addressing common security issues
+
+The following sections cover common findings and how to address them.
+
+For full information about specific results from the linting tools, consult [the Actionlint documentation](https://github.com/rhysd/actionlint/blob/main/docs/checks.md) and [the Zizmor documentation](https://docs.zizmor.sh/audits/).
+
+### Template injection
+
+Template injection occurs when a GitHub Actions expression such as `${{ github.event.issue.title }}` is used directly within a `run:` block. GitHub Actions expressions are interpreted _prior_ to running the script, therefore an attacker who controls the expression value can inject arbitrary shell commands, regardless of whether the expression is wrapped in quotes.
+
+**Incorrect:**
+
+```yaml
+- name: Print title
+  run: echo "Title: ${{ github.event.pull_request.title }}"
+```
+
+**Correct:**
+
+```yaml
+- name: Print title
+  run: echo "Title: ${PR_TITLE}"
+  env:
+    PR_TITLE: ${{ github.event.pull_request.title }}
+```
+
+When the value is passed through an environment variable, it is treated as data rather than code, preventing injection.
+
+For `actions/github-script` steps, pass values through the `env` block and access them via `process.env` instead of using template expressions in the script body:
+
+**Incorrect:**
+
+```yaml
+- uses: actions/github-script@...
+  with:
+    script: |
+      const title = "${{ github.event.pull_request.title }}";
+```
+
+**Correct:**
+
+```yaml
+- uses: actions/github-script@...
+  env:
+    PR_TITLE: ${{ github.event.pull_request.title }}
+  with:
+    script: |
+      const title = process.env.PR_TITLE;
+```
+
+### Dangerous triggers
+
+The `pull_request_target` and `workflow_run` triggers run in the context of the base repository and have access to repository secrets. If a workflow triggered by `pull_request_target` checks out the pull request's head ref and runs code from it, an attacker can execute arbitrary code with access to secrets.
+
+- Avoid `pull_request_target` or `workflow_run` unless your workflow genuinely needs access to repository secrets to operate on a pull request (for example, to comment on the PR or manage labels).
+- Never check out the pull request's head ref (`github.event.pull_request.head.ref`) in a `pull_request_target` workflow and then run code from that checkout.
+- If `pull_request_target` or `workflow_run` is necessary, document the justification inline with a comment explaining why the trigger is safe in context.
+
+### Excessive permissions
+
+Workflow and job permissions should follow the principle of least privilege. Every workflow file should include a top-level `permissions: {}` block that grants no permissions, with individual jobs declaring only the specific permissions they need. Omitting a `permissions` declaration entirely is not sufficient.
+
+**Incorrect:**
+
+```yaml
+permissions:
+  contents: write
+
+jobs:
+  lint:
+    # This job only reads code, it doesn't need write access.
+    runs-on: ubuntu-latest
+```
+
+**Correct:**
+
+```yaml
+permissions: {}
+
+jobs:
+  lint:
+    runs-on: ubuntu-latest
+    permissions:
+      contents: read
+```
+
+### Artipacked credentials
+
+The `actions/checkout` action persists credentials by default so that subsequent git operations can authenticate. If the checkout directory is later uploaded as an artifact (or its contents are otherwise exposed), the persisted credentials can be leaked.
+
+Always set `persist-credentials: false` on `actions/checkout` unless subsequent steps in the same job genuinely need to perform authenticated git operations (such as pushing commits).
+
+**Correct:**
+
+```yaml
+- uses: actions/checkout@...
+  with:
+    persist-credentials: false
+```
+
+If the job needs persistent credentials (for example, to push built files), set `persist-credentials: true` explicitly so the intent is clear and auditable, and include an accompanying comment.
+
+### GitHub environment manipulation
+
+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.
+- If you must process user-controllable input, validate and sanitize it before writing to these files.
+
+### Unpinned uses
+
+All third-party actions must be pinned to a full commit SHA, not a tag, branch, or floating version reference such as `v6`. Tags can be moved or deleted as well as added, meaning a tagged reference could silently point to different (potentially malicious) code in the future.
+
+**Incorrect:**
+
+```yaml
+- uses: actions/checkout@v6
+```
+
+**Correct:**
+
+```yaml
+- 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.
+
+### Cache poisoning
+
+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.

From 9a907eb3695b7228cda662403cdc85bf918999fc Mon Sep 17 00:00:00 2001
From: John Blackbourn <john@johnblackbourn.com>
Date: Wed, 6 May 2026 13:10:29 +0100
Subject: [PATCH 2/5] Add a link to `gh`.

---
 wordpress-coding-standards/github-actions.md | 2 +-
 1 file changed, 1 insertion(+), 1 deletion(-)

diff --git a/wordpress-coding-standards/github-actions.md b/wordpress-coding-standards/github-actions.md
index 43e903c..70b305f 100644
--- a/wordpress-coding-standards/github-actions.md
+++ b/wordpress-coding-standards/github-actions.md
@@ -43,7 +43,7 @@ From the root of the repository, run (note the trailing period):
 zizmor .
 ```
 
-To enable the online audits that check for known-vulnerable actions and impostor commits, provide a GitHub token:
+To enable the online audits that check for known-vulnerable actions and impostor commits, you can use [the `gh` CLI tool from GitHub](https://cli.github.com/) to provide an auth token:
 
 ```
 GH_TOKEN=$(gh auth token) zizmor .

From a8c0058fc9c5eb763159d8a3935a36f4af31ec1e Mon Sep 17 00:00:00 2001
From: John Blackbourn <john@johnblackbourn.com>
Date: Tue, 19 May 2026 16:01:51 +0200
Subject: [PATCH 3/5] Updates based on feedback from Jonathan.

---
 wordpress-coding-standards/github-actions.md | 12 +++++++-----
 1 file changed, 7 insertions(+), 5 deletions(-)

diff --git a/wordpress-coding-standards/github-actions.md b/wordpress-coding-standards/github-actions.md
index 70b305f..184ebc7 100644
--- a/wordpress-coding-standards/github-actions.md
+++ b/wordpress-coding-standards/github-actions.md
@@ -72,9 +72,9 @@ Template injection occurs when a GitHub Actions expression such as `${{ github.e
 
 ```yaml
 - name: Print title
-  run: echo "Title: ${PR_TITLE}"
   env:
     PR_TITLE: ${{ github.event.pull_request.title }}
+  run: echo "Title: ${PR_TITLE}"
 ```
 
 When the value is passed through an environment variable, it is treated as data rather than code, preventing injection.
@@ -84,7 +84,8 @@ For `actions/github-script` steps, pass values through the `env` block and acces
 **Incorrect:**
 
 ```yaml
-- uses: actions/github-script@...
+- name: Print title
+  uses: actions/github-script@...
   with:
     script: |
       const title = "${{ github.event.pull_request.title }}";
@@ -93,9 +94,10 @@ For `actions/github-script` steps, pass values through the `env` block and acces
 **Correct:**
 
 ```yaml
-- uses: actions/github-script@...
+- name: Print title
   env:
     PR_TITLE: ${{ github.event.pull_request.title }}
+  uses: actions/github-script@...
   with:
     script: |
       const title = process.env.PR_TITLE;
@@ -176,10 +178,10 @@ All third-party actions must be pinned to a full commit SHA, not a tag, branch,
 - 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.
+Always include a comment after the SHA that includes the exact name of the pinned tag, for example `v6.0.`. A floating value such as `v6` is not sufficient. When updating an action, update both the SHA and the version comment.
 
 ### Cache poisoning
 
 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.
+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, do not use partial cache key matching patterns, and verify the cache contents before use.

From c12951c4c79197d066601be39d2c45cc1f866308 Mon Sep 17 00:00:00 2001
From: John Blackbourn <john@johnblackbourn.com>
Date: Tue, 19 May 2026 16:12:28 +0200
Subject: [PATCH 4/5] Clarify the `GITHUB_ENV`, `GITHUB_PATH`, and
 `GITHUB_OUTPUT` risks following feedback from Rodrigo.

---
 wordpress-coding-standards/github-actions.md | 3 ++-
 1 file changed, 2 insertions(+), 1 deletion(-)

diff --git a/wordpress-coding-standards/github-actions.md b/wordpress-coding-standards/github-actions.md
index 184ebc7..5a1e66c 100644
--- a/wordpress-coding-standards/github-actions.md
+++ b/wordpress-coding-standards/github-actions.md
@@ -159,7 +159,8 @@ If the job needs persistent credentials (for example, to push built files), set
 
 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.
+- To pass state between steps, prefer writing to `$GITHUB_OUTPUT` instead. Unlike `$GITHUB_ENV` and `$GITHUB_PATH`, outputs are not injected into the environment or `PATH` of subsequent steps.
+- If you must write to `$GITHUB_ENV` or `$GITHUB_PATH`, only write 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.
 - If you must process user-controllable input, validate and sanitize it before writing to these files.
 
 ### Unpinned uses

From a88a6eaee40daeb10597d81a48590800329ff387 Mon Sep 17 00:00:00 2001
From: John Blackbourn <john@johnblackbourn.com>
Date: Tue, 19 May 2026 16:50:24 +0200
Subject: [PATCH 5/5] Updates based on feedback from Gary.

---
 wordpress-coding-standards.md                |  7 ++++++-
 wordpress-coding-standards/github-actions.md | 10 +++++++---
 2 files changed, 13 insertions(+), 4 deletions(-)

diff --git a/wordpress-coding-standards.md b/wordpress-coding-standards.md
index 93c1302..dc8c32c 100644
--- a/wordpress-coding-standards.md
+++ b/wordpress-coding-standards.md
@@ -13,7 +13,6 @@ If you are planning to contribute to WordPress core, you need to familiarize you
 <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>
 		<li><a href="https://developer.wordpress.org/coding-standards/wordpress-coding-standards/html/">HTML Coding Standards</a></li>
 		<li><a href="https://developer.wordpress.org/coding-standards/wordpress-coding-standards/javascript/">JavaScript Coding Standards</a></li>
 		<li><a href="https://developer.wordpress.org/coding-standards/wordpress-coding-standards/php/">PHP Coding Standards</a></li>
@@ -26,3 +25,9 @@ WordPress is committed to meeting the <a href="https://www.w3.org/TR/WCAG20/">We
 <h2>Where do the coding standards _not_ apply?</h2>
 
 Third-party libraries are not subject to these standards, even when integrated with the primary project. This includes instances like WordPress core, where multiple third-party libraries are incorporated into its codebase.
+
+<h2>GitHub Actions Workflow Standards</h2>
+
+GitHub Actions workflows operate in a highly privileged software supply chain environment.
+
+All repos under the WordPress organisation on GitHub are expected to adhere to <a href="https://developer.wordpress.org/coding-standards/wordpress-coding-standards/github-actions/">the GitHub Actions Workflow Standards</a>.
diff --git a/wordpress-coding-standards/github-actions.md b/wordpress-coding-standards/github-actions.md
index 5a1e66c..3a20114 100644
--- a/wordpress-coding-standards/github-actions.md
+++ b/wordpress-coding-standards/github-actions.md
@@ -139,7 +139,7 @@ jobs:
       contents: read
 ```
 
-### Artipacked credentials
+### Git credential persistence
 
 The `actions/checkout` action persists credentials by default so that subsequent git operations can authenticate. If the checkout directory is later uploaded as an artifact (or its contents are otherwise exposed), the persisted credentials can be leaked.
 
@@ -155,6 +155,8 @@ Always set `persist-credentials: false` on `actions/checkout` unless subsequent
 
 If the job needs persistent credentials (for example, to push built files), set `persist-credentials: true` explicitly so the intent is clear and auditable, and include an accompanying comment.
 
+This credential persistence risk is often referred to as "artipacked", and Zizmor uses this name for its corresponding audit.
+
 ### GitHub environment manipulation
 
 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`.
@@ -183,6 +185,8 @@ Always include a comment after the SHA that includes the exact name of the pinne
 
 ### Cache poisoning
 
-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.
+Using GitHub Actions caching in workflows that produce release artifacts is risky. It's possible for a cache to be poisoned by an attacker in a separate workflow, allowing the poisoned cache to inject malicious content into a release.
+
+An attacker with access to a valid `GITHUB_TOKEN` can poison the repository's GitHub Actions caches. Combined with the default behaviour of `actions/cache` during cache restoration, an attacker's payload can be retrieved from the poisoned entry and executed at workflow runtime, potentially compromising the package or release artifact that's about to be published.
 
-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, do not use partial cache key matching patterns, and verify the cache contents before use.
+Do not use `actions/cache` or the built-in caching features of other actions in workflows that build or publish packages or release artifacts.