English for GitHub Actions Reusable Workflows

Duplicating the same CI steps across a dozen repositories eventually becomes unmaintainable, and reusable workflows exist specifically to solve that — this vocabulary lets you discuss the mechanism precisely instead of calling everything “a shared pipeline.”

Key Vocabulary

Reusable workflow — a workflow file defined with a workflow_call trigger, designed to be invoked from other workflows rather than run directly, letting teams centralize CI logic instead of copy-pasting it into every repository. “Instead of maintaining nearly identical deploy steps in fifteen repos, we moved the logic into one reusable workflow — now every repo just calls it, and a fix in one place applies everywhere.”

Workflow_call trigger — the specific trigger type that makes a workflow callable by other workflows, defining the inputs, secrets, and outputs it accepts, distinct from triggers like push or pull_request that respond to repository events directly. “That workflow can’t be called from another one yet — it only has a push trigger. It needs a workflow_call trigger added, with the inputs and secrets it should accept explicitly declared.”

Input — a typed parameter declared by a reusable workflow and passed in by the calling workflow, letting the same shared logic behave differently depending on context, like which environment to deploy to. “We don’t need two nearly identical reusable workflows for staging and production — add an environment input to the one we have, and let the calling workflow pass in which target it needs.”

Secrets inheritance — the secrets: inherit setting that passes all of the calling workflow’s secrets down to the reusable workflow automatically, instead of requiring each secret to be listed and passed individually. “We were getting an ‘undefined secret’ error because the calling workflow wasn’t using secrets inheritance — it was passing secrets individually and missed one that the reusable workflow actually needs.”

Composite action — a different reusability mechanism that packages a sequence of steps into a single reusable step, referenced with uses: inside a job, better suited for a small set of steps than for an entire job or pipeline. “For just these three setup steps, a composite action is a better fit than a full reusable workflow — reusable workflows are meant for reusing whole jobs, not a handful of steps inside one.”

Common Phrases

• “Should this be a reusable workflow, or is a composite action a better fit for this size?”
• “Does this workflow have a workflow_call trigger, or only an event trigger?”
• “Should this vary by an input, or does it need a separate reusable workflow entirely?”
• “Are we using secrets inheritance here, or passing secrets individually?”
• “Is this reused across repos, or just across jobs in the same repo?”

Example Sentences

Proposing a refactor in a team discussion: “We have the same eight-step deploy sequence duplicated across twelve repositories right now. I’d like to extract it into a reusable workflow with a workflow_call trigger, so each repo just calls it with an environment input instead of maintaining its own copy.”

Debugging a secrets issue: “The build is failing because the reusable workflow can’t find NPM_TOKEN — the calling workflow is passing secrets individually and missed it. Switching to secrets: inherit would avoid this class of bug going forward.”

Explaining a design choice: “We used a composite action for the checkout-and-setup steps, not a full reusable workflow, because it’s only three steps shared within jobs of the same repo — a reusable workflow would be the right call if we needed to share this across separate repositories.”

Professional Tips

• Reach for a reusable workflow specifically when the same job-level logic is duplicated across multiple repositories — for steps shared only within one repo, a composite action is usually simpler.
• Declare the workflow_call trigger’s inputs and secrets explicitly and document what each one controls — an unclear reusable workflow interface defeats the purpose of centralizing the logic in the first place.
• Prefer an input to duplicating an entire reusable workflow for a minor variation, like environment or version — duplicating the workflow itself reintroduces the maintenance burden it was meant to remove.
• Default to secrets inheritance unless there’s a specific reason to restrict which secrets a reusable workflow can access — passing secrets individually is more explicit but is also a common source of “undefined secret” failures when a new one is added later.
• Use a composite action, not a reusable workflow, for a small set of steps reused within jobs of the same repository — matching the tool to the actual scope of duplication avoids unnecessary complexity.

Practice Exercise

1. Explain the difference between a reusable workflow and a composite action.
2. Describe what the workflow_call trigger does and why it’s necessary.
3. Write a sentence explaining what secrets inheritance does and when you might choose not to use it.