From 981dc6c04f7adc6a7dbd664705b9a1a6035a371b Mon Sep 17 00:00:00 2001 From: Chris Walters Date: Tue, 24 Mar 2026 12:29:03 +0000 Subject: [PATCH 1/4] updating guidance on actions usage --- practices/actions-best-practices.md | 41 +++++++++++++++++++---------- 1 file changed, 27 insertions(+), 14 deletions(-) diff --git a/practices/actions-best-practices.md b/practices/actions-best-practices.md index 350203e4..7999a3bd 100644 --- a/practices/actions-best-practices.md +++ b/practices/actions-best-practices.md @@ -4,7 +4,7 @@ GitHub Actions is a powerful automation tool that enables CI/CD workflows directly within your GitHub repository. Securing your GitHub Actions workflows is crucial to protect your code, secrets, and infrastructure from potential security threats. -This guide outlines best practices for securing your GitHub Actions workflows and minimizing security risks. +This guide outlines best practices for securing your GitHub Actions workflows and minimizing security risks. All actions used in committed workflow definitions must be pinned to a full-length commit SHA. ## Table of Contents @@ -40,7 +40,7 @@ jobs: environment: production runs-on: ubuntu-latest steps: - - uses: actions/checkout@v3 + - uses: actions/checkout@692973e3d937129bcbf40652eb9f2f61becf3332 # v4.1.7 - name: Deploy env: API_TOKEN: ${{ secrets.API_TOKEN }} @@ -57,7 +57,7 @@ jobs: ### Use Least Privilege Principle -Limit the GitHub token permissions to only what's necessary please [see here](https://docs.github.com/en/actions/security-for-github-actions/security-guides/automatic-token-authentication#permissions-for-the-github_token) for details on the default permissions that the github token is given when the permissions block is not used: +Limit the GitHub token permissions to only what's necessary [see here](https://docs.github.com/en/actions/security-for-github-actions/security-guides/automatic-token-authentication#permissions-for-the-github_token) for details on the default permissions that the github token is given when the permissions block is not used: ```yaml permissions: @@ -83,19 +83,32 @@ While third-party actions can significantly enhance the functionality and effici - *Lack of Maintenance*: Some third-party actions may not be actively maintained, leaving them vulnerable to security issues or compatibility problems with newer GitHub Actions features. - *Excessive Permissions*: Third-party actions may request more permissions than necessary, potentially exposing sensitive data or allowing unauthorized access to your repository. -To mitigate these risks, always follow best practices, such as pinning actions to specific commit SHAs, reviewing the source code of actions, and using only trusted actions from reputable sources. +To mitigate these risks, all actions must be pinned to specific commit SHAs, reviewed before adoption, and sourced only from trusted publishers. -### Pin Actions to Specific Versions +### Pin All Actions to a Commit SHA -When including a GitHub Action within your workflow you should perform due diligence checks to ensure that the action achieves the aims you are intending it to, and that it doesn't do anything unintended, this would include performing a code review of the GitHub action code. To prevent the underlying code being changed without your awareness always use specific commit SHAs instead of tags or branches as tags can be modified if the upstream repository is compromised: +When including a GitHub Action within your workflow you should perform due diligence checks to ensure that the action achieves the aims you are intending it to, and that it does not do anything unintended, including reviewing the action code where appropriate. Every action reference must use a full-length commit SHA, including GitHub-authored actions, marketplace actions, and internally maintained actions. Do not use tags or branch references in committed workflow definitions because they can move without review or be modified if the upstream repository is compromised: ```yaml # Not secure - can change unexpectedly -- uses: actions/checkout@v3 -# Better - using a specific version tag -- uses: actions/checkout@v3.1.0 -# Best - using a specific commit SHA -- uses: actions/checkout@2541b1294d2704b0964813337f33b291d3f8596b # v3.1.0 +- uses: actions/checkout@v4 +# Also not acceptable - tags can be moved +- uses: actions/checkout@v4.1.7 +# Required - pin to the full commit SHA and optionally annotate the tag for readability +- uses: actions/checkout@692973e3d937129bcbf40652eb9f2f61becf3332 # v4.1.7 +``` + +If you use automation such as Dependabot to keep actions up to date, enable the `github-actions` ecosystem in `dependabot.yml` and keep the release tag comment on the same line as the pinned SHA so updates continue to track tagged releases. + +A minimal Dependabot configuration for GitHub Actions is: + +```yaml +version: 2 +updates: + - package-ecosystem: "github-actions" + directory: "/" + schedule: + interval: "weekly" ``` ### Verify Third-Party Actions @@ -164,7 +177,7 @@ jobs: permissions: contents: read steps: - - uses: actions/checkout@v3 + - uses: actions/checkout@692973e3d937129bcbf40652eb9f2f61becf3332 # v4.1.7 - name: Run tests run: npm test ``` @@ -189,9 +202,9 @@ jobs: id-token: write contents: read steps: - - uses: actions/checkout@v3 + - uses: actions/checkout@692973e3d937129bcbf40652eb9f2f61becf3332 # v4.1.7 - name: Configure AWS credentials - uses: aws-actions/configure-aws-credentials@v1 + uses: aws-actions/configure-aws-credentials@e3dd6a429d7300a6a4c196c26e071d42e0343502 # v4.0.2 with: role-to-assume: arn:aws:iam::${{ secrets.AWS_ACCOUNT_ID }}:role/github-actions aws-region: eu-west-2 From f7e91f6ad18fd1cba0eabf2ef2c8453e26f53284 Mon Sep 17 00:00:00 2001 From: Chris Walters Date: Tue, 24 Mar 2026 14:19:38 +0000 Subject: [PATCH 2/4] updating discussion around third party actions --- practices/actions-best-practices.md | 16 ++++++++++++++-- 1 file changed, 14 insertions(+), 2 deletions(-) diff --git a/practices/actions-best-practices.md b/practices/actions-best-practices.md index 7999a3bd..bde7c896 100644 --- a/practices/actions-best-practices.md +++ b/practices/actions-best-practices.md @@ -83,7 +83,7 @@ While third-party actions can significantly enhance the functionality and effici - *Lack of Maintenance*: Some third-party actions may not be actively maintained, leaving them vulnerable to security issues or compatibility problems with newer GitHub Actions features. - *Excessive Permissions*: Third-party actions may request more permissions than necessary, potentially exposing sensitive data or allowing unauthorized access to your repository. -To mitigate these risks, all actions must be pinned to specific commit SHAs, reviewed before adoption, and sourced only from trusted publishers. +To mitigate these risks, all actions must be pinned to specific commit SHAs, reviewed before adoption, and sourced only from trusted publishers. Teams must minimise use of third-party actions and should expect the permitted set of actions to be restricted over time. ### Pin All Actions to a Commit SHA @@ -113,11 +113,23 @@ updates: ### Verify Third-Party Actions -When including a GitHub Action within your workflow consider alternatives, is there an existing mechanism you can use? Would this be something that could be reused and you could create your own action within the organisation that other teams could benefit from? If you can only achieve your goal with a third-party action then: +Third-party actions must not be the default choice. Before introducing one, teams should confirm that the requirement cannot be met by: + +- Native GitHub Actions features such as `run` steps, reusable workflows, or built-in workflow syntax +- An action already owned and maintained within the organisation +- An action that is already approved for reuse by other teams + +If a third-party action is still required, document why it is needed, what alternatives were considered, and why those alternatives were rejected. Teams should prefer actions with a clear maintenance history, minimal permissions, and a narrow, well-understood scope. + +If you can only achieve your goal with a third-party action then: - Only use trusted actions from the GitHub Marketplace - Review the source code of third-party actions before using them - Consider forking and maintaining your own copy of critical actions +- Keep a record of the approval decision and the version or SHA that was reviewed +- Be prepared to replace the action if organisational policy restricts the allowed set of actions + +The long-term direction is to lock down the set of actions that can be used. Teams should therefore avoid introducing new third-party actions unless there is a clear, defensible need. ### Use Actions Security Best Practices From fcd0a8831c9b18c5edb69c7baa7220beea9b4d03 Mon Sep 17 00:00:00 2001 From: walteck Date: Wed, 25 Mar 2026 08:02:19 +0000 Subject: [PATCH 3/4] Update practices/actions-best-practices.md Co-authored-by: Nick Miles <7bzbaedz8d@snkmail.com> --- practices/actions-best-practices.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/practices/actions-best-practices.md b/practices/actions-best-practices.md index bde7c896..5560f6e0 100644 --- a/practices/actions-best-practices.md +++ b/practices/actions-best-practices.md @@ -119,7 +119,7 @@ Third-party actions must not be the default choice. Before introducing one, team - An action already owned and maintained within the organisation - An action that is already approved for reuse by other teams -If a third-party action is still required, document why it is needed, what alternatives were considered, and why those alternatives were rejected. Teams should prefer actions with a clear maintenance history, minimal permissions, and a narrow, well-understood scope. +If a third-party action is still required, document why it is needed, what alternatives were considered, and why those alternatives were rejected. This should live in `docs/ADRs.md`, or similar, to ensure the decision process is held within the repository. Teams should prefer actions with a clear maintenance history, minimal permissions, and a narrow, well-understood scope. If you can only achieve your goal with a third-party action then: From 6716387ac5f3833e17d201f97fc501961d9c30d1 Mon Sep 17 00:00:00 2001 From: Chris Walters Date: Wed, 25 Mar 2026 08:04:15 +0000 Subject: [PATCH 4/4] docs: require tag annotation comment when pinning actions to commit SHA --- practices/actions-best-practices.md | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/practices/actions-best-practices.md b/practices/actions-best-practices.md index 5560f6e0..c3c732d0 100644 --- a/practices/actions-best-practices.md +++ b/practices/actions-best-practices.md @@ -87,14 +87,14 @@ To mitigate these risks, all actions must be pinned to specific commit SHAs, rev ### Pin All Actions to a Commit SHA -When including a GitHub Action within your workflow you should perform due diligence checks to ensure that the action achieves the aims you are intending it to, and that it does not do anything unintended, including reviewing the action code where appropriate. Every action reference must use a full-length commit SHA, including GitHub-authored actions, marketplace actions, and internally maintained actions. Do not use tags or branch references in committed workflow definitions because they can move without review or be modified if the upstream repository is compromised: +When including a GitHub Action within your workflow you should perform due diligence checks to ensure that the action achieves the aims you are intending it to, and that it does not do anything unintended, including reviewing the action code where appropriate. Every action reference must use a full-length commit SHA, including GitHub-authored actions, marketplace actions, and internally maintained actions, and must include an inline comment identifying the corresponding tag or version. Do not use tags or branch references in committed workflow definitions because they can move without review or be modified if the upstream repository is compromised. The tag annotation comment is not optional — without it, a pinned SHA is opaque and cannot be reviewed or updated effectively: ```yaml # Not secure - can change unexpectedly - uses: actions/checkout@v4 # Also not acceptable - tags can be moved - uses: actions/checkout@v4.1.7 -# Required - pin to the full commit SHA and optionally annotate the tag for readability +# Required - pin to the full commit SHA and annotate the tag for readability - uses: actions/checkout@692973e3d937129bcbf40652eb9f2f61becf3332 # v4.1.7 ```