tomgrv/actions

Reusable GitHub Actions

Overview

tomgrv/actions is a suite of modular, reusable GitHub composite actions designed to automate code quality, PR management, and package maintenance for monorepos and composer-based projects. Each action is self-contained, follows strict output/logging conventions, and is documented for easy integration into your workflows.

Actions are consumed directly from a workflow with uses: tomgrv/actions/<action-name>@<ref> — this repository is never published to npm (every package here, including the root one, is private: true; npm workspaces exist only to manage this monorepo's own code and tooling). For local testing, any action with a run.sh can be run from a clone of this repository via the bundled dispatch.sh, which sets sensible GITHUB_* defaults:

./dispatch.sh < action > [args...]

For example:

# Run lock coherence validation locally
GITHUB_TOKEN=ghp_xxx ./dispatch.sh check-lock

# List monorepo packages
./dispatch.sh list-packages

# Detect uncommitted changes
./dispatch.sh detect-changes

Run without arguments to see all available actions:

./dispatch.sh

Testing

Each action includes a test suite using BATS. Tests are colocated with their actions in <action-name>/run.bats files.

Run tests locally

Run all tests:

./run-tests.sh

Run tests for a specific action:

./run-tests.sh -f resolve-environment
./run-tests.sh -f detect-changes

Run with verbose output:

./run-tests.sh -v

For more options, see the test runner help:

./run-tests.sh -h

CI/CD

• validate-pr-tests: Runs the full test suite on every PR and push to main/develop
• test-run-deployer: Runs deployer-specific tests

Release process

Every repo in the tomgrv/perspikapps family releases via GitHub → Actions → release-main → "Run workflow" (no CLI needed), which checks out the repo and calls this repo's release-promote composite action. See docs/release-process.md for the full picture, including the tag/branch-protection bypass checklist every repo needs applied once by hand.

Naming convention

run-* actions analyze specific files (a paths/path input scoped to what changed) and report via reviewdog with -filter-mode=file: findings are limited to files that are actually part of the run's scope, but not further restricted to changed lines. check-* actions validate repository- or PR-wide state (manifests, lock files, secrets, PR metadata) that isn't tied to a specific set of files, and report with -filter-mode=nofilter. Both are fixed by the action itself and are not exposed as a configurable input; only reporter remains configurable, and it defaults to the value setup-reviewdog resolves for the run's context.

Available Actions

Badge legend: Stable   Beta   Experimental

🚀 Release

• release-promote : Run git-release-beta then git-release-prod (git-flow beta→prod promotion).

🔧 Utils

• config-bot : Configure git bot identity and authentication for CI/CD.
• setup-scripts : Idempotently bootstrap zz_use from tomgrv/scripts, optionally installing specific scripts.
• setup-gitversion : Idempotently install the gitversion devcontainer feature's toolchain (GitVersion CLI plus gv/bump-tag/bump-changelog/bump-version).
• setup-gitflow : Install the git-flow extension if missing, then initialize it against the checked-out repo.
• setup-php : Setup PHP, Composer, and extensions as per composer for CI jobs.
• setup-node : Setup Node.js and npm for CI jobs.
• setup-reviewdog : Setup reviewdog for CI jobs.
• resolve-environment : Resolve the deploy branch, tag, and environment from the triggering GitHub event.
• run-deployer : Install PHP Deployer and run a dep command, reporting warnings/errors via reviewdog.

📦 Monorepo

• list-packages : List all composer/npm packages in a monorepo.
• degit-package : Import the latest source branch content into a package repository and prune unwanted folders.
• split-package : Split a monorepo package to a separate repository based on path.

🐘 PHP Check

• check-laravel : Run the standard Laravel PHP check suite (PHPStan, Pint, PHP Insights, PHPMD, tests) and report via reviewdog.
• check-filament : Run Filament-specific checks (FilaCheck) and report via reviewdog.
• run-phpinsights : Run PHP Insights via reviewdog for inline code review feedback.
• run-filacheck : Run FilaCheck via reviewdog for inline Filament code review feedback.
• run-phpstan : Run PHPStan via reviewdog for inline code review feedback.
• run-phpmd : Run PHP Mess Detector and report via reviewdog.
• run-pint : Run Laravel Pint code style checks and report via reviewdog.
• run-phptests : Run the PHP test suite.
• check-security-composer : Audit Composer dependencies for known vulnerabilities.
• list-dirty : List files with uncommitted git changes, used by the PHP checks' dirty input.
• list-wip : List files changed on the current pull request, used by the PHP checks' wip input.

🔀 Pull Request

• create-pr : Open or update a pull request for a branch, with customizable title/body/labels.
• rebase-pr : Rebase the head branch of a pull request onto its base branch.
• check-pr-format : Validate PR title and body format.
• check-pr-source-branch : Reject PRs from the main branch unless marked as a hotfix.
• check-secret : Scan pull request changes for leaked secrets.
• check-security-npm : Audit npm dependencies for known vulnerabilities.
• check-lock : Validate composer.json/composer.lock and package.json/package-lock.json — schema, publish-readiness, and lock coherence — via reviewdog.

🏷️ Repository Management

• update-labels : Create or update repository labels from a JSON file or comma-separated list.
• detect-changes : Detect uncommitted or untracked changes in a given path.

See each action's README for usage, inputs, and outputs.

License

MIT License. See individual action folders for details.