DispatchOps

DispatchOps enables manual workflow execution via the GitHub Actions UI or CLI, perfect for on-demand tasks, testing, and workflows that need human judgment about timing. The workflow_dispatch trigger lets you run workflows with custom inputs whenever needed.

Use DispatchOps for research tasks, operational commands, testing workflows during development, debugging production issues, or any task that doesn’t fit a schedule or event trigger.

How Workflow Dispatch Works

Workflows with workflow_dispatch can be triggered manually rather than waiting for events like issues, pull requests, or schedules.

Basic Syntax

Add workflow_dispatch: to the on: section in your workflow frontmatter:

on:
  workflow_dispatch:

With Input Parameters

Define inputs to customize workflow behavior at runtime:

on:
  workflow_dispatch:
    inputs:
      topic:
        description: 'Research topic'
        required: true
        type: string
      priority:
        description: 'Task priority'
        required: false
        type: choice
        options:
          - low
          - medium
          - high
        default: medium
      deploy_target:
        description: 'Deployment environment'
        required: false
        type: environment
        default: staging

Supported input types: string (text), boolean (checkbox), choice (dropdown), environment (GitHub environments dropdown).

Environment Input Type

The environment type auto-populates from repository Settings → Environments, returning the selected name as a string. No options list is needed; specify a default matching an existing environment name. The type does not enforce protection rules — use manual-approval: for approval gates (see Environment Approval Gates).

Security Model

Permission Requirements

Manual workflow execution respects the same security model as other triggers:

• Repository permissions - User must have write access or higher to trigger workflows
• Role-based access - Use the roles: field to restrict who can run workflows:

on:
  workflow_dispatch:
roles: [admin, maintainer]

• Bot authorization - Use the bots: field to allow specific bot accounts:

on:
  workflow_dispatch:
bots: ["dependabot[bot]", "github-actions[bot]"]

Fork Protection

Unlike issue/PR triggers, workflow_dispatch only executes in the repository where it’s defined-forks cannot trigger workflows in the parent repository. This provides inherent protection against fork-based attacks.

Environment Approval Gates

Require manual approval before execution using GitHub environment protection rules:

on:
  workflow_dispatch:
manual-approval: production

Configure approval rules, required reviewers, and wait timers in repository Settings → Environments. See GitHub’s environment documentation for setup details.

Running Workflows from GitHub.com

Via Actions Tab

Go to the Actions tab, select the workflow from the sidebar, click Run workflow, fill in any inputs, and confirm. Only workflows with workflow_dispatch: in their on: section appear in the dropdown — if yours is missing, verify it has been compiled and the .lock.yml pushed to the repository.

Running Workflows with CLI

The gh aw run command provides a faster way to trigger workflows from the command line.

Basic Usage

gh aw run workflow

This matches workflows by filename prefix, validates workflow_dispatch:, and returns the run URL immediately.

With Input Parameters

Pass inputs using the --raw-field or -f flag in key=value format:

gh aw run research --raw-field topic="quantum computing"

gh aw run scout \
  --raw-field topic="AI safety research" \
  --raw-field priority=high

Wait for Completion

Monitor workflow execution and wait for results:

gh aw run research --raw-field topic="AI agents" --wait

--wait monitors progress in real-time and exits with a success/failure code on completion.

Additional Options

gh aw run research --ref feature-branch              # Run from specific branch
gh aw run workflow --repo owner/repository           # Run in another repository
gh aw run research --raw-field topic="AI" --verbose  # Verbose output

Declaring and Referencing Inputs

Referencing Inputs in Markdown

Access input values using GitHub Actions expression syntax:

---
on:
  workflow_dispatch:
    inputs:
      topic:
        description: 'Research topic'
        required: true
        type: string
      depth:
        description: 'Analysis depth'
        type: choice
        options:
          - brief
          - detailed
        default: brief
permissions:
  contents: read
safe-outputs:
  create-discussion:
---

# Research Assistant

Research the following topic: "${{ github.event.inputs.topic }}"

Analysis depth requested: ${{ github.event.inputs.depth }}

Provide a ${{ github.event.inputs.depth }} analysis with key findings and recommendations.

Reference inputs with ${{ github.event.inputs.INPUT_NAME }}—values are interpolated at compile time throughout the workflow.

Conditional Logic Based on Inputs

Use Handlebars conditionals to change behavior based on input values:

{{#if (eq github.event.inputs.include_code "true")}}
Include actual code snippets in your analysis.
{{else}}
Describe code patterns without including actual code.
{{/if}}

{{#if (eq github.event.inputs.priority "high")}}
URGENT: Prioritize speed over completeness.
{{/if}}

Development Pattern: Branch Testing

Testing Workflow Changes

Add workflow_dispatch: to feature branches for testing before merging. Use trial mode for isolated testing without affecting the production repository, or run from a branch directly:

gh aw trial ./research.md --raw-field topic="test query"  # isolated, no side effects
gh aw run research --ref feature/improve-workflow          # runs against live repo

Common Use Cases

On-demand research: Add a topic string input and trigger with gh aw run research --raw-field topic="AI safety" when needed.

Manual operations: Use a choice input with predefined operations (cleanup, sync, audit) to execute specific tasks on demand.

Testing and debugging: Add workflow_dispatch to event-triggered workflows (issues, PRs) with optional test URL inputs to test without creating real events.

Scheduled workflow testing: Combine schedule with workflow_dispatch to test scheduled workflows immediately rather than waiting for the cron schedule.

Troubleshooting

Workflow not listed in GitHub UI: Verify workflow_dispatch: exists in the on: section, compile the workflow (gh aw compile workflow), and push both .md and .lock.yml files. The Actions page may need a refresh.

“Workflow not found” error: Use the filename without .md extension (research not research.md). Ensure the workflow exists in .github/workflows/ and has been compiled.

“Workflow cannot be run” error: Add workflow_dispatch: to the on: section, recompile, and verify the .lock.yml includes the trigger before pushing.

Permission denied: Verify write access to the repository and check the roles: field in workflow frontmatter. For organization repos, confirm your org role.

Inputs not appearing: Check YAML syntax and indentation (2 spaces) in workflow_dispatch.inputs. Ensure input types are valid (string, boolean, choice, environment), then recompile and push.

Wrong branch context: Specify the branch explicitly with --ref branch-name in CLI or select the correct branch in the GitHub UI dropdown before running.

Related Documentation

• Manual Workflows Example - Example manual workflows
• Triggers Reference - Complete trigger syntax including workflow_dispatch
• TrialOps - Testing workflows in isolation
• CLI Commands - Complete gh aw run command reference
• Templating - Using expressions and conditionals
• Security Best Practices - Securing workflow execution
• Quick Start - Getting started with agentic workflows