highFoundationSymptom-first#workflow#triggers#branches#on-push

GitHub Actions workflow not triggered on push

Push to main does not trigger any workflow run

Likely source:availabilityconfiguration

Focused incident mode — strips away everything but this runbook.

Symptoms

  • Push to main does not trigger any workflow run
  • GitHub Actions tab shows no new run after push
  • Workflow only triggers on some branches but not others

Evidence to grab

Collect these artifacts before you change anything — they prove (or rule out) each cause.

  • Workflow trigger configuration

    cat .github/workflows/<file>.yml | grep -A20 'on:'

  • Recent push events

    gh api repos/<OWNER/REPO>/events --jq '.[] | select(.type=="PushEvent") | {id: .id, created_at: .created_at}'

Diagnostic flow

Run the steps in order, marking each claim confirmed or refuted. The evidence you gather feeds the ranked causes below.

Guided decision tree is ready.

Steps with commands, expected output, and pass/fail branches.

Ranked root causes

Evidence checklist

  • on: push: branches: [develop] but push was to main
  • branches-ignore: [main] is present in the trigger

Confirm before fixing

cat .github/workflows/<file>.yml | grep -A10 'on:' | grep -A5 branches
READ

Read branch allow/block list

Fix

sed -i 's/branches:\n\s*- develop/branches:\n - main\n - develop/' .github/workflows/<file>.yml
CHANGE

Add the missing branch to the trigger

Resolution runbook

Apply from top to bottom after the cause is confirmed. Review every command before running it — risk tags are shown on each.

1
cat .github/workflows/<file>.yml | head -30
READ

Read the on: trigger block

2
gh api repos/<OWNER/REPO>/events --jq '.[] | select(.type=="PushEvent") | {ref: .payload.ref, created: .created_at}'
READ

Check recent push events

3
git log --oneline -5
READ

Confirm what was actually pushed

Prevention

  • Use on: push: branches: [main, develop] with an explicit allow-list rather than negation patterns.
  • Add a paths-ignore: ['docs/**', '*.md'] to skip doc-only changes intentionally.
  • Test trigger logic with 'workflow_dispatch' before relying on push events.
  • Keep a CI/README that documents each workflow's trigger conditions.

Related runbooks

Same stack, same failure family — worth a skim.

Workflow YAML parse error - validation fails at startcritical

Workflow run fails immediately with 'Invalid workflow file'

GitHub ActionsFoundation3 causes
Open runbook
workflow_dispatch inputs not passed - secrets vs inputs mismatchmedium

Manually triggered workflow fails because input is empty

GitHub ActionsIntermediate2 causes
Open runbook

Commands marked READ CHANGE DESTRUCTIVE — never run DESTRUCTIVE commands against production data you cannot restore. Copy → verify → execute.