README
¶
gha-fix
gha-fix automates security and maintenance fixes in GitHub Actions workflows. It provides commands to address common issues in workflow files.
Features
- Pin GitHub Actions: Converts version references to specific commit SHAs for improved security
- Add Timeouts: Adds
timeout-minutesto GitHub Actions jobs to prevent workflows from running for too long
Installation
Using Go
go install github.com/Finatext/gha-fix@latest
Usage
pin
Pin GitHub Actions used in workflow files (.yml or .yaml) to specific commit SHAs.
This command scans GitHub Actions in workflow files and replaces references like 'owner/repo@v1' with specific commit SHAs like 'owner/repo@8843d7f53bd34e3b78f2acee556ba5d53feae7c4'.
gha-fix pin [file1 file2 ...] [flags]
If no files are specified, all workflow files (.yml or .yaml) in the current directory and subdirectories will be processed.
GitHub Token Configuration
GITHUB_TOKEN is required to fetch tags and commit SHAs from GitHub. Can be provided via environment variable or other ways.
Strict SHA Pinning (--strict-pinning-202508)
The --strict-pinning-202508 option implements support for GitHub's SHA pinning enforcement policy announced in August 2025. When enabled, this option modifies the behavior of ignore-owners:
- Actions, composite actions (e.g.,
my-org/repo@v1,my-org/repo/path/to/action@v4) will be pinned to SHAs even if their owner is specified in--ignore-ownersto follow SHA pinning enforcement policy - Reusable workflows (e.g.,
org/repo/.github/workflows/build.yml@main) will still respect the--ignore-ownerssetting
This differentiation allows organizations to comply with GitHub's security policies for composite actions while maintaining flexibility for reusable workflows. The tool distinguishes between composite actions and reusable workflows based on whether the action path contains a file extension.
Reference: GitHub Actions policy now supports blocking and SHA pinning actions
Example
# Process a specific workflow file
gha-fix pin .github/workflows/deploy.yml
# Process all workflow files in the current directory and subdirectories
gha-fix pin
# Ignore specific owners
gha-fix pin --ignore-owners=actions,github
# Enable strict SHA pinning for composite actions (GitHub's SHA pinning enforcement policy)
gha-fix pin --strict-pinning-202508
# Ignore specific directories when searching for workflow files (global option)
# This will skip any directory with these names, including in subdirectories (e.g., abc/def/node_modules/)
gha-fix --ignore-dirs=.git,node_modules,dist,out,vendor,.idea,.vscode pin
timeout
Add timeout-minutes to GitHub Actions workflow jobs that don't have one defined.
This command scans GitHub Actions workflow files and adds a timeout-minutes parameter to jobs without it. Jobs using reusable workflows (with 'uses' field) are automatically skipped since they don't directly support setting timeouts.
gha-fix timeout [file1 file2 ...] [flags]
If no files are specified, all workflow files (.yml or .yaml) in the current directory and subdirectories will be processed.
Example
# Add default timeout (5 minutes) to all workflow files
gha-fix timeout
# Set custom timeout value for specific workflow file
gha-fix timeout .github/workflows/deploy.yml --timeout-value 10
# Process all workflow files with custom timeout value
gha-fix timeout -t 15
# Process all workflow files with custom timeout value and ignore specific directories
gha-fix --ignore-dirs=node_modules,dist timeout -t 15
Acknowledgements
gha-fix adopts a text-based processing strategy for GitHub Actions workflow files, an approach inspired by suzuki-shunsuke/pinact.
In addition to this inspiration, gha-fix was developed to support new features and behavioral changes that better fit our use case. These include:
- Updating actions even when a branch name is specified, rather than failing.
- Exposing a Go interface that's easy to call from within our own tools.
- Scanning all directories by default — not just
.github— to support reusable workflows placed elsewhere.
Development
Release
Create a Git tag and push it. The CI/CD pipeline will take care of the release process.
Documentation
¶
Index ¶
Constants ¶
This section is empty.
Variables ¶
This section is empty.
Functions ¶
This section is empty.
Types ¶
type PinCommand ¶
type PinCommand struct {
// contains filtered or unexported fields
}
PinCommand is a command to pin GitHub Actions in workflow files to specific commit SHAs.
func NewPinCommand ¶
func NewPinCommand(client *gogithub.Client, opts PinOptions) PinCommand
NewPinCommand creates a new PinCommand with the provided GitHub client and options.
func (*PinCommand) Run ¶
Run executes the pin command with the provided context and file paths.
If filePaths is specified, pin the specified workflow files. Accepts both absolute and relative paths. If filePaths is emtpy, list all workflow files (.yml or .yaml) in the current directory and subdirectories.
When re-write YAML files, use temporary files then rename them to the original file names to do atomic updates.
type PinOptions ¶
type PinOptions struct {
IgnoreOwners []string
IgnoreRepos []string
IgnoreDirs []string
// Strict SHA pinning for new GitHub's SHA pinning enforcement policy. See README for details.
StrictPinning202508 bool
}
PinOptions defines options for the pin command.
type Result ¶
type Result = rewrite.RewriteResult
Result represents the result of a auto-fix operation.
type TimeoutCommand ¶
type TimeoutCommand struct {
// contains filtered or unexported fields
}
TimeoutCommand is a command to insert timeout-minutes to GitHub Actions jobs in workflow files.
func NewTimeoutCommand ¶
func NewTimeoutCommand(opts TimeoutOptions) TimeoutCommand
NewTimeoutCommand creates a new TimeoutCommand with the provided options.
type TimeoutOptions ¶
TimeoutOptions defines options for the timeout command.
Source Files
Directories