GitHub Actions Workflow Checker

A security-focused tool that automatically updates GitHub Actions workflows to use pinned commit SHAs instead of floating tags, protecting against supply chain attacks while maintaining compatibility.

🔐 Security Features

• Automatically updates GitHub Actions to use pinned commit SHAs
• Prevents supply chain attacks by ensuring verified action versions
• Maintains workflow compatibility through testing
• Creates automated pull requests with security improvements
• Includes version information alongside hash updates

✨ Key Features

• Scans GitHub Actions workflow files (.yml and .yaml)
• Creates pull requests with detailed security improvements
• Supports both CLI and GitHub Actions workflow usage
• Handles semantic versioning and commit SHA references
• Runs in a secure Docker container with minimal permissions
• Provides detailed security reports

🚀 Quick Start

GitHub Actions Workflow (Recommended)

Add this workflow to your repository:

name: Update GitHub Actions Dependencies

on:
  schedule:
    - cron: "0 0 * * 1"  # Runs every Monday
  workflow_dispatch:      # Manual trigger option
    inputs:
      dry-run:
        description: 'Show changes without applying them'
        required: false
        default: 'false'
        type: boolean
      workflows-path:
        description: 'Path to workflow files'
        required: false
        default: '.github/workflows'
        type: string

jobs:
  update-actions:
    runs-on: ubuntu-latest
    permissions:
      contents: write
      pull-requests: write
    
    steps:
      - uses: actions/checkout@11bd71901bbe5b1630ceea73d27597364c9af683  # v4.2.2
      - name: Update GitHub Actions
        uses: ThreatFlux/githubWorkFlowChecker@fc3d69cb98fb60b80a6009169959831d4f49ee7d  # v1.20250309.1
        with:
          token: ${{ secrets.GITHUB_TOKEN }}
          owner: ${{ github.repository_owner }}
          repo-name: ${{ github.event.repository.name }}
          labels: "dependencies,security"
          # Optional parameters
          workflows-path: ${{ inputs.workflows-path }}
          dry-run: ${{ inputs.dry-run }}
          # stage: 'false'  # Uncomment to apply changes locally without creating a PR

CLI Installation

Using Docker

docker pull ghcr.io/threatflux/ghactions-updater:latest

📋 Usage

CLI Options

ghactions-updater [options]

Option	Description	Required	Default
-token	GitHub token with PR permissions (see Required Token Scopes)	✅	-
-owner	Repository owner	✅	-
-repo-name	Repository name	✅	-
-repo	Repository path	❌	"."
-workflows-path	Path to workflow files	❌	".github/workflows"
-dry-run	Show changes without applying them	❌	false
-stage	Apply changes locally without creating PR	❌	false
-version	Print version information	❌	-

Environment Variables

• GITHUB_TOKEN: Alternative to -token flag
• OWNER: Alternative to -owner flag
• REPO_NAME: Alternative to -repo-name flag
• WORKFLOWS_PATH: Alternative to -workflows-path flag

Required Token Scopes

The GitHub token must have the following scopes to function properly:

• repo or public_repo: Required for reading repository contents and creating pull requests
  • Use repo for private repositories
  • Use public_repo for public repositories only
• workflow: Required for modifying GitHub Actions workflow files

The tool will validate token scopes on startup and provide clear error messages if required permissions are missing. For GitHub App tokens or fine-grained personal access tokens, ensure equivalent permissions are granted.

🛠️ Development

Prerequisites

• Go 1.24.3 or later
• Make
• Docker (optional)
• Git

Local Setup

1. Clone the repository:

git clone https://github.com/ThreatFlux/githubWorkFlowChecker.git
cd githubWorkFlowChecker

2. Install dependencies:

make install-tools
go mod download

3. Install git hooks (optional but recommended):

./scripts/git-hooks/install.sh

Git Hooks

This project includes pre-commit hooks that automatically:

• Format Go code (make fmt)
• Run linter (make lint)
• Run tests (make test) - requires GITHUB_TOKEN
• Build the project (make build)

To install the hooks:

./scripts/git-hooks/install.sh

To skip hooks temporarily:

git commit --no-verify

Common Tasks

Command	Description
make build	Build binary
make test	Run tests
make lint	Run linter
make security	Run security checks
make docker-build	Build Docker image
make clean	Clean up build artifacts

📚 Documentation

• Security Policy - Security policy and reporting vulnerabilities
• Contributing Guidelines - Guidelines for contributing
• Code of Conduct - Community behavior guidelines

🔒 Security

• All dependencies are regularly updated and scanned for vulnerabilities
• Docker images are signed and include SBOMs
• Actions are pinned to specific commit SHAs
• Minimal container permissions and secure defaults

Report security vulnerabilities via GitHub Security Advisories

📜 License

MIT License - see LICENSE file for details.

🤝 Contributing

Contributions are welcome! Please read our Contributing Guidelines before submitting a pull request.

📬 Support

• Open an issue
• Start a discussion
• Email: wyattroersma@gmail.com

⭐ Acknowledgments

Thanks to all contributors and the GitHub Actions community for making this tool possible.