🚀 GitHub Actions - Quick Start Guide

This repository uses an optimized GitHub Actions architecture with composite actions for maximum efficiency and reusability.

📦 What's Included

Composite Actions

• setup - Base setup with Node.js, pnpm, and caching
• build-portfolio - Build Astro portfolio with optimization
• build-api - Validate Cloudflare Workers API
• lint - Run Biome + Astro checks
• test-unit - Execute Vitest tests with coverage
• test-playwright - Run E2E tests with browser caching

Workflows

• ci.yml - Main CI pipeline (lint, test, build)
• deploy-portfolio.yml - Deploy Astro to Cloudflare Pages
• deploy-api.yml - Deploy Workers to Cloudflare
• release.yml - Automated semantic versioning
• cache-cleanup.yml - Weekly cache maintenance

⚡ Quick Examples

Use Setup in Your Workflow

steps:
  - uses: actions/checkout@v4
  - uses: ./.github/actions/setup
    with:
      node-version: '22'

Run Tests

- uses: ./.github/actions/test-unit
  with:
    project: 'portfolio'
    coverage: 'true'

Build & Deploy

- uses: ./.github/actions/build-portfolio
  with:
    skip-check: 'false'
    upload-artifact: 'true'

🎯 Key Benefits

• ✅ 52% faster CI runs with intelligent caching
• ✅ DRY principle - No code duplication
• ✅ Parallel execution - Multiple jobs run simultaneously
• ✅ Artifact management - Automated retention policies
• ✅ Matrix strategies - Test across browsers/projects

📊 Cache Strategy

Type	Key	Invalidation
pnpm	pnpm-lock.yaml	Lock file change
Playwright	Browser version	Version upgrade
Builds	Commit SHA	New commit

🔐 Required Secrets

Set these in repository settings → Secrets:

CLOUDFLARE_API_TOKEN
CLOUDFLARE_ACCOUNT_ID
SONAR_TOKEN (for code quality)

📚 Documentation

See docs/guides/composite-actions.md for:

• Detailed action documentation
• Advanced usage examples
• Troubleshooting guide
• Best practices

🚦 Workflow Status

The CI pipeline runs on:

• Push to main, develop, feature/*, fix/*
• Pull requests to main, develop

Jobs execute in this order:

Lint ──┬──> Build ──> E2E Tests ──> Report
       │                              ↑
Unit Tests ──> Code Quality ──────────┘

🛠️ Local Testing

# Test workflow locally with act
brew install act
act -j lint

# Validate workflow syntax
brew install actionlint
actionlint .github/workflows/*.yml

📈 Performance

Metric	Value
Average CI time	~12 min
Cache hit rate	~85%
Artifact retention	7-30 days

🤝 Contributing

When adding new composite actions:

1. Create action in .github/actions/<name>/action.yml
2. Add comprehensive inputs/outputs
3. Include usage examples
4. Update documentation
5. Test locally with act

💡 Tips

• Use workflow_dispatch for manual triggers
• Set fail-fast: false in test matrices
• Upload artifacts for debugging
• Monitor cache size (< 5GB recommended)

---

Questions? Check the full guide or open an issue.