4.2 Comparing Reusable Workflows, Composite Actions & Starter Workflows

Comparing Reusable Workflows, Composite Actions & Starter Workflows

When designing a scalable CI/CD strategy across an enterprise, modular code reuse is paramount. GitHub Actions provides three distinct architectural mechanisms for code and pipeline reuse:

1. Reusable Workflows (workflow_call): Job-level pipelines that orchestrate end-to-end multi-job processes across isolated runners.
2. Composite Actions (runs.using: 'composite'): Step-level actions that bundle multiple shell commands and action steps into a single reusable component executed on the caller's existing runner.
3. Starter Workflows (.github/workflow-templates): Organization-level workflow templates that developers copy into their repositories as boilerplate when creating new workflows in the GitHub UI.

Selecting the correct reuse mechanism requires understanding their operational boundaries, execution contexts, security models, and lifecycle maintenance characteristics.

1. Comprehensive 10-Criteria Comparison Matrix

The following comparison table highlights the precise technical differences across all ten core dimensions tested on the GH-200 exam:

---

2. Deep Dive: Composite Actions vs. Reusable Workflows

Because both Reusable Workflows and Composite Actions provide version-controlled, centralized code reuse, choosing between them is a frequent enterprise design challenge.

When to Choose a Composite Action

• Shared Setup Sequences: You need to execute 4-6 sequential steps (e.g., checkout code, setup Go/Node toolchain, restore cache, run linting) inside the same runner without paying the provisioning overhead of starting a new virtual machine.
• File System State Sharing: The steps must mutate the local workspace (e.g., compile code, generate local .env configuration) so that subsequent steps in the caller job can immediately read the files on disk.
• Action Ecosystem Distribution: You want to package your tooling to publish to the GitHub Marketplace or share across heterogeneous workflows as a modular building block.

# action.yml (Composite Action)
name: 'Setup & Authenticate Toolchain'
description: 'Configures custom enterprise build utilities'
inputs:
  api-token:
    description: 'Auth token'
    required: true

runs:
  using: 'composite'
  steps:
    - name: Download CLI
      shell: bash # MANDATORY in composite actions!
      run: curl -s https://bin.corp.internal/tool -o /usr/local/bin/tool
    - name: Authenticate
      shell: bash # MANDATORY!
      run: /usr/local/bin/tool login --token "${{ inputs.api-token }}"

When to Choose a Reusable Workflow

• Complete Multi-Job Lifecycles: The process consists of multiple discrete phases (e.g., lint -> build -> security-scan -> deploy-prod) requiring independent runner environments (such as Ubuntu for building and Windows/macOS for packaging).
• Centralized Compliance Gates: Security teams require mandatory security scanning and deployment verification that individual developers cannot modify, omit, or tamper with.
• Environment Protection Rules & Approvals: The process must deploy to protected environments (production) that require manual reviewer approvals and deployment branch restrictions.

---

3. Starter Workflows: Enterprise Scaffolding

Starter workflows reside in a special repository named .github in an organization or enterprise account under the .github/workflow-templates/ directory.

Anatomy of a Starter Workflow

A starter workflow requires two files in the .github repository:

1. The Workflow Definition File (.github/workflow-templates/nodejs-ci.yml): Contains the template YAML. Can include $default-branch placeholder tokens which GitHub replaces with the repository's default branch upon creation.
2. The Metadata Properties File (.github/workflow-templates/nodejs-ci.properties.json): Describes the template in the GitHub Actions template picker UI:

   {
     "name": "Node.js Enterprise CI",
     "description": "Standard corporate Node.js build, test, and security scan.",
     "iconName": "nodejs",
     "categories": ["Node", "CI"],
     "filePatterns": ["package.json", "tsconfig.json"]
   }
   

The Disconnected Nature of Starter Workflows

When a developer creates a new workflow from a starter template, GitHub copies the YAML file directly into their repository's .github/workflows/ directory.

[!WARNING] Once copied, there is zero ongoing connection between the starter template and the repository's workflow file. If the enterprise updates the starter template in the .github repository, existing repositories will not receive the update automatically. For managed, enforceable standards, use Reusable Workflows instead.

Non-Public .github Repositories: Template Visibility Rules

The .github repository holding your templates does not have to be public. GitHub Actions supports workflow templates from non-public .github repositories, and the repository's visibility determines who can consume the templates:

The rule is simple: a template is available to repositories whose visibility matches or is more restricted than the template repository. A public .github repository reaches everything; a private one reaches only private repositories.

[!IMPORTANT] Read access is the gate for non-public templates. If your .github repository is private or internal, users and teams must be granted Read access to it before the templates appear in their "New workflow" picker. A regulated organization that keeps its CI scaffolding private and then forgets this grant will find the template list mysteriously empty for most engineers - the templates exist, but the consumers cannot see the repository.

Two mechanics carry over regardless of visibility:

• The $default-branch placeholder is substituted with the consuming repository's real default branch name when the workflow is created, so a template does not have to hard-code main.
• The .properties.json metadata file must share the workflow file's base name. octo-organization-ci.yml pairs with octo-organization-ci.properties.json; name and description are required, while iconName, categories, and filePatterns are optional. filePatterns is a regular expression matched against files in the consuming repository's root, so a template can be surfaced only to repositories that actually contain, say, a package.json.

---

4. Disabling versus Deleting a Workflow

The blueprint asks you to contrast disabling and deleting workflows, and the exam scenario is nearly always "how do we stop this from running without losing the history?"

[!TIP] Prefer disabling for anything temporary. Disabling is reversible, leaves an auditable record, and does not touch protected-branch history. Also remember the separate, automatic case: GitHub disables scheduled workflows automatically after 60 days of repository inactivity, and the owner must re-enable them manually - a disabled workflow is not always something a human chose.

[!WARNING] Both actions can deadlock a pull request. If a branch ruleset requires the build-and-test status check and you disable or delete the workflow that produces it, open pull requests wait forever on a check that will never report. Remove the required status check from the ruleset in the same change.