You signed in with another tab or window. Reload to refresh your session.You signed out in another tab or window. Reload to refresh your session.You switched accounts on another tab or window. Reload to refresh your session.Dismiss alert
Copy file name to clipboardExpand all lines: practices/actions-best-practices.md
+40-15Lines changed: 40 additions & 15 deletions
Display the source diff
Display the rich diff
Original file line number
Diff line number
Diff line change
@@ -4,7 +4,7 @@
4
4
5
5
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.
6
6
7
-
This guide outlines best practices for securing your GitHub Actions workflows and minimizing security risks.
7
+
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.
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:
60
+
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:
61
61
62
62
```yaml
63
63
permissions:
@@ -83,28 +83,53 @@ While third-party actions can significantly enhance the functionality and effici
83
83
- *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.
84
84
- *Excessive Permissions*: Third-party actions may request more permissions than necessary, potentially exposing sensitive data or allowing unauthorized access to your repository.
85
85
86
-
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.
86
+
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.
87
87
88
-
### Pin Actions to Specific Versions
88
+
### Pin All Actions to a Commit SHA
89
89
90
-
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:
90
+
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:
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.
102
+
103
+
A minimal Dependabot configuration for GitHub Actions is:
104
+
105
+
```yaml
106
+
version: 2
107
+
updates:
108
+
- package-ecosystem: "github-actions"
109
+
directory: "/"
110
+
schedule:
111
+
interval: "weekly"
99
112
```
100
113
101
114
### Verify Third-Party Actions
102
115
103
-
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:
116
+
Third-party actions must not be the default choice. Before introducing one, teams should confirm that the requirement cannot be met by:
117
+
118
+
- Native GitHub Actions features such as `run` steps, reusable workflows, or built-in workflow syntax
119
+
- An action already owned and maintained within the organisation
120
+
- An action that is already approved for reuse by other teams
121
+
122
+
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.
123
+
124
+
If you can only achieve your goal with a third-party action then:
104
125
105
126
- Only use trusted actions from the GitHub Marketplace
106
127
- Review the source code of third-party actions before using them
107
128
- Consider forking and maintaining your own copy of critical actions
129
+
- Keep a record of the approval decision and the version or SHA that was reviewed
130
+
- Be prepared to replace the action if organisational policy restricts the allowed set of actions
131
+
132
+
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.
0 commit comments