npm package: @nesvel/github-actions
Description: Reusable GitHub Actions workflows and composite actions for CI/CD
Author: Nesvel
Latest version: 1.0.3

# @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

```bash
pnpm add -D @nesvel/github-actions
```

## Quick Setup

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

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

Alternative methods:

```bash
# 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:

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

Or create a dedicated setup script:

```json
{
  "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:**

```bash
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:**

```bash
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:**

```bash
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:**

```bash
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:**

```yaml
- 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:**

```yaml
- 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:

```typescript
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:

   ```bash
   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:

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

2. Update action references in workflows:

   ```yaml
   - 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:

```json
// 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](./CHANGELOG.md) for version history.