3.1.1. Reusable Components and Organization Templates
💡 First Principle: Centralizing automation means choosing where the definition lives and when consumers bind to it — a starter workflow binds at creation and drifts freely afterward, while a reusable workflow binds at every run, so updates propagate instantly.
The organization's .github repository is the distribution point for starter workflows (formerly "workflow templates"). Two files per template live in a workflow-templates directory: the workflow YAML itself and a matching .properties.json describing its name, description, categories, and which file types it suits. Members of the organization then see it in the "New workflow" chooser. Placeholders like $default-branch and $protected-branches are substituted at creation time, which is how one template adapts to repositories with different branch names.
Reusable workflows are the other half. They live in any repository's .github/workflows/ directory, declare on: workflow_call (as in 2.1.3), and are invoked by SHA, tag, or branch — uses: my-org/ci@v2. Because the consumer resolves that reference at run time, publishing v2.1 of a central pipeline updates every caller pinned to v2 at once. That is either exactly what you want (security patches everywhere immediately) or exactly what you fear (an untested change everywhere immediately), which is why versioning discipline (5.3.2) matters as much for workflows as for actions.
Access follows repository visibility, with one enterprise-specific nuance worth memorizing: a private repository's reusable workflows and actions can be shared with other repositories in the organization or enterprise by enabling Access settings on that repository (Settings → Actions → General → Access), and internal repositories are visible to the whole enterprise by default. Without that, uses: against a private repository fails to resolve — the classic "works for me, 404 for everyone else" scenario.
⚠️ Exam Trap: Starter workflows must live in the organization's .github repository, in a top-level workflow-templates folder, with a companion .properties.json. Missing the properties file or nesting the folder elsewhere means the template never appears in the chooser — and no error is raised anywhere.
Reflection Question: Your platform team ships a security fix to the shared build pipeline. Explain, in terms of binding time, why every consumer of the reusable workflow gets it automatically while every repository created from the starter workflow does not.
