Open-Source Workflows Repository

Flexible, production-grade CI/CD workflows for linting, testing, and code cleanup. Designed to support any repository structure—monorepo or single package, works with Bun and pnpm.

Features

✅ Package Manager Agnostic - Auto-detects bun.lock or pnpm-lock.yaml ✅ Monorepo & Non-Monorepo Support - Works with Nx, Turborepo, or single packages ✅ Flexible Project Detection - Adapts to Angular, Next.js, React Native, etc. ✅ Intelligent Caching - Smart cache keys for dependencies and build artifacts ✅ Fail-Fast Testing - Tests per-project sequentially to isolate failures ✅ Type-Safety First - TypeScript validation before linting ✅ Accessibility Compliance - WCAG 2.1 AA standards built-in ✅ Zero Configuration - Works out of the box with sensible defaults

Quick Start

1. Add as Git Submodule

git submodule add https://github.com/your-org/workflows.git .workflows
git config -f .gitmodules submodule.workflows.shallow true
git submodule update --init --recursive

2. Use GitHub Actions Workflows

Copy workflows to .github/workflows/:

cp .workflows/github-actions/*.yml .github/workflows/

Or link them:

# In .github/workflows/ci.yml
name: CI
on: [push, pull_request]
jobs:
  include:
    - uses: ./.workflows/github-actions/lint.yml

3. Use Agent Workflows

Reference workflows for autonomous agent execution:

# Example: Run code quality check
bun scripts/execute-workflow.ts code-quality-check

Repository Detection

The workflows automatically detect your repository structure:

Detection Priority

1. bun.lock → Use Bun as package manager
2. pnpm-lock.yaml → Use pnpm as package manager
3. package-lock.json → Fall back to npm
4. yarn.lock → Fall back to yarn

Monorepo Detection

• Nx - Detects nx.json
• Turborepo - Detects turbo.json
• pnpm workspaces - Detects pnpm-workspace.yaml
• Single package - Uses package.json root

Workflow Types

GitHub Actions Workflows (.github/workflows/)

Automated CI/CD workflows triggered by GitHub events:

• ci.yml - Main CI pipeline (lint, type-check, test on every push/PR)
• lint.yml - ESLint + Prettier checks
• type-check.yml - TypeScript validation
• test.yml - Jest/Vitest unit testing
• code-quality.yml - Full quality check with auto-fix
• cleanup.yml - Manual workflow for fixing all issues

Agent Workflows (.agent/workflows/)

Documentation-based workflows for autonomous agent execution:

• code-quality-check.md - Type checking, linting, formatting
• fix-all-tests-workflow.md - Systematically fix all failing tests
• clean-all.md - Complete cleanup of all code quality issues
• build-and-fix.md - Build all projects and fix errors

Configuration

Environment Variables

Create .env or configure in your repo:

# Package manager (auto-detected if not set)
PACKAGE_MANAGER=bun

# Node version for actions
NODE_VERSION=22

# Skip certain checks
SKIP_ACCESSIBILITY_CHECKS=false
SKIP_E2E_TESTS=false

Custom Rules

ESLint Configuration

Place at repo root:

// .eslintrc.json
{
  "extends": ["eslint:recommended", "plugin:@typescript-eslint/recommended"],
  "rules": {
    "@typescript-eslint/no-explicit-any": "error"
  }
}

TypeScript Configuration

Place at repo root:

// tsconfig.json
{
  "compilerOptions": {
    "strict": true,
    "noImplicitAny": true
  }
}

Usage Examples

Run CI Locally

# Lint only changed files
bunx eslint --ext .ts,.tsx src/

# Type-check
bun run type-check

# Run tests
bun test

Use GitHub Actions

Push to trigger automatic workflows:

git add .
git commit -m "feat: new feature"
git push origin main

Manual Workflow Dispatch

Trigger from GitHub UI:

1. Go to Actions tab
2. Select workflow
3. Click Run workflow
4. Choose branch and options

Scripts

Utility scripts for local development and CI/CD:

detect-repo-type.ts

Automatically detects repository structure:

bun scripts/detect-repo-type.ts
# Output: { packageManager: 'bun', isMonorepo: true, buildSystem: 'nx' }

run-linter.ts

Flexible linting with file detection:

# Lint all files
bun scripts/run-linter.ts --all

# Lint changed files only
bun scripts/run-linter.ts --changed

# Fix issues
bun scripts/run-linter.ts --fix

run-tests.ts

Smart test runner:

# Run all tests
bun scripts/run-tests.ts --all

# Run changed tests
bun scripts/run-tests.ts --changed

# Run specific project
bun scripts/run-tests.ts --project web-app

# Run with coverage
bun scripts/run-tests.ts --coverage

fix-all-tests.ts

Systematically fix failing tests:

bun scripts/fix-all-tests.ts
# Runs each project sequentially until all pass

type-check-analyze.ts

Analyze TypeScript errors:

# Show all errors
bun scripts/type-check-analyze.ts

# Show only fixable errors
bun scripts/type-check-analyze.ts --fixable

# Show specific error code
bun scripts/type-check-analyze.ts --code TS2307

Supported Technologies

Package Managers

• Bun 1.0+
• pnpm 8+
• npm (fallback)
• Yarn (fallback)

Build Systems

• Nx 18+
• Turborepo 1.13+
• pnpm workspaces
• Single package repos

Frameworks

• Next.js 14+
• React 18+
• React Native 0.72+
• Angular 17+
• Vue 3+
• SvelteKit
• Node.js backends

Languages

• TypeScript (strict mode)
• JavaScript (ES2020+)
• JSX/TSX

Testing

• Jest 29+
• Vitest 1+
• Bun:test

CI/CD Integration

GitHub Actions

Workflows run on:

• Push to main, develop, staging
• Pull requests
• Manual workflow dispatch
• Scheduled (cron jobs)

Other Platforms

Adapt workflows for:

• GitLab CI - Convert .yml to .gitlab-ci.yml
• CircleCI - Use equivalent config format
• Jenkins - Use pipeline syntax
• Azure Pipelines - Use YAML format

Performance Optimization

Caching Strategy

• Node Modules - Cache based on lock files
• Build Artifacts - Cache .next, .nx/cache, etc.
• TypeScript Cache - Cache incremental compilation

Parallel Execution

• Tests run per-project for fail-fast
• Multiple workflows run concurrently
• Shared cache prevents duplicate work

Cost Reduction

• Skip expensive checks on documentation-only changes
• Use continue-on-error for non-blocking checks
• Run full suite only on main branch

Troubleshooting

Common Issues

"Package manager not detected"

# Ensure lock file exists
bun install  # Creates bun.lock
# or
pnpm install  # Creates pnpm-lock.yaml

"Cannot find project configuration"

# For Nx: ensure nx.json exists
# For Turborepo: ensure turbo.json exists
# For pnpm: ensure pnpm-workspace.yaml exists

"Tests fail in CI but pass locally"

• Check Node/Bun versions match
• Verify environment variables
• Check for cache issues: clear and rebuild

"Workflows run too slow"

• Enable caching (enabled by default)
• Run only changed files: --changed flag
• Reduce test suite: focus on affected projects

Contributing

Contributions welcome! Areas:

• New workflow templates
• Platform support (GitLab, CircleCI, etc.)
• Documentation improvements
• Performance optimizations
• Bug reports and fixes

License

MIT License - See LICENSE file

Resources

• Bun Documentation
• pnpm Documentation
• Nx Documentation
• GitHub Actions Documentation
• ESLint Configuration
• TypeScript Compiler Options

Related Projects

• AFFECTIVELY - Reference implementation
• Other open-source templates

Questions? Open an issue or discussion in the repository.