A Run Button Is Not a Publication Decision
A museum maintains a collection catalog in a private repository and wants an operator to export a reviewed subset for a public website. A hurried manual workflow might accept a single free-text argument and run an upload step immediately. If that text names a private collection or malformed destination, the system may publish data that has not been cleared for release. The problem is a missing governance boundary, not a missing button.
GitHub Actions supports workflow_dispatch, a manually triggered event with optional inputs. A careful design separates the choice of what to export, validation of those inputs, a dry-run artifact and an explicit approval stage. This fictional catalog project uses invented accession IDs and labels; the diagrams are not copied from GitHub’s UI or evidence of a real workflow execution.
Define the Manual Trigger on the Default Branch
GitHub documents that the workflow must exist on the default branch for workflow_dispatch events to be received. Authorized users can trigger it through the Actions interface, GitHub CLI or REST API; manual execution requires the appropriate repository permissions. Put the workflow definition through normal code review rather than relying on a one-time script pasted into the web interface.
Name the event’s inputs to express intent. A collection key should identify a published-eligible dataset, not allow an arbitrary shell path. A target can be a choice of staging or preview when possible. An optional dry_run boolean should default to a nonpublishing mode. Avoid mixing review state with an operator-entered word such as approved; that string is not an independent sign-off.
Prefer Types and Preserve Boolean Meaning
The workflow_dispatch definition supports input types including boolean, choice, number, string and environment. GitHub explains that the inputs context preserves boolean values as booleans, whereas github.event.inputs converts them to strings. A condition that compares a string to a boolean can therefore make a guard behave unexpectedly. Use the documented inputs context and test both true and false branches.
Choice inputs resolve to strings, so still validate their meaning against the workflow’s allowlist. Number inputs remain bounded by the application’s own policy; their type alone does not establish sensible batch size. GitHub documentation currently describes a limit of 25 top-level input properties and a 65,535-character payload, but these are transport limits, not design targets. Prefer a small auditable input set.
Keep Inputs Out of the Shell Interpreter
A manually entered input is still user-supplied data. Never interpolate arbitrary strings directly into a shell command where quoting errors or special characters could change execution. Validate the identifier against a strict server-side allowlist and pass safe values through environment variables or other controlled interfaces. Use dedicated permissions for reading catalog data and a separate, protected job for public publication.
Keep API credentials out of input fields, logs and job summaries. Restrict the workflow token permissions to the steps that need them; do not grant broad write access merely because an operator has permission to start a run. If a collection is not eligible for export, fail before building an artifact. An invalid input should produce a readable failure with a correlation ID, not an empty export that looks successful.
Compare Unchecked, Validated and Approved Runs
In the initial visual state, an arbitrary collection string goes straight to an export command. The intermediate state verifies typed inputs and creates a staging package but still awaits approval. The final state makes a separate, logged release decision that refers to the precise source revision and artifact. These panels illustrate a proposed release protocol, not screenshots of a real GitHub repository.
A common edge case involves a boolean dry_run. If the operator selects false, that only requests a different behavior; it must not by itself satisfy environment review, rights approval or policy conditions. Likewise, setting an environment input is not equivalent to proving the repository has configured environment protection. Tie the deploy job to actual required reviewers and permissions where those controls apply.
Attach Provenance to the Export Artifact
The preview artifact should include source commit, selection criteria, review timestamp, export tool revision and a manifest of eligible records. Compare the record counts and IDs with the approved catalog subset. If the source changes while the job is awaiting approval, decide whether to rebuild rather than publishing the old preview with a new status label. Keep sensitive rows out of public logs and screenshots.
Use representative fake records for workflow testing. Include empty selections, missing permissions, wrong environment choices, unexpected Boolean values and a dataset containing a private entry. Test that each case is blocked before publication. Do not claim that a successful build or checksum proves copyright clearance, consent or correctness of collection metadata. Those require separate review.
Make Approval Independent of the Trigger
A named curator or collections manager should approve the exact release scope, not merely the fact that someone clicked Run workflow. A deployment environment or another protected release mechanism can provide a second gate. Document what each gate checks: technical package integrity, collection visibility policy, rights restrictions and the intended publishing destination. Keep a clear rollback path.
If an approval is missing, leave the artifact in staging. Treat canceled jobs, retries and partially completed uploads as distinct states. A human-triggered workflow can improve reproducibility and accountability, but it cannot replace the underlying access and editorial rules. The operator should see a useful explanation of what has been checked and what remains pending before any public update.
Release Only the Reviewed Selection
An acceptable handoff contains validated typed inputs, an approved collection allowlist, least-privilege execution, a stable source revision, staged preview and a separate release approval. The final run should record who authorized it and which archive object IDs were included. If the log cannot tie a public export to its approved source, the process is not yet ready for unattended publication.
The most important distinction is between selecting a job configuration and authorizing a public action. workflow_dispatch solves the former. A well-designed repository workflow surrounds it with checks that preserve the latter, so the museum can operate efficiently without turning a convenient input form into an accidental publishing back door.
How We Research
We consulted the following official developer documentation on November 8, 2026: GitHub Docs: Events that trigger workflows; GitHub Docs: Manually running a workflow; GitHub Docs: Contexts reference. We compared the documented parameters, data flow and stated limitations with this hypothetical editorial scenario. The diagrams are original instructional illustrations, not real vendor screenshots or outputs. We did not submit private archive material, run a production API evaluation, measure tool accuracy, obtain legal consent, or test a live service configuration. Product behavior, access rules, quotas and supported settings may change; confirm the latest documentation and your organization’s policies before deployment.
Frequently Asked Questions
GitHub documents that the workflow file must be on the default branch to receive the manual trigger.
The inputs context preserves booleans; github.event.inputs represents supplied values as strings.
No. Choices constrain selection; permission checks and release approval remain independent.
Avoid it. Use a protected secret store with least-privilege job permissions instead of logging credentials as arguments.
No. It is only a requested mode. A separate review gate should protect public exports.