160-github-actions

GitHub Actions Engineering Ruleset

Audience: engineers writing and reviewing GitHub Actions Goal: secure, fast, maintainable workflows - without over-engineering

GitHub Actions Philosophy (Core Principles)

Core Principles:

• "Security by default" - Start with zero permissions, grant only what's needed
• "Fail fast, fail clearly" - Use timeouts, clear error messages, proper exit codes
• "Cache aggressively, invalidate wisely" - Cache dependencies and artifacts, version keys properly
• "Composition over duplication" - Use reusable workflows and composite actions
• "Explicit over implicit" - Document everything, use clear naming, avoid magic
• "Performance matters" - Parallelize where possible, skip unnecessary runs, optimize caching
• "Observability is essential" - Use summaries, annotations, structured logging
• "Trust but verify" - Validate inputs, sanitize outputs, audit dependencies

Applying GitHub Actions Principles:

# BAD: Implicit, insecure, slow
on: [push]
jobs:
  build:
    runs-on: ubuntu-latest
    steps:
      - run: npm install && npm test

# GOOD: Explicit, secure, optimized
name: CI Pipeline

on:
  push:
    branches: [main]
    paths:
      - 'src/**'
      - 'package*.json'

concurrency:
  group: ${{ github.workflow }}-${{ github.ref }}
  cancel-in-progress: true

permissions: {}

jobs:
  build:
    name: Build and Test
    runs-on: ubuntu-latest
    timeout-minutes: 30
    permissions:
      contents: read
    steps:
      - uses: actions/checkout@v4

      - name: Cache dependencies
        uses: actions/cache@v4
        with:
          path: ~/.npm
          key: ${{ runner.os }}-node-${{ hashFiles('**/package-lock.json') }}

      - name: Install dependencies
        run: npm ci

      - name: Run tests
        run: npm test

Note: where your original guidance conflicted with how Actions actually works, I kept your text and added a short Note immediately under it so the doc remains complete and correct.