GitHub Actions Workflow Not Triggering

Problem Summary

GitHub Actions silently ignores workflows that it cannot parse or that do not match the configured trigger. Unlike application errors that surface in logs, a workflow that does not trigger produces no error message it simply does not appear in the Actions tab. This makes diagnosis unintuitive: the absence of output is the signal.

Symptoms

• No workflow run appears in the repository Actions tab after pushing a commit
• No workflow run appears after opening or updating a pull request
• The workflow appears in the Actions tab but shows as 'skipped' or grey rather than running
• The workflow ran on a previous branch but does not run on the current one
• The workflow runs manually via workflow_dispatch but not automatically on push
• Required status checks block a PR merge because the expected check never ran

Cause 1: Workflow File Not on the Default Branch

If you add a new workflow file on a feature branch and push to that branch, GitHub will not run the workflow even for push events because the workflow definition does not exist on the default branch yet. Merge the workflow file to the default branch first, then it will trigger on subsequent pushes.

# Check if the workflow file exists on main
git show main:.github/workflows/ci.yml

# If this errors with "does not exist in 'main'", the file is not on main yet
# Merge or cherry-pick it to main first

# Then verify it is tracked in git (not gitignored)
git ls-files .github/workflows/

Cause 2: YAML Syntax Error (Silent Failure)

A YAML syntax error in the workflow file causes GitHub to silently discard the entire workflow with no error message in the Actions tab. The most common errors are incorrect indentation, a missing space after a colon, and tab characters where spaces are required.

# ❌ Missing space after colon  YAML parse error
name:CI

# ❌ Wrong indentation  steps must be indented under the job
jobs:
  build:
    runs-on: ubuntu-latest
steps:       # Wrong  should be indented under build
  - run: echo hello

# ✓ Correct structure
name: CI

on:
  push:
    branches: [main]

jobs:
  build:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4
      - run: echo hello

Validate your YAML before pushing

If the command exits with no output, the YAML is valid. If it throws an error, it will show the line and column of the problem. Fix the syntax error and push again.

Cause 3: Branch Filter Mismatch

If your workflow specifies a branches filter under the trigger, it will only run when a push or PR targets one of the listed branches. A push to any other branch is silently ignored.

# This workflow only triggers on pushes to main
on:
  push:
    branches:
      - main

# ❌ Pushing to develop, staging, or feature/foo does nothing

# ✓ To trigger on all branches except a specific one:
on:
  push:
    branches-ignore:
      - 'docs/**'

# ✓ To trigger on main and any release branch:
on:
  push:
    branches:
      - main
      - 'release/**'

Cause 4: Paths Filter Excluding Your Changed Files

A paths filter tells GitHub to only run the workflow if at least one of the changed files in the push matches the pattern. If every changed file in your commit is excluded by the filter, the workflow does not run.

on:
  push:
    paths:
      - 'src/**'
      - 'package.json'

# ❌ You commit only to README.md  workflow does not trigger
# ❌ You commit only to .github/workflows/ci.yml  also does not trigger

# ✓ To always run when the workflow file itself changes:
on:
  push:
    paths:
      - 'src/**'
      - 'package.json'
      - '.github/workflows/**'  # Add this

Cause 5: Wrong Event Type

If the workflow is configured with on: pull_request but you pushed directly to a branch, the workflow will not trigger. Conversely, if it is configured with on: push but you are waiting for it to run on a PR, it will not run either.

# ❌ Only triggers on PRs  direct pushes to main are ignored
on:
  pull_request:
    branches: [main]

# ✓ Trigger on both direct pushes and PRs
on:
  push:
    branches: [main]
  pull_request:
    branches: [main]

# ✓ For deployment workflows  only run after PR is merged (push to main)
on:
  push:
    branches: [main]

Diagnosis Checklist

1. 1Open the repository Actions tab if no run appears after your push, the workflow was not triggered at all (not a failing run, a non-triggering workflow)
2. 2Check the workflow file exists on the default branch: git show main:.github/workflows/your-workflow.yml
3. 3Validate the YAML syntax: npx js-yaml .github/workflows/your-workflow.yml
4. 4Verify the on: trigger matches the action you performed push vs pull_request vs workflow_dispatch
5. 5Check the branches: filter matches the branch you pushed to
6. 6Check the paths: filter at least one of your changed files must match
7. 7Check for a job-level if: condition that might be evaluating to false

Debug a Non-Triggering Workflow

The fastest way to confirm a workflow file is valid and reachable is to add workflow_dispatch to its triggers. This adds a 'Run workflow' button to the Actions tab that lets you manually trigger it without a push.

on:
  workflow_dispatch:  # Add this to test manually
  push:
    branches: [main]

jobs:
  debug:
    runs-on: ubuntu-latest
    steps:
      - name: Print trigger context
        run: |
          echo "Event: ${{ github.event_name }}"
          echo "Ref: ${{ github.ref }}"
          echo "Branch: ${{ github.ref_name }}"
          echo "Actor: ${{ github.actor }}"

If the 'Run workflow' button appears and the manual trigger works, your workflow file is valid. The problem is in the automatic trigger configuration branch filter, paths filter, or event type. If the button does not appear, the workflow file has a syntax error or is not on the default branch.