github-actions-centralized-reusable-workflows

GitHub Actions Centralized Reusable Workflows

Purpose

When the same workflow YAML — build, test, security scan, deploy — is copy-pasted across dozens of repos (github-actions-single-repo-workflows covers that per-repo pattern), a policy change (a new required scan, a registry migration) requires editing every repo individually and drifts immediately. GitHub Actions solves this at the organization level with reusable workflows (workflow_call), which let a caller workflow in any repo invoke one centrally-maintained workflow definition with inputs/ secrets, and shared composite actions hosted in a dedicated repo for smaller reusable step sequences. This skill covers designing, versioning, and rolling out that centralized pattern so many repos consume one standardized pipeline rather than diverging copies.

When to use

• More than a handful of repos have near-identical .github/workflows/*.yml files and a change requires updating each one individually.
• Standing up an organization-wide CI/CD standard (e.g. "every service repo must run this exact set of security gates before deploy") that individual teams shouldn't be able to silently drift from.
• An existing reusable workflow needs a new input/secret, or a breaking change that must be versioned so callers can opt in on their own schedule.
• Deciding whether a step sequence belongs in a per-repo composite action (see github-actions-single-repo-workflows) versus a centrally-hosted one consumed by many repos.
• Migrating from Jenkins shared libraries to GitHub Actions and wanting the equivalent centralization model — compare with jenkins-centralized-shared-library.

Prerequisites & environment

• A dedicated repository to host reusable workflows/composite actions (commonly .github at the org level for org-wide defaults, or a purpose-named repo like actions-library).
• Organization (or repo, for repo-scoped reuse) admin access to configure which repos may call reusable workflows: Organization Settings → Actions → General → "Access" for reusable workflows and actions, since by default a private reusable workflow is only callable from repos in the same organization unless explicitly opened up.
• Caller repos need permissions: granted appropriately, since a reusable workflow runs with the permissions the caller grants it, not its own hardcoded defaults.
• Secrets: either passed explicitly via secrets: inherit (simplest, but passes everything the caller has) or named individually (secrets: { DEPLOY_TOKEN: ${{ secrets.DEPLOY_TOKEN }} }, more auditable about exactly what the reusable workflow receives).
• Semantic version tags (or at minimum SHA pinning discipline) on the reusable-workflow repo so callers can pin a version rather than track @main.