GitHub Actions — All Scenarios Explained (Complete & Clear)

Understanding when workflows appear in the UI, when they can run, and which branch GitHub reads workflows from can be confusing. This guide explains every scenario clearly — covering workflow visibility, run button availability, automatic triggers, and CLI/API behavior.

---

All Scenarios

#  Scenario                                      Visible?        Run Button?
─  ────────────────────────────────────────────  ──────────────  ───────────

1  workflow_dispatch in DEFAULT branch           YES             YES

2  workflow_dispatch in NON-DEFAULT branch       NO              NO
   and never executed before

3  workflow_dispatch in NON-DEFAULT branch       HISTORY ONLY    NO
   and executed via CLI/API once

4  on:push workflow exists ONLY in DEFAULT       YES             NO
   branch but push occurs to another branch
   that does NOT contain the workflow file

5  on:push workflow exists in NON-DEFAULT        NO              NO
   branch and the branch is pushed
   to the repository for the first time

6  on:push workflow exists in NON-DEFAULT        HISTORY ONLY    NO
   branch and the workflow has run before

7  schedule or repository_dispatch workflow      NO              NO
   exists ONLY in NON-DEFAULT branch

---

Scenario Breakdown

Scenario 1 — workflow_dispatch in the Default Branch

Visible: ✅ Yes   |   Run Button: ✅ Yes

The workflow file exists in the default branch. GitHub lists it in the Actions UI and shows the "Run workflow" button. Users can start a workflow run manually from the UI. The same workflow can also be triggered using the CLI or API.

---

Scenario 2 — workflow_dispatch in a Non-Default Branch (Never Run)

Visible: ❌ No   |   Run Button: ❌ No

The workflow file exists only in another branch (for example, a feature branch). GitHub does not list workflows from non-default branches in the UI, so it is not visible and there is no "Run workflow" button.

However, it can still be triggered manually using the GitHub CLI or the REST API by specifying the branch containing the file.

---

Scenario 3 — workflow_dispatch in a Non-Default Branch (Run Once via CLI/API)

Visible: 🕓 History Only   |   Run Button: ❌ No

The workflow was triggered earlier using CLI or API from that branch. The workflow itself still does not appear in the sidebar list, but the past run appears in the workflow run history. It can again be triggered using CLI/API.

---

Scenario 4 — on: push Workflow in Default Branch, Push to Another Branch

Visible: ✅ Yes   |   Run Button: ❌ No

The workflow file exists in the default branch, so it appears in the UI. However, when a push occurs to another branch that does not have the workflow file in that branch's commit, GitHub cannot find the workflow to execute — therefore the push event does not trigger it.

---

Scenario 5 — on: push Workflow in Non-Default Branch, First Push

Visible: ❌ No   |   Run Button: ❌ No

The workflow file is located in a non-default branch. When that branch is pushed for the first time and the pushed commit contains the workflow file, GitHub detects it and runs the workflow automatically because the push event matches.

---

Scenario 6 — on: push Workflow in Non-Default Branch (Has Run Before)

Visible: 🕓 History Only   |   Run Button: ❌ No

The branch already contains the workflow file and it has run previously. Each new push to that branch triggers the workflow automatically. The workflow may still not appear in the sidebar list, but all runs appear in the run history.

---

Scenario 7 — schedule or repository_dispatch in a Non-Default Branch

Visible: ❌ No   |   Run Button: ❌ No

If a workflow using these triggers exists only in a non-default branch, GitHub does not evaluate it. These triggers are processed only from workflow files located in the default branch, so the workflow will never run.

---

4 Golden Rules

Rule 1 — The "Run Workflow" Button

The "Run workflow" button appears only when a workflow file containing workflow_dispatch exists in the repository's default branch.

---

Rule 2 — Push Events Read from the Pushed Commit

For push events, GitHub reads the workflow definition from the commit that was pushed. If the pushed branch does not contain the workflow file in that commit, the workflow cannot run.

---

Rule 3 — Visibility in the Actions UI

A workflow becomes visible in the Actions UI when either:

• The workflow file exists in the default branch, OR

• A run of that workflow has already occurred and appears in the run history.

---

Rule 4 — Scheduled and External Triggers

Triggers such as schedule and repository_dispatch are evaluated only from workflow files located in the default branch. If those workflows exist only in other branches, GitHub will not run them.

---

One Mental Model (Explains All Scenarios)

Manual trigger (workflow_dispatch)
  → UI button requires workflow in default branch
  → CLI/API can target any branch

Push trigger (on: push)
  → GitHub reads the workflow from the branch being pushed

Scheduled / external triggers (schedule, repository_dispatch)
  → GitHub only checks workflow files in the default branch

Understanding these three rules covers every scenario above. The key insight is that GitHub's behavior depends on where the workflow file lives at the time of the triggering event — not where it has ever been.