hana-developer-cli-tool-example github-workflow-maintenance.instructions.md

GitHub Workflow Maintenance Guidelines

Use this guide when creating or modifying GitHub Actions workflow files in .github/workflows/.

Scope and Purpose

This guide applies to GitHub Actions workflow configuration:

• CI/CD pipelines for testing and building
• Documentation deployment workflows
• Release automation
• Scheduled maintenance tasks
• Pull request checks
• Package publishing workflows

Critical Principles

1. Matrix Testing: Use matrix strategy for testing across multiple environments
2. Dependency Caching: Cache npm dependencies to speed up builds
3. Artifact Management: Properly upload and download build artifacts
4. Secret Security: Never expose secrets in logs or outputs
5. Job Dependencies: Clearly specify job dependencies with needs
6. Fail Fast: Use fail-fast: false for comprehensive testing
7. Descriptive Names: Use clear, descriptive names for workflows and jobs
8. Idempotency: Jobs should be repeatable and produce consistent results

Workflow Structure Template

name: Descriptive Workflow Name

# Trigger configuration
on:
  push:
    branches: [main, develop]
    paths:
      - 'src/**'
      - 'package.json'
  pull_request:
    branches: [main]
  workflow_dispatch:  # Manual trigger
  schedule:
    - cron: '0 0 * * 0'  # Weekly on Sunday

# Environment variables
env:
  NODE_VERSION: '20'
  NPM_CONFIG_LOGLEVEL: 'error'

# Workflow permissions
permissions:
  contents: read
  packages: write

jobs:
  # Job definitions
  test:
    name: Test on Node ${{ matrix.node-version }}
    runs-on: ${{ matrix.os }}
    
    strategy:
      fail-fast: false
      matrix:
        os: [ubuntu-latest, windows-latest, macos-latest]
        node-version: [18, 20]
    
    steps:
      # Step definitions
      - uses: actions/checkout@v4
      - name: Setup Node.js
        uses: actions/setup-node@v4
        with:
          node-version: ${{ matrix.node-version }}
          cache: 'npm'
      
      - name: Install dependencies
        run: npm ci
      
      - name: Run tests
        run: npm test