Have a new workflow run from a PR (none main branch) before committing into main branch possible?

[punkbit]

Hi,

I’d like to test a workflow in a PR, but from what I understand it only shows and runs if committed to the “main branch”.

Is there a way to have new workflows show and run in the PR stage?

Just to be clear, a new workflow in .github/workflows/some-workflow.yml, when committed in a new PR, it won’t show up in the actions and I’d like to have it and run it before committing to the main branch.

Thank you!

[mickeygousset]

You can trigger off of a pull request event in your workflow file:

https://docs.github.com/en/actions/reference/events-that-trigger-workflows#pull_request

[punkbit]

Thanks for looking!

But I should have worded it differently.

I’m looking to have the workflow peer-reviewed before integrating it into the main branch. This means that the workflow is not yet available or merged with the main branch. Because it is not yet available, displayed, showing in the Github actions, I won’t be able to trigger it: manually, by PR, etc.

I believe that Github does not yet support running workflows that only exist in a none main branch. Am I correct?

Example use-case:

• Create a new branch for a new workflow
• Create a new workflow under .github/foobar.yaml
• Commit the file and changes for foobar.yaml
• Push the branch to Github
• Create a new PR for the branch against the main branch (or the same, in which the workflow should be triggered)
• Finally check actions, where the workflow won’t be available, or shown

cc @mickeygousset

[airtower-luna]

heldrida:

I believe that Github does not yet support running workflows that only exist in a none main branch. Am I correct?

It depends on the event type. There are certain event types for which the workflow file must be on the default branch (e.g. schedule), but events associated with a specific branch (e.g. push or pull_request) should work on other branches.

Check GITHUB_REF for different events in Events that trigger workflows - GitHub Docs. 🙂

[punkbit]

Thanks for the support!

If the PR holding a new workflow hasn’t yet been approved and merged to the “main” branch, is it expected to show in the actions?

Here’s an example, which is not showing (the workflow yaml only exists in the pending PR):

name: Foobar
on:

pull_request:

branches: [ main ]
workflow_dispatch:
jobs:

build:

runs-on: ubuntu-latest
steps:
  ...

My expectation was that at least I could trigger it manually, as you see the workflow_dispatch, or at least have it display in the actions sidebar. But afaik, it’ll only show once I merge into the main branch.

[punkbit]

My apologies, just found that I have the paths, in which the changes at the moment do not full-fill as I’m only working in workflow.

By removing it, the action does show as expected!

[mickeygousset]

for workflow_dispatch, you HAVE to have a version of the file in the main branch.

[igor-dovgaliuk-globallogic]

it is common practice that new functionality added to the project is not immediately merged into master/main and reviewed from there.
In case of workflow_dispatch it would be good to have a note about the limitation in the documentation
https://docs.github.com/en/actions/using-workflows/workflow-syntax-for-github-actions#onworkflow_dispatch

[jsoref]

Filing tickets isn't particularly difficult. Filed: github/docs#31007

[tracy-ash]

But workflow_dispatch will only run the workflow version that’s checked into the main branch, right?

[mickeygousset]

Ahhh, see that is where things get interesting. To initially make it show up on the Actions tab, and so that you can trigger it manually, it has to be checked in to the main branch.

BUT, when you trigger it, you can pick which branch to run it against. The only caveat is that the workflow file (or a version of it) also has to exist IN THAT BRANCH.

[rwader-swi]

so I'm having the workflow_dispatch triggering workflow on master, but I've made changes in the action that it is using and it's in the non-merged PR's branch now. So will my updated action run if I select that branch, or will the same action from master branch will be run?

[jsoref]

When you use workflow dispatch, GitHub asks you which branch to run. So it's your choice.

[iamakshatjain]

this is not mentioned clearly in the docs

[jsoref]

Correct, it's only visible in a screen capture:

You're welcome to file a ticket to the docs repository asking to clarify that. I file tickets regularly, but don't have the energy to do it for this one this year.

[tracy-ash]

ok, got it. thanks.

but for repository_dispatch, the workflow that runs must be in the default branch, right? if not, how can a workflow in a non-default branch be triggered by a repository_dispatch?

[mickeygousset]

