@nesvel/github-actions

Production-ready GitHub Actions workflows and composite actions for Turborepo monorepos.

Overview

This package provides a complete CI/CD setup for pnpm + Turborepo monorepos, including:

• Workflows: Complete CI/CD pipelines
• Composite Actions: Reusable setup steps
• TypeScript Definitions: Type-safe access to workflow/action metadata

Installation

pnpm add -D @nesvel/github-actions

Quick Setup

Run the install script to automatically copy all workflows and actions to your repository:

# Easiest method (if package is installed)
pnpm github-actions-install

Alternative methods:

# From workspace root with filter
pnpm --filter=your-project exec @nesvel/github-actions install:workflows

# From within a package
pnpm exec @nesvel/github-actions install:workflows

This will:

• ✅ Create .github/workflows/ and .github/actions/ directories
• ✅ Copy all workflow files (ci.yml, release.yml, deploy.yml, dependabot.yml)
• ✅ Copy all composite actions (setup-node-pnpm, setup-turbo-cache)
• ✅ Display next steps for configuration

Automatic Installation

Add to your root package.json to run automatically on install:

{
  "scripts": {
    "postinstall": "pnpm exec @nesvel/github-actions install:workflows"
  }
}

Or create a dedicated setup script:

{
  "scripts": {
    "setup:ci": "pnpm exec @nesvel/github-actions install:workflows"
  }
}

Workflows

All workflows are located in the workflows/ directory and can be copied to your .github/workflows/ folder.

CI Workflow (ci.yml)

Comprehensive continuous integration with parallel job execution:

Jobs:

• Setup: Dependency caching
• Lint: ESLint checks
• Type Check: TypeScript validation
• Test: Jest/Vitest tests with coverage upload
• Build: Turborepo build with caching
• Security: pnpm audit checks
• Quality Gate: Ensures all checks pass

Features:

• pnpm store caching
• Turbo cache with GitHub Actions
• Codecov integration
• Runs on push to main/develop and PRs

Usage:

cp node_modules/@nesvel/github-actions/workflows/ci.yml .github/workflows/

Release Workflow (release.yml)

Automated package publishing using Changesets:

Features:

• Semantic versioning
• Changelog generation
• NPM publishing
• Slack notifications (optional)
• Triggered on push to main or manually

Required Secrets:

• NPM_TOKEN: NPM authentication token
• SLACK_WEBHOOK_URL (optional): Slack webhook for notifications

Usage:

cp node_modules/@nesvel/github-actions/workflows/release.yml .github/workflows/

Deploy Workflow (deploy.yml)

Application deployment with Docker and Cloud Run:

Features:

• Docker image building and pushing
• Google Cloud Run deployment
• Staging/production environments
• Slack deployment notifications

Required Secrets:

• REGISTRY_URL: Container registry URL
• REGISTRY_USERNAME: Registry username
• REGISTRY_PASSWORD: Registry password
• SLACK_WEBHOOK_URL (optional): Slack webhook

Usage:

cp node_modules/@nesvel/github-actions/workflows/deploy.yml .github/workflows/

Dependabot Auto-merge (dependabot.yml)

Automatically approve and merge Dependabot PRs:

Features:

• Auto-merge patch and minor updates
• Squash merge strategy
• Automatic approval

Usage:

cp node_modules/@nesvel/github-actions/workflows/dependabot.yml .github/workflows/

Composite Actions

Reusable action components for workflow composition.

Setup Node.js and pnpm

Sets up Node.js, pnpm, and caches the pnpm store.

Location: actions/setup-node-pnpm/action.yml

Inputs:

• node-version: Node.js version (default: 22)
• pnpm-version: pnpm version (default: 10.24.0)
• install-deps: Whether to install dependencies (default: true)

Outputs:

• pnpm-store-path: Path to pnpm store directory

Example:

- name: Setup Node and pnpm
  uses: ./.github/actions/setup-node-pnpm
  with:
    node-version: '22'
    pnpm-version: '10.24.0'

Setup Turbo Cache

Configures Turborepo caching with GitHub Actions cache.

Location: actions/setup-turbo-cache/action.yml

Inputs:

• turbo-token: Turbo token for remote caching (optional)
• turbo-team: Turbo team for remote caching (optional)

Example:

- name: Setup Turbo Cache
  uses: ./.github/actions/setup-turbo-cache
  with:
    turbo-token: ${{ secrets.TURBO_TOKEN }}
    turbo-team: ${{ secrets.TURBO_TEAM }}

TypeScript Usage

Access workflow and action metadata programmatically:

import { workflows, actions, getWorkflowPath, listWorkflows } from '@nesvel/github-actions';

// Get workflow metadata
console.log(workflows.ci.name); // "CI"
console.log(workflows.ci.description); // "Continuous Integration workflow..."

// Get workflow path
const ciPath = getWorkflowPath('ci'); // "workflows/ci.yml"

// List all workflows
const allWorkflows = listWorkflows();
// [
//   { name: 'CI', description: '...', path: 'workflows/ci.yml' },
//   { name: 'Release', description: '...', path: 'workflows/release.yml' },
//   ...
// ]

Customization

Modifying Workflows

1. Copy workflows to your repository:

   mkdir -p .github/workflows
   cp node_modules/@nesvel/github-actions/workflows/*.yml .github/workflows/

2. Edit as needed for your project requirements

Modifying Actions

1. Copy actions to your repository:

   mkdir -p .github/actions
   cp -r node_modules/@nesvel/github-actions/actions/* .github/actions/

2. Update action references in workflows:

   - uses: ./.github/actions/setup-node-pnpm

Best Practices

Secrets Management

Store sensitive values as GitHub repository secrets:

1. Navigate to Settings > Secrets and variables > Actions
2. Add required secrets (NPM_TOKEN, REGISTRY_PASSWORD, etc.)
3. Reference in workflows: ${{ secrets.SECRET_NAME }}

Caching Strategy

The workflows implement multi-level caching:

1. pnpm store cache: Speeds up dependency installation
2. Turbo cache: Accelerates build tasks
3. Build artifacts: Optional upload for debugging

Dependency Updates

Use Renovate or Dependabot to keep actions up to date:

// renovate.json
{
  "extends": ["config:base"],
  "packageRules": [
    {
      "matchManagers": ["github-actions"],
      "automerge": true,
      "automergeType": "pr"
    }
  ]
}

Requirements

• Node.js >= 22
• pnpm >= 10.24.0
• Turborepo monorepo structure
• GitHub Actions enabled

License

MIT

Changelog

See CHANGELOG.md for version history.