# GitHub Actions Setup Guide

## Overview

The MCP WordPress project includes comprehensive GitHub Actions workflows for automated testing, quality assurance, and
NPM publishing.

## Workflows

### 1. NPM Publish Workflow (`.github/workflows/npm-publish.yml`)

**Trigger**: When a GitHub release is created **Purpose**: Automatically publish the package to NPM

**Features**:

- ✅ Checkout code with latest actions
- ✅ Setup Node.js 18 with NPM registry
- ✅ Install dependencies with `npm ci`
- ✅ Run complete test suite
- ✅ Verify ignore file configurations
- ✅ Dry-run package contents verification
- ✅ Publish to NPM with authentication

**Required Secret**: `NPM_TOKEN`

**Usage**:

```bash
# Create a GitHub release to trigger publishing
gh release create v1.1.3 --title "Release v1.1.3" --notes "Release notes here"
```

### 2. CI Workflow (`.github/workflows/ci.yml`)

**Triggers**:

- Push to `main` or `develop` branches
- Pull requests to `main`
- Scheduled nightly runs

**Features**:

- 🧪 **Test Matrix**: Multiple Node.js versions (18, 20, 22)
- 🔍 **Quality Checks**: Linting, type checking, coverage
- 📦 **Build Verification**: Package building and installation
- 🌍 **WordPress Compatibility**: Tests against multiple WordPress versions
- 🚨 **Security Scanning**: Vulnerability scanning with Trivy
- 📚 **Documentation**: Link checking and TypeDoc generation

### 3. Additional Workflows

- **`dependency-update.yml`**: Automated dependency updates
- **`quality-assurance.yml`**: Comprehensive quality checks

## Setup Instructions

### 1. Configure NPM Token

1. **Generate NPM Token**:

   - Log in to [npmjs.com](https://npmjs.com)
   - Go to Account Settings → Access Tokens
   - Create an "Automation" token

2. **Add to GitHub Secrets**:
   - Go to your repository on GitHub
   - Settings → Secrets and variables → Actions
   - Click "New repository secret"
   - Name: `NPM_TOKEN`
   - Value: Your NPM automation token

### 2. Verify Workflow Configuration

Check that your workflows reference the correct package name and repository:

```yaml
# In npm-publish.yml
- name: Publish to NPM
  run: npm publish
  env:
    NODE_AUTH_TOKEN: ${{ secrets.NPM_TOKEN }}
```

### 3. Test the Workflows

1. **Test CI Workflow**:

   ```bash
   # Push to main branch triggers CI
   git push origin main
   ```

2. **Test NPM Publish**:

   ```bash
   # Create a release to trigger publishing
   git tag v1.1.3
   git push origin v1.1.3
   gh release create v1.1.3 --title "Release v1.1.3" --notes "Release notes"
   ```

## Workflow Details

### NPM Publish Process

1. **Trigger**: GitHub release created
2. **Environment**: Ubuntu latest, Node.js 18
3. **Steps**:
   - Checkout repository
   - Setup Node.js with NPM registry
   - Install dependencies (`npm ci`)
   - Run tests (`npm test`, `npm run test:tools`, `npm run health`)
   - Verify configurations (`npm run check:ignore`)
   - Dry-run verification (`npm publish --dry-run`)
   - Publish to NPM (`npm publish`)

### Security Features

- ✅ **Token Security**: NPM_TOKEN stored as GitHub secret
- ✅ **Scope Isolation**: Workflows only have necessary permissions
- ✅ **Vulnerability Scanning**: Automated security checks
- ✅ **File Verification**: Ensures no sensitive files are published

### Quality Assurance

- ✅ **Multi-Node Testing**: Compatibility across Node.js versions
- ✅ **Code Quality**: ESLint, TypeScript, coverage thresholds
- ✅ **WordPress Compatibility**: Tests against multiple WP versions
- ✅ **Documentation**: Automated link checking

## Troubleshooting

### NPM Publish Fails

1. **Check Token**: Ensure `NPM_TOKEN` secret is correctly set
2. **Verify Permissions**: Token must have publish permissions
3. **Version Conflicts**: Ensure version number is incremented

```bash
# Check if version already exists
npm view mcp-wordpress versions --json
```

### CI Failures

1. **Test Failures**: Check test output in Actions tab
2. **Dependency Issues**: Review package-lock.json changes
3. **Timeout Issues**: WordPress compatibility tests may timeout

### Security Scan Issues

1. **Vulnerability Alerts**: Review and update dependencies
2. **File Exclusion**: Ensure sensitive files are in `.npmignore`

## Best Practices

### Release Process

1. **Update Version**: Increment version in `package.json`
2. **Update Changelog**: Document changes
3. **Test Locally**: Run full test suite
4. **Create Release**: Use GitHub releases for publishing

```bash
# Recommended release flow
npm run test && npm run health && npm run check:ignore
git add . && git commit -m "release: v1.1.3"
git tag v1.1.3 && git push origin main --tags
gh release create v1.1.3 --title "Release v1.1.3" --notes-file RELEASE_NOTES_v1.1.3.md
```

### Monitoring

- **Actions Tab**: Monitor workflow runs
- **NPM Dashboard**: Check download stats
- **Security Alerts**: Review GitHub security advisories

## Maintenance

### Weekly Tasks

- Review workflow run status
- Check for dependency updates
- Monitor NPM package health

### Monthly Tasks

- Review and update workflow actions versions
- Audit security scan results
- Update documentation

## Example Release Creation

```bash
# Complete release process
npm version patch                    # Increment version
npm run test                        # Verify tests pass
git add package.json package-lock.json
git commit -m "release: v1.1.3"
git tag v1.1.3
git push origin main --tags
gh release create v1.1.3 \
  --title "Release v1.1.3" \
  --notes "Bug fixes and performance improvements" \
  --latest
```

This automatically triggers the NPM publish workflow and makes the new version available to users.

## Resources

- [GitHub Actions Documentation](https://docs.github.com/en/actions)
- [NPM Publishing Guide](https://docs.npmjs.com/packages-and-modules/contributing-packages-to-the-registry)
- [Semantic Versioning](https://semver.org/)
- [GitHub Releases](https://docs.github.com/en/repositories/releasing-projects-on-github)
