Protect the repository hosting your GitHub Action

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

If your GitHub Action is hosted on a GitHub Organisation, the policies and default workflow permissions can be set at the organisation level.

Clearly document the required permissions for your GitHub Action to make it easier for consumers of the action to set the correct limits on the scope of the GITHUB_TOKEN.

3. Setup tag protection

With the new Ruleset feature you can limit the tags that can be created or overwritten. You can use this feature to make all build/patch versions of your actions read-only, while still allowing the major versions to be overwritten.

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.

In order to cover all the bases, a number of rules must be created. Creating a tag rule is a bit hidden, you must click the 🔽 on the New ruleset and select New tag ruleset:

1. Patch versions are frozen for all - Apply this rule to target tags v*.*.*
   and configure the following policies:
   - Restrict updates
   - Restrict deletions
   - Block force pushes

2. Patch versions must be created by admins - To limit the number of people who can publish a new version of an action, limit the creation to admins only. Apply this rule to v*.*.* and limit:
   
   - Restrict creations
   - Block force pushes
   
   And add the repository admin role to the bypass list.

3. Floating versions cannot be deleted - to prevent people from deleting and recreating a tag, prevent deletions. Apply to v*.* , v1..v0 and exclude v*.*.*
   
   Limit:
   
   - Restrict deletions

4. Floating versions can only be created and updated by admins - This ensures that only admins can create or update a floating version. Apply to: v0..v9, v*.* , exclude v*.*.*
   
   Limit:
   
   - Restrict creations
   - Restrict updates
   - Block force pushes
   
   And add the repository admin role to the bypass list.

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, organizations and repositories needed by the token.

Limit the token to Only select repositories:

If you are keeping all your actions in an organization 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.

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:

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!