That I don’t know I’d have to test it and see. The docs don’t say. Logically it makes sense that yes it would have to be on the main branch for repository_dispatch to work

[tracy-ash]

As far as I can tell with my limited experience with repository_dispatch, it only runs workflows on the default/main branch when triggered by a push on a non-default branch. Would love to be proven wrong. :slight_smile:

[tracy-ash]

This is what I’d love:

push to dev branch -> trigger and run workflow on dev branch

[blanchardjeremy]

I was struggling with this too. I followed what I picked up from this thread and did the following:

1. Make a new workflow with a very incomplete set of actions. Just a skeleton basically.
2. Add the workflow_dispatch to the config so I can trigger it manually
3. Commit the new workflow to a branch
4. Open a pull request for that new branch
5. Merge it into the default branch (main) (even though it’s not functional)
6. Now you can access the action from the Actions tab on the repo
7. You can run it against a specific branch.

[shivam-effibuild]

It's usable but, GitHub makes us feel dumb doing these types of hacks.

[ndpiparava]

This is not solution, why we should merge untested changes to default branch? this also against practice of following PR process.

[jsoref]

Fwiw, as long as the repository is public, you can create a public fork and set your public fork’s default branch to the version which has the code you want to demonstrate. (And possibly w/ the same name as the expected destination branch, instead of the name of the feature branch in your fork as used for your PR.)

In your case, removing the branches: [ main ] item of course was sufficient.

In some cases you could just add a second branch, as in:

on:
  pull_request:
    branches:
     - main
     - demo

[pnadolny13]

@jsoref thanks for this! It seems obvious but solved my problem.

I was trying to follow the workflow from https://github.com/orgs/community/discussions/25746#discussioncomment-3249056 but I didn't want to commit my draft to main. Testing on my fork main branch allows me to keep the actual main branch clean until I'm done testing. Its especially helpful in cases where I'm experimenting and am not planning to ever get this workflow into the main branch.

[fharper]

Seems like you either need to have it first in main or create a fork like described by @jsoref.

