Add recommendation for specifying Github Actions versions

.alexrc.js

@@ -1,5 +1,6 @@
 exports.profanitySureness = 1;
 exports.allow = [
-    "steward-stewardess", //Exclude this rule as we get false positives from references to Scala Steward
-    "special"
+  "steward-stewardess", //Exclude this rule as we get false positives from references to Scala Steward
+  "special",
+  "actor-actress", // Used in Security, as in "threat actor"
 ];

README.md

@@ -86,6 +86,7 @@ This repository document [principles](#principles), standards and [guidelines](#
 -   [Elasticsearch](elasticsearch.md)
 -   [Emotion](emotion.md)
 -   [GitHub](github.md)
+-   [Github Actions](github-actions.md)
 -   [Logging](logging.md)
 -   [NPM packages](npm-packages.md)
 -   [Production Services, Ownership and Maintenance](ownership.md)

continuous-integration.md

@@ -1,5 +1,6 @@
 [Scripts To Rule Them All pattern]: https://github.com/github/scripts-to-rule-them-all
 [GitHub Actions]: https://docs.github.com/en/actions
+[Github Actions recommendations]: github-actions.md
 [RiffRaff]: https://github.com/guardian/riff-raff
 [`actions-riff-raff`]:https://github.com/guardian/actions-riff-raff/
 [`aws-actions/configure-aws-credentials`]: https://github.com/aws-actions/configure-aws-credentials
@@ -31,7 +32,7 @@ Every minute you reduce your building time is a minute saved when you will need
 
 ## Platforms
 
-* Use GitHub Actions (with [`aws-actions/configure-aws-credentials`]) to run continuous integration tasks
+* Use GitHub Actions (with [`aws-actions/configure-aws-credentials`]) to run continuous integration tasks. See also [Github Actions recommendations].
 * Where possible, have CI execute a single, centralised script in the repository named `script/ci` 
     - This adheres to GitHub's [Scripts To Rule Them All pattern]
 

github-actions.md

@@ -0,0 +1,36 @@
+# GitHub Actions
+
+Github actions should be used for Continuous Integration. Actions are typically used to enforce checks before merging branches into main (such as formatting, linting and testing), as well as to publish libraries or [deploy](continuous-deployment.md) build artifacts (via Riff-Raff).
+
+## Specifying versions for actions you use
+
+Github Actions workflows can invoke other actions via `uses` steps. When specifying the version to use, one can typically:
+
+- Reference via a Git tag e.g `uses: actions/checkout@v4`. These correspond to tagged releases on Github - see [actions/checkout/releases](https://github.com/actions/checkout/releases) for examples.
+- Reference via a Git Commit SHA e.g. `uses: actions/checkout@b4ffde65f46336ab88eb53be808477a3936bae11 # v4.1.1`.
+
+**We recommend specifying the version of Github Actions workflows as a commit SHA**.
+
+Since commit SHAs are immutable, the code of the underlying workflow cannot be changed for any given commit. This mitigates a security issue that arises from using tags (assuming you’re comfortable with the code present for the given SHA), where code executed by the underlying action can be changed without creating a new release. A malicious actor could exploit this in order to run code within our own workflows. See this [blog post](https://blog.rafaelgss.dev/why-you-should-pin-actions-by-commit-hash) for a complete example.
+
+It’s important to check the source code of the action for the given commit, so you’re reasonably satisfied the action is behaving as expected (and not exfiltrating secrets, for example).
+
+As well as specifying the commit, it’s worth combining this with a comment specifying a more readable semver version, in the format `# v0.0.1`. Dependabot also knows how to handle updates for workflows versioned with SHAs, with a comment that is kept updated with the version tag that the commit points to: see [nodejs/node/pull/51334](https://github.com/nodejs/node/pull/51334) for an example.
+
+Note that this differs from the [Github recommendations](https://docs.github.com/en/actions/security-guides/security-hardening-for-github-actions#using-third-party-actions), as we're applying the principle of zero trust to all Github Actions.
+
+### Finding the SHA for a given release
+
+You can find the SHA for a particular release by navigating to the Releases page of a GitHub repository, and clicking the short SHA digest in the panel to the left of the release. The full SHA can then be copied out of the URL.
+
+![image](finding-gha-release-sha.png)
+
+Alternatively, they can be obtained via the command line. For example:
+
+```bash
+git ls-remote --tags https://github.com/actions/checkout | sort -Vr -k2
+```
+
+## Keep actions up to date with Dependabot
+
+Use Dependabot to keep all actions up to date. See [Keeping your actions up to date with Dependabot](https://docs.github.com/en/code-security/dependabot/working-with-dependabot/keeping-your-actions-up-to-date-with-dependabot).

ownership.md

@@ -12,7 +12,7 @@ N.B. This guidance only intended as a minimum baseline; in practice the expectat
 - All source code should be version controlled using [GitHub](./github.md)
 - CI/CD should be employed
     - An appropriate testing strategy should be considered. We do not aim for a specific % of test coverage, but important business logic should be unit tested
-    - For CI, use GitHub Actions
+    - For CI, use [GitHub Actions](./github-actions.md)
     - For most (non-library) projects, deployment will be done via [Riff-Raff](https://riffraff.gutools.co.uk/)
 
 ### Security