diff --git a/.alexrc.js b/.alexrc.js index f5f5da1..d8dd342 100644 --- a/.alexrc.js +++ b/.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" ]; diff --git a/README.md b/README.md index 023e7d2..2949cee 100644 --- a/README.md +++ b/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) diff --git a/continuous-integration.md b/continuous-integration.md index 49eb63e..d9b1c7a 100644 --- a/continuous-integration.md +++ b/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] diff --git a/finding-gha-release-sha.png b/finding-gha-release-sha.png new file mode 100644 index 0000000..97b391b Binary files /dev/null and b/finding-gha-release-sha.png differ diff --git a/github-actions.md b/github-actions.md new file mode 100644 index 0000000..a95cd68 --- /dev/null +++ b/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). diff --git a/ownership.md b/ownership.md index 095f15c..9d5fd34 100644 --- a/ownership.md +++ b/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