GitHub Actions Not Triggering on Push? 7 Things to Check

If you pushed a commit successfully but GitHub Actions did not create a new
workflow run, check the workflow trigger conditions before debugging your
application code.

A red workflow run means the trigger worked and a job failed. If there is no
run at all, the likely causes are the workflow file location, branch or path
filters, a skip directive in the commit message, a disabled workflow, or the
way the push was created.

First, confirm whether the run is missing or failed

Open the repository’s Actions tab and select the workflow. If a run exists
for the commit you just pushed, the event trigger worked. Open the failed job
and step to inspect its logs.

If the run summary shows an event, branch, status, and job graph, you are
dealing with a job result rather than a missing trigger. A successful run needs
no trigger fix; a failed run needs log-based troubleshooting.

If there is no new run, use this table to choose the first place to look.

What you see	Check first
The workflow is missing from the list	File location and YAML syntax
The workflow exists, but there is no new run	on, branches, paths, and the commit message
The workflow is disabled	Enable workflow in the Actions tab
A run exists and failed	The failed job logs and required secrets

GitHub’s
workflow troubleshooting guide
also separates trigger problems from failures that happen after a run starts.

Collect the local facts in one minute

Before changing the workflow by guesswork, run these commands from the
repository root:

git status -sb
git branch --show-current
git log -1 --format="%h %s"
git show --name-only --format="" HEAD
git remote get-url --push origin

Read the output against the workflow configuration:

Local result	Compare it with
Current branch	on.push.branches or branches-ignore
Files changed in the latest commit	paths or paths-ignore
Latest commit message	Skip directives such as [skip ci]
Push remote URL	The GitHub repository you are viewing

Redact private repository names, remote URLs, email addresses, and other
sensitive details before sharing the output or a screenshot. These commands
only read local Git information; they do not start a workflow or change the
remote repository.

1. Check the workflow file location

GitHub Actions only discovers workflow files with a .yml or .yaml
extension inside the repository’s .github/workflows/ directory.

A file in another directory will not be treated as a workflow. A common typo
is using the singular directory name .github/workflow.

This is a valid layout:

.github/
└─ workflows/
   └─ validate.yml

If the location is correct, compare the YAML indentation and the on, jobs,
and steps structure with the official
GitHub Actions workflow syntax.
Start here when the workflow itself does not appear in the Actions tab.

When you configure only some events, remember to include a colon after every
event name. This is a minimal workflow that supports both manual runs and
pushes to main:

on:
  workflow_dispatch:
  push:
    branches:
      - main

2. Check the branch you actually pushed

The following workflow runs only when a commit is pushed to main:

on:
  push:
    branches:
      - main

If your local branch is feature/test, the push can succeed without starting
this workflow. Check the active branch, latest commit, and configured remotes:

git branch --show-current
git log -1 --oneline
git remote -v

If git status says Your branch is ahead, you may have committed locally
without pushing that commit to the remote repository. Compare the current
branch with the workflow’s branch filter before creating empty commits or
repeating the push.

3. Evaluate branch and path filters together

The following workflow requires both conditions to match:

on:
  push:
    branches:
      - main
    paths:
      - "content/drafts/**/*.md"

A push to main that changes only README.md will not trigger the workflow.
A change to content/drafts/post.md pushed to a different branch will not
trigger it either.

GitHub’s
workflow filter syntax
states that when branch and path filters are both present, both filters must
match.

With paths-ignore, a push to main or master can be skipped when every
changed file matches an ignored path such as .gitignore, README.md, or
LICENSE. Use paths to include matching paths and paths-ignore to exclude
matching paths.

Check the files in the latest commit with:

git show --name-only --format="" HEAD

Path patterns are evaluated from the repository root. Check capitalization,
singular and plural directory names, hyphens, and underscores against the
actual paths.

You cannot use paths and paths-ignore for the same event. If you need both
inclusion and exclusion, use a negative pattern beginning with ! inside
paths, and pay attention to pattern order. Path filters are not evaluated
for tag pushes. These rules are documented in GitHub’s
path filter syntax.

4. Check the commit message for a skip directive

A push or pull_request workflow can be skipped when the commit message
contains a supported directive such as:

[skip ci]
[ci skip]
[no ci]
[skip actions]
[actions skip]

Check messages created by automation as well as messages copied from another
commit. If a skip directive caused the problem, push a new commit without that
directive.

See GitHub’s
guide to skipping workflow runs
for the supported directives and their scope.

5. Confirm that the workflow and repository Actions are enabled

A workflow can be disabled without deleting its YAML file. If you see an
Enable workflow button after selecting it in the Actions tab, enable it
before testing the trigger again.

Also check the repository-wide Actions policy:

Repository Settings
→ Actions
→ General
→ Actions permissions

In an organization-owned repository, organization or enterprise policy can
override repository settings. GitHub documents the recovery steps in
disabling and enabling a workflow.

6. Check whether another workflow pushed with GITHUB_TOKEN

If a person did not create the push and an earlier GitHub Actions workflow used
GITHUB_TOKEN to push the commit, that push will usually not create a new
workflow run. This behavior helps prevent workflows from triggering each other
indefinitely.

GitHub’s
GITHUB_TOKEN documentation
explains that events created by GITHUB_TOKEN do not create new workflow runs,
with exceptions such as workflow_dispatch and repository_dispatch.

Before issuing a broadly scoped personal access token, consider whether one of
these designs fits the workflow:

• Continue the work in another job in the same workflow.
• Use workflow_call for a reusable workflow.
• Use workflow_run when the next workflow must follow completion of an
  earlier workflow.
• Use repository_dispatch when an external system must explicitly trigger
  the workflow.

If you must change the authentication method, use a least-privilege GitHub App
or token. Never place a token directly in workflow YAML or print it in logs.

7. Use a manual run to separate trigger problems from job problems

When a workflow includes workflow_dispatch, you can start it from the
Run workflow button in the Actions tab:

on:
  workflow_dispatch:
  push:
    branches:
      - main

If the manual run succeeds but pushing does not create a run, troubleshoot the
branch and path conditions under push before changing Python, Node.js, build,
or deployment commands.

If a manual run does not start either, check whether the workflow is disabled,
whether repository policy blocks Actions, and whether the YAML structure is
valid.

The Run workflow button requires workflow_dispatch, the workflow file
must exist on the default branch, and the user starting it needs write access.
See GitHub’s official
manual workflow guide
for the full requirements.

In a separate test repository, a push to main that changed a configured path
created a workflow run. A push that changed only a non-matching path did not
create a new run. Starting the workflow with Run workflow also created a
separate manual run.

Information to collect if the workflow still does not run

If the problem continues, collect these details in one place:

• The workflow file path and its on: section
• The branch you pushed
• The paths changed in the latest commit
• The latest commit message
• Whether the workflow appears in the Actions tab
• Whether a manual run is available
• Whether a person or another workflow created the push

Do not include secret values in a screenshot or support question. If a run is
created and then fails with 401, 403, or a package installation error, the
push trigger is working. Troubleshoot the failed step separately from the
event trigger.

Summary

When GitHub Actions does not start after a push, check these items in order:

1. Confirm whether a workflow run exists.
2. Check the file location under .github/workflows/.
3. Verify the branch you actually pushed.
4. Evaluate branches and paths filters together.
5. Check the commit message for a skip directive.
6. Confirm that the workflow and repository Actions are enabled.
7. Check for a GITHUB_TOKEN-created push and compare it with a manual run.

This sequence keeps a missing workflow trigger separate from a job that
started successfully and failed later.