codfish/actions

A collection of reusable GitHub Actions for common development workflows. Each action is self-contained and designed for maximum reusability across different projects.

Table of Contents

• Usage
• Available Actions
  • comment
  • npm-pr-version
  • setup-node-and-install
• Contributing
• Example Workflow
• Maintenance
  • Test pull requests in downstream apps before merging

Usage

Reference actions using the following format:

uses: codfish/actions/{action-name}@main
uses: codfish/actions/{action-name}@v3
uses: codfish/actions/{action-name}@v3.0.1
uses: codfish/actions/{action-name}@feature-branch
uses: codfish/actions/{action-name}@9f7cf1a3ff9f2838eff5ec9ac69b6ff277610bb2

Available Actions

comment

Creates or updates a comment in a pull request with optional tagging for upsert functionality

Inputs:

Input	Description	Required	Default
message	The comment message content (supports markdown formatting)	Yes	-
tag	Unique identifier to find and update existing comments (required when upsert is true)	No	-
upsert	Update existing comment with matching tag instead of creating new comment	No	false

Usage:

- uses: codfish/actions/comment@v3

npm-pr-version

Publishes package with PR-specific version (0.0.0-PR-123--abc1234) using detected package manager (npm/yarn/pnpm) or OIDC trusted publishing, and automatically comments on PR

Inputs:

Input	Description	Required	Default
npm-token	Registry authentication token with publish permissions. If not provided, OIDC trusted publishing will be used.	No	-
tarball	Path to pre-built tarball to publish (e.g., '*.tgz'). When provided, publishes the tarball with --ignore-scripts for security. Recommended for pull_request_target workflows to prevent execution of malicious lifecycle scripts.	No	-
comment	Whether to comment on the PR with the published version (true/false)	No	true
comment-tag	Tag to use for PR comments (for comment identification and updates)	No	npm-publish-pr

Outputs:

Output	Description
version	Generated PR-specific version number (0.0.0-PR-{number}--{short-sha})
package-name	Package name from package.json
error-message	Error message if publish fails

Usage:

on: pull_request

jobs:
  publish:
    permissions:
      id-token: write
      pull-requests: write

    steps:
      - uses: actions/checkout@v6

      - uses: codfish/actions/setup-node-and-install@v3
        with:
          node-version: lts/*

      - run: npm run build

      - uses: codfish/actions/npm-pr-version@v3

setup-node-and-install

Sets up Node.js environment and installs dependencies with automatic package manager detection (npm/pnpm/yarn), intelligent caching, and version detection via input, .node-version, .nvmrc, or package.json volta.node

Inputs:

Input	Description	Required	Default
node-version	Node.js version to install (e.g. "24", "lts/*"). Precedence: node-version input > .node-version > .nvmrc > package.json volta.node.	No	-
install-options	Extra command-line options to pass to npm/pnpm/yarn install.	No	-
working-directory	Directory containing package.json and lockfile.	No	.
upgrade-npm	Whether to upgrade npm to v11.5.1. This is required for OIDC trusted publishing but can be disabled if you want to shave off some run time and you are still using token-based authentication.	No	true

Outputs:

Output	Description
node-version	The installed node version.
cache-hit	Whether the dependency cache was hit (true/false).
pnpm-dest	Expanded path of pnpm dest.
pnpm-bin-dest	Location of pnpm and pnpx command.

Usage:

- uses: codfish/actions/setup-node-and-install@v3

Contributing

Each action follows these conventions:

• Directory structure: Actions are in kebab-case directories at the repository root
• Required files: action.yml, README.md
• Composite actions: All actions use composite type for simplicity and transparency
• Documentation: Each action includes comprehensive usage examples and input/output documentation

Example Workflow

Complete workflow using multiple actions together with secure OIDC trusted publishing:

name: Validate

on: pull_request_target

jobs:
  # Build and test with untrusted PR code (no secrets)
  build-and-test:
    runs-on: ubuntu-latest

    permissions:
      contents: read
      pull-requests: write

    steps:
      - uses: actions/checkout@v6
        with:
          ref: ${{ github.event.pull_request.head.sha }}

      - uses: codfish/actions/setup-node-and-install@v3

      - name: Run tests
        id: test
        run: |
          pnpm test 2>&1 | tee test-output.txt
          if grep -q "All tests passed" test-output.txt; then
            echo "status=✅ passed" >> $GITHUB_OUTPUT
          else
            echo "status=❌ failed" >> $GITHUB_OUTPUT
          fi
          echo "count=$(grep -c "✓\|√\|PASS" test-output.txt || echo "unknown")" >> $GITHUB_OUTPUT

      - name: Build package
        id: build
        run: |
          pnpm build

          if [ -d "dist" ]; then
            size=$(du -sh dist | cut -f1)
          elif [ -d "build" ]; then
            size=$(du -sh build | cut -f1)
          else
            size="unknown"
          fi
          echo "size=$size" >> $GITHUB_OUTPUT

      - uses: codfish/actions/comment@v3
        with:
          message: |
            ## 🚀 **Build Summary**

            **Tests**: ${{ steps.test.outputs.status }} (${{ steps.test.outputs.count }} tests)
            **Build**: ✅ completed successfully
            **Size**: ${{ steps.build.outputs.size }}

            Ready for testing! 🎉
          tag: 'build-summary'
          upsert: true

      - name: Create package tarball
        run: pnpm pack

      - uses: actions/upload-artifact@v4
        with:
          name: package-tarball
          path: '*.tgz'
          retention-days: 1

  # Publish with secrets using only trusted base branch code
  publish:
    needs: build-and-test

    runs-on: ubuntu-latest

    permissions:
      contents: read
      id-token: write
      pull-requests: write

    steps:
      - uses: actions/checkout@v6
        # No ref = uses base branch (trusted code only)

      - uses: codfish/actions/setup-node-and-install@v3

      - uses: actions/download-artifact@v4
        with:
          name: package-tarball

      - uses: codfish/actions/npm-pr-version@v3
        with:
          tarball: '*.tgz' # Secure: uses --ignore-scripts
          comment-tag: 'pr-package'

Maintenance

The release workflow automatically updates the major version tag (v3, v4, v5, etc.) to point to the latest release for that major version. This allows users binding to the major version tag to automatically receive the most recent stable minor/patch releases.

This happens automatically in the release workflow after each successful release.

If you need to update the major version tag manually:

git tag -fa v5 -m "Update v5 tag" && git push origin v5 --force

Reference: https://github.com/actions/toolkit/blob/main/docs/action-versioning.md#recommendations

Test pull requests in downstream apps before merging

Our validation workflow builds and publishes a multi-arch Docker image to GitHub Container Registry for every pull request, tagging the image with the PR's branch name. You can point downstream repositories at this branch-tagged image to try changes before merging.

- uses: codfish/actions:<branch-name>