feat: reusable workflows as default ci-cd

Author: sheplu

docs/rfc/0001-reusable-workflows.md

@@ -0,0 +1,108 @@
+# Adopting shared & reusable GitHub Actions for default CI/CD pipelines
+
+## Summary
+
+This RFC proposes that all default CI/CD workflows across the Express.js organization should be built using shared, reusable GitHub Actions rather than defining separate workflows in each repository. These workflows will be centrally maintained, versioned, and consumed by individual repositories to ensure consistency, reliability, and easier maintenance.
+
+## Motivation
+
+Currently, each repository in the Express.js organization maintains its own GitHub Actions workflows. This leads to:
+
+- Inconsistent CI/CD practices (different Node versions, test commands, caching, verification steps, etc.)
+- Duplicated effort across repositories
+- Increased probability of misconfiguration or security vulnerabilities
+- Difficulty onboarding new contributors and maintainers
+- Harder organization-wide upgrades (e.g., Node.js version updates or introducing new security validations)
+
+By moving to shared reusable workflows, we expect to:
+
+- Ensure consistent build, test, and release standards across all repositories
+- Reduce maintenance overhead and simplify updates
+- Improve security by enforcing centralized best practices
+- Enable shared improvements for all repositories (e.g., adding `npm audit`, code coverage, publishing automation)
+- Support future capabilities such as automated dependency updates and release pipelines
+
+## Detailed Explanation
+
+### Proposal
+
+- Create and maintain centralized reusable workflows under a repository such as:
+  - `expressjs/ci-workflows`
+
+- These workflows will include:
+  - `ci.yml` — install dependencies, lint, test, build
+  - `release.yml` — publish to npm and create GitHub releases (optional approval gates)
+  - `security.yml` — package audit, CodeQL (if required)
+  - `nightly.yml` — scheduled CI runs on latest Node.js versions or branches
+
+- Each repository will consume them using `workflow_call`, for example:
+
+  ```yaml
+  name: CI
+
+  on:
+    push:
+      branches: [main]
+    pull_request:
+
+  jobs:
+    build:
+      uses: expressjs/ci-workflows/.github/workflows/ci.yml@v1
+      with:
+        node-version: 24
+  ```
+
+- Customization will still be possible using workflow inputs and conditionals.
+- Workflows will be versioned (`v1`, `v1.1`, etc.) to ensure stability.
+
+### Migration
+
+1. Create shared workflow repository and initial pipeline definitions.
+2. Document how to consume workflows, expected defaults, and available inputs.
+3. Migrate a few core repositories (`express`, `router`, `body-parser`) as a pilot.
+4. Expand adoption across the organization.
+5. Deprecate custom pipelines once migration is completed.
+
+## Rationale and Alternatives
+
+| Approach | Pros | Cons |
+|----------|------|------|
+| **Shared reusable workflows (proposed)** | Consistent CI/CD, easier maintenance, improved security, one update applies to all repos | Requires initial setup and governance |
+| **Status quo: per-repository workflows** | Maximum flexibility per repository | Inconsistent behavior, duplicated code, high maintenance, increased risk of outdated CI |
+| **Use external CI tools (Jenkins, CircleCI, etc.)** | Can be highly customizable | Adds external dependency, higher complexity, reduces transparency for contributors |
+
+This proposal offers the best balance of maintainability, consistency, and openness for the Express.js ecosystem.
+
+## Implementation
+
+### Affected Areas
+
+- All active repositories using GitHub Actions under the `expressjs/` organization.
+- No runtime code changes required; only CI configuration updates.
+
+### Actions Required
+
+- Create new repository `ci-workflows` organization repository.
+- Implement and document reusable workflows.
+- Configure organization-wide secrets (npm token, GitHub token, etc.) if required.
+- Roll out reusable workflows in prioritized repositories.
+- Establish contribution guidelines and versioning strategy for workflow updates.
+
+### Technical Considerations
+
+- Use `workflow_call` and workflow permissions properly.
+- Use only organization-level secrets, not per-repo secrets for shared steps.
+- Optional security checks (CodeQL, audit) should be configurable.
+- Release workflows should include safeguards (e.g., manual approval for npm publish).
+
+## Prior Art
+
+- GitHub officially recommends this pattern for large organizations.
+
+## Unresolved Questions and Bikeshedding
+
+- What should the shared workflow repository be named? `expressjs/.github` or something like `expressjs/ci-workflows`?
+- Should `npm` be enforced, or support `pnpm`, `npm`, `yarn`?
+- Should `npm audit` or CodeQL scanning be mandatory by default?
+- How should versions of workflows be managed — tagged releases (`v1`) or branch references (`main`)?
+- Should automatic npm releases be allowed, or manual approvals required?