From 06aee15cbacca5908ebaa54514ec13d6ebf69af3 Mon Sep 17 00:00:00 2001 From: Huw Diprose Date: Thu, 8 Feb 2024 12:30:57 +0000 Subject: [PATCH] Expand github action pinning guidance to include update approach SHA pinning is a sensible approach to mitigate potential supply chain attacks. See some great blog posts here on the approach: https://blog.rafaelgss.dev/why-you-should-pin-actions-by-commit-hash also https://michaelheap.com/improve-your-github-actions-security/#using-pin-github-action However one down side is that SHA's are not very human readable. It can be difficult to tell from the SHA if the version we've pinned has an update, or if that update is a security or important fix. Best practice therefore is to place a comment after the pinned version listing the semantic version for a third party github action. This gets you best of both worlds, maintainability plus certainty. It might look at bit like this: ``` jobs: check-pull-request: runs-on: ubuntu-latest steps: - name: Check out repository code uses: actions/checkout@ee066bloop # pin @v2 - name: Install Ruby uses: ruby/setup-ruby@22acsewblah # pin@v1 ``` Consistency here also helps us manage this code in line with the GDS Way requirement to Update dependencies frequently when managing third party dependencies: https://gds-way.digital.cabinet-office.gov.uk/standards/tracking-dependencies.html#update-dependencies-frequently Since October 2022 DependaBot will now look for comments on SHA pinning and automatically suggest updates. Similar approaches may be possible for other dependency management tools. Dependabot currently supports a range of different comment syntaxses which can be viewed here: https://github.com/dependabot/dependabot-core/pull/5951#issuecomment-1298147084 I've tried to keep the guidance general and open, leaving detail to this commit history, given the range of different tools on use across GDS. The principles are: - Pin your actions using SHAs - Ensure human readability by commenting the semver on the line with the action - Explore if your usual dependency management process, especially automated ones like DependaBot can help flag and raise visibility on new versions. --- .../source-code/use-github.html.md.erb | 17 +++++++++++++++-- 1 file changed, 15 insertions(+), 2 deletions(-) diff --git a/source/standards/source-code/use-github.html.md.erb b/source/standards/source-code/use-github.html.md.erb index 5d62ee6d..95b10f0d 100644 --- a/source/standards/source-code/use-github.html.md.erb +++ b/source/standards/source-code/use-github.html.md.erb @@ -55,13 +55,24 @@ Consider protecting the `.github/workflows` folder by using [a CODEOWNERS file]( Consider creating a Workflow Template in the [alphagov workflow folder](https://github.com/alphagov/.github/tree/main/workflow-templates) if you need to share a similar workflow between many repositories. -[Create your own local actions](https://docs.github.com/en/actions/creating-actions/about-actions) wherever possible. If using GitHub-owned actions, [pin to a specific version](https://docs.github.com/en/actions/learn-github-actions/finding-and-customizing-actions#using-release-management-for-your-custom-actions). +[Create your own local actions](https://docs.github.com/en/actions/creating-actions/about-actions) wherever possible. + +If using GitHub-owned actions, [pin to a specific version](https://docs.github.com/en/actions/learn-github-actions/finding-and-customizing-actions#using-release-management-for-your-custom-actions) and [configure Dependabot to keep your actions up to date](https://docs.github.com/en/code-security/dependabot/working-with-dependabot/keeping-your-actions-up-to-date-with-dependabot#example-dependabotyml-file-for-github-actions) by adding a comment on the same line with the tag the commitsha represents. For example: + +``` +- uses: actions/checkout@01aecccf739ca6ff86c0539fbc67a7a5007bbc81 #v2.1.0 +``` + +Pinned versions should include the semver version in a comment next to the SHA, helping humans understand which versions we are pinned to. +Where possible, allow automated dependency management tools to scan these version comments and suggest updates. + Third-party actions should only be used if: - The provider is verified by GitHub (for example, [aws-actions](https://github.com/aws-actions)) - The action is complex enough that you cannot write your own local action - You have fully reviewed the code in the version of the third-party action you will be using - You have pinned the specific version in your workflow and in the repository settings, using a Git commit SHA +- You have included the semver version in a comment next to the SHA, helping humans understand the version and automated tools report on what is out of date (for example dependabot) - The third-party action is actively maintained, well-documented and tested ([follow the guidance on third party dependencies](/standards/tracking-dependencies.html)). You can enforce this in the settings for Actions by choosing ['Allow select actions'](https://docs.github.com/en/repositories/managing-your-repositorys-settings-and-features/enabling-features-for-your-repository/managing-github-actions-settings-for-a-repository#allowing-specific-actions-to-run) and then 'Allow actions created by GitHub' and 'Allow Marketplace actions by verified creators' as required. @@ -90,7 +101,9 @@ You should use your `@digital.cabinet-office.gov.uk` email during the sign up pr * [How to store source code](index.html) * [Working with Git](working-with-git.html) +* [Updating actions with DependaBot][github-dependabot-actions] [GitHub]: https://technology.blog.gov.uk/2016/05/31/how-we-use-git-at-the-government-digital-service/ [alphagov]: https://github.com/alphagov/ -[govuk-one-login]: https://github.com/govuk-one-login \ No newline at end of file +[govuk-one-login]: https://github.com/govuk-one-login +[github-dependabot-actions]: https://docs.github.com/en/code-security/dependabot/working-with-dependabot/keeping-your-actions-up-to-date-with-dependabot