Protect the repository hosting your GitHub Action

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.

The GitHub Actions Worm: Compromising GitHub Repositories Through the Actions Dependency Tree

GitHub Actions worm compromises GitHub repositories via action dependencies in a novel attack vector allowing attackers to distribute malware across repositories, research shows.

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 Organisation 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 capabilities of 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 a v, 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<em>.</em> and v<em>.</em>.*.

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 a v, 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.

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 RenovateBot or OSSF Scorecard or Step Security 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.