Still, I would love if GitHub add the option to be able to display the /actions view based on the selected branch in the UI or display actions available in other branches which are not in the main one in the view or at a minimum, let us fire actions from a specific branch (even if it's new or was deleted from the main branch with their CLI).

[jsoref]

Workflows can reference actions at arbitrary commits by full sha, by branch, or by tag.

That isn't a problem.

[vladimirdu]

I’m still unsure about how to test a newly implemented workflow before integrating it into the default branch. 🤔 Is there an approach to experimenting with a new workflow and verifying different commands/images, etc., without needing to merge every modification into the master beforehand for testing?”

[airtower-luna]

It depends mostly on the workflow trigger you're using. Some will only work if the workflow is on the default branch, but others (like push or workflow_dispatch) work on any branch. If you can test using one of those you don't need to merge first. If the workflow is supposed to run on a different event you might be able to test your code using sample data and then only change the data source before merge.

[fharper]

Most workflows can be tested on your computer with act. I still would like to see this implemented for edge cases.

[BrunoJuchli]

I would like to be able to test workflows with a workflow_dispatch and a choice input on a branch before merging it to the main branch.
Seems to me this is currently impossible, but I'd be happy if someone proves me wrong ;-)

[jsoref]

You asked what's possible.

Forks don't have access to secrets.

Fwiw, if you need to test additional inputs, you could merge a thing which provides the additional inputs but no wiring w/ a user facing note explaining it's for use w/ specific branches.

[mickeygousset]

The workflow has to exist on the main branch in order to enable the manual run button. So normally what i do is create a blank workflow and push it to main. Then I can edit the workflow on a branch off of main, and when I run it, I can tell it to run on that branch and it will use the version on that branch.

[tedparagon]

Thanks @mickeygousset. This seems like the least painful option even though it still requires an extra PR. As mentioned above it would still be nice to be able to run the new workflow off the feature branch in the UI without first merging to main.

[BrunoJuchli]

@mickeygousset
That's what I usually do, but AFAIK the choice UI is not available when you add the choice spec on the branch.

@jsoref
Thanks for your comments.
These workarounds are doable but far from ideal. As long as there's no better option, it's good to have these documented.
However, I would still like GH to implement "first class" support for these scenarios.

[Matthew0x]

Since the issue was reported at least 4 years ago, would it be possible to fix this design to catch up with industry's equivalents, e.g. ADO? It is not the expected behaviour to push into the default branch in order to test changes on personal branches. GitFlow clearly specifies how a standard branching model looks like.

[Zordid]

How can such a simple thing be SO SCREWED up on Github?? I simply cannot understand how completely messed up GH actions are. It is absolutely NORMAL for any developer to NOT push things directly on main, I do not want to mess up my main branch only to develop a new action. Unbelievable.

[jsoref]

I can't quite tell from your complaint which part of things is bothering you.

GitHub might not show you a workflow in its left sidebar, but you absolutely can push a workflow to a branch that is defined to run on the branch to which you push it, and have it run.

Do you have a specific repository and workflow in mind?

[Zordid]

As stated, I am talking about a workflow_dispatch Action, not triggered by a push, as I need input parameters. Finding out why my workflow shows up but cannot be run was a total mess. When you push a malformed workflow to any branch, no matter the trigger, it shows up on the left side, but you don't find the "run action" drop-down anywhere. It is simply not understandable to a new user and no document explains this. The only way to develop a brand new action with inputs is to first merge some empty / incomplete workflow on main in order to then start developing it on a feature branch. All the time the not-yet-ready workflow is now shown to all users of the repo as if it were already there and working... Josh Soref ***@***.***> schrieb am Di., 5. März 2024, 13:25:

…

I can't quite tell from your complaint which part of things is bothering you. GitHub might not show you a workflow in its left sidebar, but you absolutely can push a workflow to a branch that is defined to run on the branch to which you push it, and have it run. Do you have a specific repository and workflow in mind? — Reply to this email directly, view it on GitHub <#25746 (reply in thread)>, or unsubscribe <https://github.com/notifications/unsubscribe-auth/ABETSZTXNRMJ7W6FYR6T7VDYWW2U3AVCNFSM6AAAAAAWBTL4RKVHI2DSMVQWIX3LMV43SRDJONRXK43TNFXW4Q3PNVWWK3TUHM4DMNZZGYZDO> . You are receiving this because you commented.Message ID: ***@***.***>

[jsoref]

https://docs.github.com/en/actions/using-workflows/events-that-trigger-workflows#workflow_dispatch

Note: This event will only trigger a workflow run if the workflow file is on the default branch.

Is this insufficient documentation? If so, you can file an issue.

I think the idea that a workflow file can't be malformed if you want it to work is kinda easy to understand if one spends a bit of time thinking about it.

Generally my approach to workflows is:

1. develop a basic workflow with the structure I need that uses on: push -- this is easy enough to test because each push to whichever branch I'm using will trigger a run.
2. I can simulate inputs things by using the env context.
3. As you've discovered (and as is well documented), to use workflow_dispatch, when I have something vaguely working, I'll add a dummy version to the default branch with on: workflow_dispatch.
4. As for workflows being visible to all users -- that's part of working in the open. The way I deal that is that I'll do my development in a fork instead of the main repository -- as an added bonus, by doing this, I can change my default branch of my fork to the one with workflow_dispatch.

[ishi]

Actually there is way to test a new workflow on branch. First you create a skeleton implementation in the branch that is triggered by

on: 
   push:

and push it to the github so the workflow is run and github is aware of such workflow.
Next you develop the target workflow replacing the on push event with desired on: workflow_dispach.
When you push it you can trigger the workflow using the github cli command:

gh workflow run <workflow-file-name>.yaml -r <branch-name> -f input-field=value

[helloint]

I think this at the moment is the best workaround. When the workflow on branch is ready to test, add on push trigger and let it trigger once. You can cancel the job but still need to keep it there. Then you can remove the on push trigger and use gh CLI to test your workflow from branch until the end

[Matthew0x]

There is also another approach that boils down to the same issue. You can modify an orchestrator (dispatchable) workflow (supposing you have some already and use them in your default branch) to call a dummy reusable (callable) workflow. You create a wrapper in the form of a special job that runs a template with custom steps within (with inputs that you can control).

This way you append a name reference to the "dummy" template using an existing, persistent workflow, but you test the parametrized logic within that template in your branch without having to push every piece of logic separately into the default branch.

[ncgjones]

It's 2025, and we still can't run workflow dispatch from branches.
You've been able to do this in Azure Devops since forever. Why is github so far behind? I don't understand why they want us to merge untested workflows to main, or change the default branch to test workflows.

All these workarounds are fine, and helpful... but it doesn't solve the core issue. Github expects us to merge untested workflows to the default branch in order to test them.

[SilverPreeceSOF]

I have no idea why Azure DevOps is EOL in favour of GitHhub Actions when GitHub isn't even close to being able to replace it and won't be for a long time yet.

[Matthew0x]

Are you sure about the EOL? It seems the opposite.
https://learn.microsoft.com/en-us/azure/devops/release-notes/features-timeline-released#released-features

There is a clear roadmap along with a nice summary per Release, for those who may be more curious
https://learn.microsoft.com/en-us/azure/devops/release-notes/2025/pipelines/sprint-257-update

Unironically, it seems that a 'StringList' was added, one of very crucial features for Pipelines in general.
"Starting with this sprint, we've added a new parameter type, named StringList, that provides this capability."

[jan-philippkappmeier-tomtom]

Finally String list, I wait for this for over 9000 years.

[Eddie-Hartman]

@jsoref it seems like you were pretty active in this thread and fairly knowledgeable on this topic.

1. This exists in Azure DevOps. I am in a GitHub enterprise setup without forking, so right now the ONLY way I can set up a new pipeline/action and test it in the UI is by getting a template and merging it in via PR. That's fairly unacceptable. I'm honestly kind of shocked this thread has been out there for so long without just adding a setting to allow running actions from other branches that are NET NEW.
2. So I'm seeing a lot of people vocalizing here, but how does a feature request get submitted or how do we get this to GitHub proper to escalate and backlog it properly? Maybe @mickeygousset? What I'm looking for is the ability for a repo maintainer to allow adding workflow_dispatch actions into the list that are NOT on the default branch for testing purposes before having to merge them in. In Azure DevOps, this allowed us to experiment more with actions. Here, it sounds like I'd make some kind of "Action Testing" skeleton, modify it in branches whenever I want to make a new one, then merge the "real" one in as a new file, which all sounds like jumping through completely unnecessary hoops.

[jsoref]

If you're an enterprise, maybe you have a CSR to whom you can complain?

Personally, I'd just cannibalize any existing workflow that has a workflow_dispatch handler and then use the default branch for that workflow to test my branch's changes.

Personally, I'm not an enterprise and haven't found ears of GitHub management. I just work within the constraints I can see.

[SilverPreeceSOF]

Based on @ishi 's reply, I tried pushing a workflow_dispatch setup to a branch and seeing if I could trigger it directly, just to confirm if it was possible. It was not. Even specifying the branch as the target ref from the CLI, it will reject the attempt to start the workflow because it does not also exist on the default branch. I assume this is intended as a security feature of some kind, preventing developers from pushing new unapproved workflows to branches and executing them directly, but it's still absolutely maddening for people trying to build out new workflows, especially when the workarounds are so obvious.

$ gh workflow run deploy.yml --ref "my-work-branch" -f input1=val1 -f input2=val2
HTTP 404: workflow deploy.yml not found on the default branch (https://api.github.com/repos/myorg/myrepo/actions/workflows/deploy-vm.yml)

[jsoref]

You can always use your own fork and set a branch with the code in question to be your default branch. It's a much safer approach for testing potentially untrustworthy code changes

[mallman-experian]

My codebase is a private org repo. I'm having the same problem as OP.

[jsoref]

so create another copy of your private repo and change that copy's default branch to include the changes... Orgs can have multiple forks of a repository (unless they don't allow forks at all -- in which case you can just create a disconnected repository).

[mallman-experian]

I acknowledge what you suggest is a workaround. I'm looking for a solution to the original problem, running a new/modified workflow from a branch of an existing repo. I raised this as an issue with Github support and they indicated that this is on their internal feature request list. Hopefully they can make this easier.

[rafael-unloan]

LOL. Having to fork just to get a workflow to show up is so absurd.