Cover photo used under Creative Commons
It comes as no surprise that the tags and branches solution to version GitHub Actions is weak at best. There have been rumors of Actions moving to a different model (GitHub Container Registry), but that is yet to see the light.
To protect your GitHub Actions repository there are a few things the author of an Action should do.
1. Setup 2FA
The author of a GitHub Action should always enable 2FA for their account.
You could consider putting all your actions in a GitHub Organization instead of your personal account, which enables a number of extra policies (like enforced 2FA). This will also allow you to enable the ✅ verified creator on your marketplace listing.
2. Limit default permissions of your Actions in your repo
In the Actions settings you can limit what actions can do by default, requiring the author to set explicit permissions thus reducing the default permissions of your workflows.
Limit the actions the repo is permitted to run to the exact list of actions used by your repository:
You can further limit what a GitHub Actions workflow can do. Recommended settings:
- Require approval for all outside collaborator
- Read repository contents and package permissions
- Do not allow GitHub Actions to create and approve pull requests
3. Setup tag protection
Setup protected tags to limit who can overwrite your tags. This will prevent GitHub Actions workflows from overwriting existing tags. It won't prevent the creation of new minor versions though. Major versions will need to be updated by a repository owner or a GitHub App token with Repository Admin permissions.
Unfortunately, the tag name format doesn't support regular expressions. To not block the creation of a tag called
verify-sanity
or any other tag name that starts with av
, I've added the protections for all the ways a version tag can be named in GitHub Actions.
Create a protected tag for v0
to v9
as well as v*.*
and v*.*.*
.
4. Setup Branch protection
With the new Ruleset feature you can limit the branches that can be created. GitHub Actions will favor a branch with the name v1
over a tag with the same name. Thus, a new branch could be used to redirect users of your action to a different implementation.
Unfortunately, the branch format doesn't support regular expressions. To not block the creation of a branch called
verify-sanity
or any other branch name that starts with av
, I've added the protections for all the ways a version tag can be named in GitHub Actions.
Create a new Rule named "Do not allow versioned branches" and a rule for v0
to v9
:
Configure the policy to:
- Restrict creation
- Restrict updates
- Block force pushes
Also be sure to setup a Branch Protection for your main branch. Personally, I've setup the following rules:
If you have more than one maintainer, you block everyone from bypassing these rules. If you're a lone maintainer like me, you'll have to allow yourself to bypass this protection.
5. Setup GitHub's security features
Enable Secret Scanning and push protection:
Enable Dependabot Alerts and Version Updates:
Add a .github/dependabot.yml
to your Actions's repository:
version: 2
updates:
- package-ecosystem: "github-actions"
directory: "/" # Location of package manifests
schedule:
interval: "weekly"
6. Use GitHub App Tokens or Fine-grained Access Tokens
Now that the Fine-grained personal access tokens support both the REST and the GraphQL API, be sure to delete any remaining Classic Personal Access Tokens and replace them with a Fine-grained token with only the scopes, organisations and repositories needed by the token.
Where possible limit the token to Only select repositories :
If you are keeping all your actions in an organisation instead of your personal account and have enabled Single Sign-on, then your Access tokens will require additional SSO-authorization. This will add yet another layer of security. Single Sign-on is unfortunately only available for GitHub Enterprise Cloud, not on the Free and Teams plan.
In actions workflows rely on GitHub Apps instead of personal acces tokens:
steps:
- id: create_token
uses: tibdex/github-app-token@0914d50df753bbc42180d982a6550f195390069f # v2
with:
app_id: ${{ secrets.APP_ID }}
private_key: ${{ secrets.PRIVATE_KEY }}
- run: "echo 'The created token is masked: ${{ steps.create_token.outputs.token }}'"
7. Prefer forks to collaborate over adding collaborators to the repo
This last item may be a bit paranoid, but GitHub protects your repository quite a bit better when other collaborators submit their changes from a fork instead of from a branch in the same repository.
This way collaborators can't:
- Create tags
- Create branches
- Access repository secrets
- Run a changed workflow without approval (see policy above)
8. Use sha
over tags in all workflows used by your own GitHub Action.
Enable RenovateBotor OSSF Scorecard to automatically replace the version tags in your workflows and composite actions with their sha
.
For RenovateBot add the following snippet to your .github/renovate.json
:
{
"extends": ["helpers:pinGitHubActionDigests"]
}
And when these tools suggest upgrading to a newer version, make sure you verify the contents of the new release.
9. Reduce your dependencies
I just went over all my own GitHub Actions and Azure Pipelines Task repositories and removed 3rd party dependencies that I didn't strictly need. For example, I had a dependency on marvinpinto/action-automatic-releases@latest
which I replaced with 3 lines of code in a run block:
git tag latest HEAD --force
git push origin latest --force
gh release create latest --generate-notes --prerelease --latest --title "Development Build" ./ppt-diffmerge-tool/bin/Release/ppt-diffmerge.zip
One less dependency to worry about. This way I managed to remove most of my non-major-vendor dependencies.
10. Ensure your tags are versioned correctly
GitHub Actions requires the author of the action to manage the versioning of the action itself. It does that through tags. One set of tags should be locked down, your build/patch versions (v1.2.x
), the other tags are floating and should be updated every time a new build/patch version is added (v1.x
, vx
).
There is no built-in mechanism to ensure the versions have been updated correctly and if v1
doesn't point to v1.0.5
, but instead still points to v1.0.0
, then all the people using @v1
of your action will forever be on the older version.
To at least ensure your major version is pointing to the latest build/patch version, you can use an action I've created:Actions SemVer Checker - GitHub Marketplace Checks the version tags for your action repository to ensure the correct versions will be picked
Here's a sample workflow that will flag any versioning issues:
name: Check SemVer
on:
push:
tags:
- '*'
workflow_dispatch:
jobs:
check-semver:
concurrency:
group: '${{ github.workflow }}'
cancel-in-progress: true
runs-on: ubuntu-latest
steps:
- uses: actions/checkout@v4
with:
fetch-depth: 0
- uses: jessehouwing/actions-semver-checker@v1
with:
warn-minor-version: true
Conclusion
There are a lot of things an action author can do to ensure the security of their own actions. Apart from all of these repository settings, it's of course important to create an action that's secure by itself. The GitHub Security Lab Blog has written a number of articles on Action Security that I whole heartedly recommend:
- Keeping your GitHub Actions and workflows secure Part 1: Preventing pwn requests
- Keeping your GitHub Actions and workflows secure Part 2: Untrusted input
- Keeping your GitHub Actions and workflows secure Part 3: How to trust your building blocks
Let's build a more secure Actions ecosystem together!
Top comments (0)