GitHub Actions workflow_call Inputs: Validate Museum Preview Settings Before CI Runs

A preview setting is more than a string

A museum maintains a shared GitHub Actions workflow that builds previews for multiple digital exhibits. Teams call it with parameters such as an exhibit path, a flag to enable draft assets and a maximum number of pages to scan. Without a clear input contract, callers can supply unexpected values or rely on defaults that silently change what the preview includes. The workflow_call event supports declared reusable-workflow inputs with types boolean, number and string. That is useful for catching interface mistakes before a job runs. It is not a complete release-authorization system: even correctly typed values can designate an unapproved path or environment. Build both a typed contract and explicit rules for which preview targets are allowed.

Declare required values and intentional defaults

In the called workflow, define inputs under on.workflow_call.inputs, giving each declared input a type. GitHub requires the type field for an input declared in workflow_call. The documented options are boolean, number and string. The syntax reference says that when no default is specified, booleans default to false, numbers to 0 and strings to an empty string. Those silent defaults may be inappropriate for a museum release workflow. Mark essential exhibit IDs as required and specify meaningful defaults only for noncritical options. For example, a preview-only flag should never be interpreted as authorization to deploy to production. Review which input values could alter the public-site destination.

Keep caller values in the correct types

A caller passes named inputs through the with block of a job that invokes the reusable workflow. The value types must match the declared interface. Use boolean true or false for a boolean input rather than assuming the string “false” will behave identically in every expression or shell command. Use a number for a bounded scan count, but perform a separate range check because the type alone does not prevent a value such as 100000. For paths and environment names, compare a string against an explicit allowlist. GitHub rejects an input that the called workflow did not declare, which helps catch spelling errors, but cannot determine whether a valid value is safe.

Make one contract the source of truth

Document the reusable workflow’s inputs next to its YAML file with descriptions, examples and rules for version changes. A compact contract for the example might include exhibit_id as required string, include_drafts as boolean with false default, and max_pages as number with a documented upper bound. The called workflow should log validated nonsecret configuration after parsing while avoiding the disclosure of private paths or tokens. Callers should pin the reusable workflow to an approved reference and submit contract changes through review, rather than relying on a mutable interface that can change overnight. Treat inputs, secrets and job permissions as different security concepts: an input value cannot grant credentials by itself.

Compare omitted, incorrect and approved inputs

An illustrative first state shows the caller leaving out an optional flag, so the documented default applies. That can be safe, but it should be visible in the preview manifest. The second state shows a wrong-type or undeclared input that the workflow interface rejects instead of guessing what it means. The third state shows values matching the types, a recognized exhibit target and a separate approval gate before publication. These states are hypothetical examples, not screenshots from GitHub. The distinction matters because a typed value is necessary for a dependable interface but not sufficient to authorize a change. The diagram should not imply that passing type checks alone protects production credentials.

Validate targets before touching build outputs

At job start, validate exhibit_id against a known set of repository directories and reject relative traversal, external URLs or unauthorized deployment names. Check that max_pages stays within a deliberately chosen operational bound. If include_drafts is true, ensure the output remains on a private review destination and cannot be uploaded as a public artifact. Fail clearly when the caller omitted a required value or supplied an unsupported combination. A separate environment protection rule can require review for production deployment; this article focuses on the input contract rather than replacing that protection. Keep build artifacts named with trusted IDs generated after validation, not arbitrary unsanitized user input.

Test caller mistakes in a nonproduction repository

Create a fixture caller for the reusable workflow and exercise four cases: a valid preview request, a missing required exhibit ID, a wrong-type boolean value and an allowed type with an invalid exhibit path. Check which failures are rejected by GitHub’s workflow syntax and which are rejected by the explicit validation step. Add a deliberately large number to verify bounds checking. Do not claim that all malformed YAML reaches the runner; some invalid calls fail before job execution. Collect the workflow’s error messages and ensure they tell maintainers how to correct the input without echoing any secret. These proposed tests can run without publishing or deploying a museum site.

Preserve least privilege across the call boundary

Reusable workflows can receive named secrets, and GitHub also documents mechanisms for inheriting secrets in supported contexts. That is separate from typing ordinary inputs. A correctly typed exhibit ID should never cause the job to receive broader credentials than the preview needs. Configure permissions, secret passing and environments explicitly. If the reusable workflow is also used for production, put protected release steps behind a stronger authorization boundary instead of a single boolean flag. Verify that a pull request from an untrusted contributor cannot use its input values to move output into a privileged destination. Review artifacts for hidden configuration files or accidental token disclosure before sharing a preview.

Release with a visible contract and reviewer gate

A maintainer should be able to identify the called workflow version, the declared input types, resolved nonsecret values, target validation result and any required review before publication. A build can be green and still be pointed at the wrong exhibit if its paths were not checked. After changing the contract, test existing callers and document any input that has been renamed or given a new default. Keep preview links distinct from production URLs and require human approval for a public release. The useful outcome is an interface that rejects accidental values early while making authorization decisions explicit. Type checking reduces configuration ambiguity; it cannot substitute for permissions, content review or deploy controls.

Related guides

• GitHub Actions workflow_dispatch Inputs: Require a Reviewed Museum Catalog Export
• GitHub Actions Reusable Workflows: Standardize Museum Site Checks Without Sharing Secrets
• GitHub Actions GITHUB_WORKFLOW_SHA: Prove Which Caption-QA Workflow Ran
• GitHub Actions sparse-checkout: Build Museum Previews Without Silently Missing Assets

How We Research

For this guide we consulted the official documentation: GitHub Actions workflow syntax; Reuse workflows. We compared named fields, supported behaviors and stated limitations, then developed an instructional museum scenario with explicit failure states. We did not run a live vendor API benchmark, inspect a production museum system, or measure vendor performance. The workflow and illustrations are proposed review steps; verify API-version support and your organization’s current policy before applying them.

Frequently Asked Questions