Skip to content

Commit

Permalink
Expand github action pinning guidance to include update approach
Browse files Browse the repository at this point in the history
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:
dependabot/dependabot-core#5951 (comment)

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.
  • Loading branch information
huwd committed Feb 9, 2024
1 parent b224a6b commit af588ea
Showing 1 changed file with 4 additions and 0 deletions.
4 changes: 4 additions & 0 deletions source/standards/source-code/use-github.html.md.erb
Original file line number Diff line number Diff line change
Expand Up @@ -52,12 +52,16 @@ 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).
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
- 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.
Expand Down

0 comments on commit af588ea

Please sign in to comment.