GitHub Actions Workflow Not Running: Common Issues and Solutions

GitHub Actions workflows that don't trigger can be frustrating to debug. This comprehensive guide covers the most common reasons why workflows fail to run and provides actionable solutions.

Problem Overview

When a GitHub Actions workflow doesn't execute after a push or other triggering event, it's typically due to one of these categories of issues:

• Configuration errors in your workflow file
• Branch or path restrictions that prevent execution
• Repository settings that disable workflows
• Syntax or naming problems with files or branches
• GitHub platform limitations or outages

Common Causes and Solutions

1. Incorrect Branch Configuration

The most frequent issue is mismatched branch names between your workflow configuration and your actual branch structure.

Incorrect - using 'master'

on:
  push:
    branches:
      - master  # Many new repos use 'main' instead

Correct - using 'main'

on:
  push:
    branches:
      - main    # Matches default branch name for new repositories

Solution: Check your repository's default branch name in Settings → Branches and update your workflow accordingly.

2. Workflow File Location and Naming Issues

GitHub Actions requires specific file locations and naming conventions:

WARNING

Workflow files must be placed in .github/workflows/ (exactly) - not .github/workspaces/ or other variations.

Common problems:

• Extra spaces in folder names (.github /workflows)
• Nested subfolders within workflows directory
• Files with special characters or spaces in names
• Workflow files ignored by .gitignore

Solution: Verify your directory structure:

# Correct structure
.git/
.github/
└── workflows/
    └── your-workflow.yml

# Incorrect structures
.github / workflows/  # Space before slash
.github/workspaces/   # Wrong folder name
.github/workflows/subfolder/workflow.yml  # Nested subfolder

3. Path Filter Restrictions

If your workflow uses paths filters, it will only run when changes occur in specified directories:

Restrictive paths

on:
  push:
    branches: [main]
    paths:
      - 'src/**'  # Only runs when src/ files change
      # Workflow won't run if only .github/workflows changes

Broader paths

on:
  push:
    branches: [main]
    # No paths specified - runs on any change to branch

Solution: Remove or adjust path restrictions if you want the workflow to run on all changes.

4. Branch Name Pattern Matching Issues

GitHub uses glob patterns, not regex, for branch matching:

Incorrect - using regex syntax

on:
  push:
    branches:
      - 'feature/.*'  # Period treated literally, not as wildcard

Correct - using glob syntax

on:
  push:
    branches:
      - 'feature/*'   # Asterisk acts as wildcard

Special characters in branch names (+, ?, !, *, **) may need escaping with backslashes.

5. Repository and Permission Settings

Several repository-level settings can prevent workflow execution:

• Workflows disabled in fork: Forks have workflows disabled by default
• Insufficient permissions: Check Settings → Actions → General → Workflow permissions
• Auto-disabled workflows: GitHub disables workflows after 90 days of inactivity
• Secrets mismatch: Required secrets must be defined in repository settings

Solution: Navigate to your repository's Actions settings and ensure workflows are enabled with appropriate permissions.

6. Commit Message Skipping

Workflows won't run if commit messages contain skip instructions:

DANGER

Commits containing [skip ci], [ci skip], [no ci], [skip actions], or [actions skip] will prevent workflow execution.

Solution: Check recent commit messages and remove skip instructions if unintentional.

7. GitHub Actions Outages

Sometimes the issue is on GitHub's side:

Solution: Check GitHub Status to confirm if Actions are experiencing outages.

8. Workflow File Must Exist on Target Branch

For a workflow to run on a specific branch, the workflow file must exist on that branch:

INFO

If you want a workflow to run on branch webpage, the .github/workflows/ directory and workflow file must be present on the webpage branch.

Solution: Merge your workflow file into the target branch or create it directly on that branch.

Debugging Checklist

When your workflow isn't running, follow this systematic approach:

1. Verify workflow file location: .github/workflows/ (no spaces, no subfolders)
2. Check branch names: Match your workflow configuration with actual branch names
3. Review path filters: Remove or adjust if too restrictive
4. Confirm repository settings: Ensure workflows are enabled with proper permissions
5. Inspect commit messages: Remove any skip instructions
6. Check GitHub Status: Rule out platform outages
7. Validate YAML syntax: Use a YAML validator to catch syntax errors
8. Wait a few minutes: New repositories may experience brief delays

Example Working Configuration

Here's a properly configured workflow that avoids common pitfalls:

name: Webpage Build

on:
  push:
    branches:
      - main      # Matches default branch name
      - feature/* # Uses glob pattern for feature branches
    # No path restrictions - runs on any change

jobs:
  build:
    runs-on: ubuntu-latest
    steps:
    - uses: actions/checkout@v4
    - name: Setup Node
      uses: actions/setup-node@v3
      with:
        node-version: '20'
    - name: Install dependencies
      run: |
        npm ci
        npm run predeploy
    - name: Deploy
      uses: JamesIves/github-pages-deploy-action@v4
      with:
        GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }}
        BRANCH: gh-pages
        FOLDER: build

When to Seek Further Help

If you've checked all the above and your workflow still isn't running:

1. Check workflow runs: Go to Actions tab → All workflows to see if there are any error messages
2. Review GitHub Docs: Consult the official GitHub Actions documentation
3. Community support: Ask on GitHub Community Forum or Stack Overflow with details of your configuration

By methodically checking each potential issue, you can usually identify and resolve why your GitHub Actions workflow isn't running.