zero gravitySOLUTIONS
← All insightsCI/CD & DELIVERY / WORKFLOW CONTRACT GUIDE

Reusable workflows with a clear contract

QUICK ANSWER

A reusable workflow is a delivery API. Give it a narrow purpose, typed inputs, documented outputs, and the least authority required for that purpose. Version its behavior deliberately and test representative callers before changing shared execution.

Inside this article 5 sections

A reusable GitHub Actions workflow is an interface that other repositories depend on. Changing a default, output name, permission, or runner can break callers even when the YAML still parses. Treat the workflow like a small internal API with a defined purpose and a controlled upgrade path.

Begin with one capability, such as checking a Node application or publishing an already-built image. A single workflow that builds, provisions infrastructure, deploys, migrates data, and comments on pull requests accumulates unrelated authority. Smaller contracts let teams reuse common behavior without giving every caller the same powers.

Define inputs in business terms

Use typed inputs for decisions the caller legitimately owns: application name, runtime version, or whether an optional report is required. Avoid accepting an arbitrary shell command merely to make the workflow flexible. That transfers execution policy to the caller and makes the shared workflow difficult to review.

Validate values even when the type is correct. A string input can still contain an unsupported application identifier or an unsafe path. Prefer a small allowlist or a repository-owned mapping from application name to command and directory. Document required inputs, defaults, and the meaning of an omitted value.

name: Validate application selection
on:
  workflow_call:
    inputs:
      application:
        required: true
        type: string
permissions:
  contents: read
jobs:
  validate:
    runs-on: ubuntu-latest
    steps:
      - name: Check supported application
        env:
          APPLICATION: ${{ inputs.application }}
        run: |
          case "$APPLICATION" in
            portal|worker) ;;
            *) exit 1 ;;
          esac

This complete validation-only example demonstrates the input boundary; it does not build or deploy either application. The input reaches the shell through a quoted environment variable rather than being interpolated directly into script source. A production workflow should add the explicit repository-owned behavior after validation.

Make authority part of the interface

Reusable workflow contract review
Contract elementCaller responsibilityWorkflow responsibility
InputsSelect a supported application and modeValidate values and reject unsupported combinations
Token permissionsGrant the declared minimumAvoid hidden write or deployment requirements
SecretsPass explicitly authorized credentialsUse only for the documented operation
OutputsInterpret success and identifiers correctlyReturn stable, non-secret result fields
RevisionChoose a reviewed workflow versionPreserve or deliberately migrate its behavior
Reuse does not remove ownership. Each side must know what the workflow accepts, returns, and is permitted to do.

Set token permissions explicitly at the appropriate scope. A verification workflow normally needs much less authority than a release workflow. Called workflows cannot elevate permissions beyond the caller's allowed chain, so test permission requirements from a realistic caller rather than only running the shared file in isolation.

Prefer named secret mappings over indiscriminate inheritance when only a few values are needed. A secret being available does not mean it belongs in every step. Keep cloud authentication, package publication, and repository mutation in separate jobs where their authority can be reviewed independently.

Environment protections need deliberate placement. A reusable workflow that declares a deployment environment may use that environment's secrets and protection rules. Document which repository owns the environment and verify the effective behavior in the supported calling arrangement. Do not assume caller-level environment configuration is automatically forwarded as an ordinary input.

Return evidence that callers can use

Useful outputs identify immutable results: artifact digest, test report identifier, or deployment revision. Avoid returning a vague success string when job status already communicates success. If a workflow produces an artifact, state which checks were performed and whether the output exists after partial failure.

Map step outputs to job outputs and then to workflow outputs explicitly. Test empty values and skipped optional jobs. A caller that interprets an empty digest as “use latest” can accidentally deploy a different artifact. Missing required evidence should be a visible failure, not a permissive fallback.

Keep secrets and sensitive payloads out of outputs. Outputs often travel into logs, summaries, or downstream jobs with a different audience. Use references to protected resources rather than embedding credentials or complete customer fixtures in the workflow interface.

Pin implementation and review upgrades

For cross-repository reuse, reference a reviewed full commit SHA when immutable behavior is required. Resolve that SHA from the actual repository and verify the intended release; do not invent a hash or assume a movable tag provides the same guarantee. A same-repository relative workflow reference follows the calling commit and has a different update model.

Publish behavior changes with migration notes. Changing the default runtime, artifact naming, or required permission is an interface change even if the input schema is unchanged. Keep representative caller fixtures that cover the simplest app, a monorepo app, optional outputs, and a caller with only the documented minimum permissions.

Run those fixtures against the proposed workflow revision before updating callers. Include an unsupported input and missing required secret to verify clear failure. Static YAML validation checks structure, but only a GitHub test run can verify expression evaluation, permissions, runner behavior, and access to referenced workflows.

Document cancellation and timeout behavior as part of the contract. A caller needs to know whether canceling a verification run simply discards work or can interrupt a stateful release operation. Keep deployment serialization and cancellation separate from ordinary test-run optimization, and return enough evidence to identify an interrupted operation.

Roll out shared changes in small groups

Upgrade a few representative repositories first, inspect resulting evidence, and then expand. Keep the previous revision available for rollback. Track which callers remain on older versions so retiring an interface does not depend on memory or a broad search performed during an incident.

The API versioning guide offers the same compatibility discipline, while delivery acceptance guidance explains what evidence a completed change needs. Software implementation should make shared automation a dependable capability rather than a central file that every team is afraid to edit.

FROM INSIGHT TO ACTIONCustom software development

Make delivery reuse predictable.

We can implement reusable workflows, representative caller tests, and controlled version upgrades across your applications.

Explore software developmentDiscuss your build

Start with your goals.
We’ll work through the next step together.