Manual Inputs (workflow_dispatch)

~9 min · dispatch, inputs, manual

Level 0Apprentice

0 XP0/101 lessons0/10 achievements

0/120 XP to next level120 XP to go0% complete

Run-on-demand pipelines

workflow_dispatch exposes a 'Run workflow' button in the Actions UI (plus gh workflow run from CLI and the API). It's the right trigger for ad-hoc work: manual deploys, one-off backfills, debug sessions.

Typed inputs

string (default).
boolean — UI shows a checkbox.
number.
choice — dropdown with options:.
environment — dropdown of repo environments.

Triggering from CLI

gh workflow run deploy.yml -f env=production -f version=v1.4.2

Why this beats SSHing into the runner

Audit log — every dispatch is recorded.
Auth — runs as the dispatching user, secrets and permissions apply.
Reproducible — the YAML is the script.
Visible — anyone can see what's running and what was run.

Code

workflow_dispatch with rich inputs·yaml

name: deploy
on:
  workflow_dispatch:
    inputs:
      env:
        type: environment
        required: true
      version:
        type: string
        required: true
        description: 'Semver tag like v1.4.2'
      dry-run:
        type: boolean
        default: true
      force:
        type: choice
        default: 'no'
        options: ['no', 'yes-i-really-mean-it']

jobs:
  deploy:
    runs-on: ubuntu-latest
    environment: ${{ inputs.env }}
    steps:
      - run: |
          echo "Deploying ${{ inputs.version }} to ${{ inputs.env }}"
          if ${{ inputs.dry-run }}; then echo 'DRY RUN'; fi
          if [[ "${{ inputs.force }}" == 'yes-i-really-mean-it' ]]; then echo 'FORCE'; fi

External links

GitHub — workflow_dispatch reference

Exercise

Pick one operational task you currently do by SSHing into a server. Re-implement it as a workflow_dispatch with typed inputs. Run it once via UI and once via gh workflow run.