---
name: github-actions-workflow-architect
description: Use when designing, optimizing, or securing GitHub Actions CI/CD workflows, caching dependencies, configuring matrix builds, and managing secrets.
---

# GitHub Actions CI/CD Workflow Architecture

## Purpose
Build fast, reliable, secure, and cost-effective GitHub Actions workflows following current DevOps and security best practices.

## Core Best Practices

### 1. Security & Principle of Least Privilege
- **Explicit Permissions:** Always declare top-level `permissions:` explicitly (e.g. `contents: read`, `pull-requests: write`). Avoid default broad permissions.
- **Pin Actions to Commit SHA:** Protect against upstream compromise by pinning third-party actions to full commit hashes:
  `uses: actions/checkout@11bd71901bbe5b1630ceea73d27597364c9af683 # v4.2.2`
- **Secrets Isolation:** Never pass secrets directly into `run:` bash strings where they can be echoed. Pass them via `env:`.

### 2. Performance & Caching Strategy
- **Dependency Caching:** Use native setup action caching (`actions/setup-node` with `cache: 'pnpm'`, `actions/setup-python` with `cache: 'pip'`).
- **Concurrency Control:** Cancel in-flight duplicate runs on new commits to the same branch:
  ```yaml
  concurrency:
    group: ${{ github.workflow }}-${{ github.ref }}
    cancel-in-progress: true
  ```
- **Matrix Builds:** Run tests across platforms (Ubuntu, Windows, macOS) and runtime versions concurrently.

### 3. Workflow Hygiene
- Set reasonable execution timeouts (`timeout-minutes: 15`).
- Use separate jobs with clear `needs:` dependency DAGs (e.g., `lint` & `typecheck` $\to$ `unit-tests` $\to$ `e2e-tests` $\to$ `deploy`).