153

For actions working on a third party repository, I would like to be able to create an action on a branch and execute it on the workflow_dispatch event. I have not succeeded in doing this, but I have discovered the following:

  • The Action tab will change the branch where it finds workflows and action code based on the branch relating to the last executed workflow. e.g. if some workflow is executed from the Action tab using the Run Workflow button and the Use Workflow From dropdown is set to some branch, Branch-A, then the contents of the Workflows panel on the left hand side of the Actions tab will be taken from Branch-A's version of .github/.
  • The This workflow has a workflow_dispatch event trigger. text does not change with the branch. It seems to be taken from master. Alternatively, it may be being taken from the last set of results. I have not tested for that because either way it is not helpful behaviour.

The workaround is the execute on a push event which is OK, but that seems out of kilter with GitHub's high standards of design.

Does the above sound a) about right and b) whichever way you look at it, not optimal behaviour? Or, is there a better approach to building and testing actions?

7 Answers 7

114

You can run a workflow that is still in development in a branch branch-name from the command line, with the GitHub CLI. The documentation says:

To run a workflow on a branch other than the repository's default branch, use the --ref flag.

gh workflow run workflow-name --ref branch-name

To list valid workflow names, use gh workflow list.

To add input parameters, run it like this:

gh workflow run workflow-name --ref branch-name -f myparameter=myvalue

5
  • 72
    Specifically for workflow_dispatch this won't work until the workflow has run once before. You can add a push event hook and then it will be activated after running once. Using gh workflow list you can see the job in the list once it has run once.
    – Dustin
    Commented Jun 23, 2021 at 16:32
  • 6
    Hmm I didn't know that gh exists. Thanks. Sadly as @Dustin wrote. It is not working for newly created workflows never run before. Ive tested this by creating new workflow file on new branch and after running gh workflow run workflow-test.yml --ref=feat/wf-dispatch-cli-test I got only could not find any workflows named workflow-test.yml. Yet it sees old workflow on this new branch without problems.
    – piotrekkr
    Commented Jul 1, 2021 at 22:04
  • 12
    To follow up on this: add a pull_request: to your workflow file and push that. It will register the workflow (you can view via gh workflow list). Then run gh workflow run 'My Workflow Name' --ref branch-name. Note there, that's the actual name of the workflow, not the name of the yaml file.
    – hayesgm
    Commented Feb 9, 2022 at 22:47
  • 3
    Having to add an event to the workflow to get it to run once is absurd! And I've noticed that this is not always the case. For instance, I can't find my newly added workflow in one repo, but in 10 other repos it's there and runnable (same workflow).
    – Josh M.
    Commented Jun 7, 2023 at 16:38
  • 1
    push: makes much more sense than pull_request (see @code11 answer below) Commented Apr 12 at 14:47
78

You can run your workflow through the GitHub CLI, but you will first need to make sure it's run before.

gh workflow list

If your workflow isn't in that list (by name), then add pull_request: and create a pull request so that the workflow is registered, once.

name: 'My Workflow'
on:
  workflow_dispatch:
    inputs:
      parameter:
        description: My Parameter
  pull_request: -- Add this here
...

Once you've created a pull request, you should see 'My Workflow' when you run gh workflow list. Once that's done, you can remove the added line.

Finally, now run:

gh workflow run 'My Workflow' --ref my-branch -f parameter=value

This should run your workflow dispatch from a feature branch.

3
  • 18
    Instead of pull_request it would be even easier to just use push to trigger the first run from the branch.
    – MEMark
    Commented Feb 22, 2022 at 8:51
  • 10
    We shouldn't have to do either of those things. If we add a workflow_dispatch event to a workflow, it should show up in the Actions tab / via gh workflow list immediately. (But it doesn't.)
    – Josh M.
    Commented Jun 7, 2023 at 16:39
  • @MEMark It depends, I think. pull_request is easier if your default branch is configured to only accept pull requests. And a pull request can be opened and closed without messing with the history.
    – huyz
    Commented Sep 2 at 8:54
34

UPDATE: @hayesgm answer may be better choice since using push/pull_request workflow trigger will register new workflow in GitHub and then you can just remove unneeded push/pull_request events trigger and run workflow using gh command. It works without merging anything to default branch.

UPDATE 2: Seems like using @hayesgm way may not work for you if you expect to see "Run workflow" dropdown in GitHub UI for your not yet merged workflow. It will be available to see on workflow list in Actions tab and will be available to run using gh but not by using GitHub UI.

UPDATE 3: I could not find it documented anywhere but I think workflow is registered only if it exist on default branch or if it was run at least once on non-default branch. In case of non default branch, GitHub knows about workflow existence only when it has workflow run logs available. If you remove all workflow logs for it, then it will get unregistered and you cannot run it any more. This is not the case for workflows that exist on default branch. Those are always available even without any workflow run logs.


  • Seems like it works as you described
  • Text seems to change when you run workflow on non main branch and on this branch workflow name changed to something new...

This workflow name change is really strange. I couldn't find any docs describing this behavior.

Testing workflows

One thing that needs to be done before testing is to actually add dummy workflow with same filename to main/master. Without this workflow won't appear in actions tab.

How to test:

  1. Create dummy Readme.md and some dummy .github/workflows/workflow.yml to test:
    name: Test run v1
    
    on:
      workflow_dispatch:
    
    jobs:
      test:
        runs-on: ubuntu-18.04
        steps:
          - name: Show environment v1
            run: env | grep ^GITHUB
          - name: Show ref v1
            run: echo "===============> Version from $GITHUB_REF"
    
  2. Push to your default branch (probably main or master)
  3. New action should appear there
  4. You can now run dummy workflow

Testing branch run:

  1. Create new branch test-branch from default repo branch
  2. Modify workflow file .github/workflows/workflow.yml
    name: Test run v2
    
    on:
      workflow_dispatch:
    
    jobs:
      test:
        runs-on: ubuntu-18.04
        steps:
          - name: Show environment v2
            run: env | grep ^GITHUB
          - name: Show ref v2
            run: echo "===============> Version from $GITHUB_REF"
    
  3. Commit and push to test-branch
  4. Go to Actions
  5. Click Test run v1 and set Use workflow from to test-branch.
  6. Click run workflow button

You should see different step names than in default repo branch workflow version and different GITHUB_REF.

The weird thing is that after running workflow on test-branch somehow without merging anything, my previous workflow (from default repo branch) changed name to new version.

enter image description here

2
  • 2
    It seems bug-ish so I think this works as the accepted answer. Thanks for the analysis.
    – mikemay
    Commented Dec 22, 2020 at 16:11
  • 2
    Seems like this weird name change bug was fixed because I did not see this behavior for some time now.
    – piotrekkr
    Commented Jan 19, 2022 at 10:47
29

I'm seeing a lot of answers with adding pull_request:, but in my organization, we hold off on pull requests until we want review by others.

I think a better suggestion was made by MEMark.

Add push: instead and just push once to your remote feature branch, then edit that line out. The action will be registered and you don't have to mess with master or any pull requests.

name: 'My Workflow'
on:
  workflow_dispatch:
    inputs:
      parameter:
        description: My Parameter
  push: -- Add this here
6
  • 6
    Maybe you should start using Draft PRs? That will give you CI runs but without any reviewers being nudged. github.blog/2019-02-14-introducing-draft-pull-requests Commented Aug 15, 2022 at 8:55
  • 3
    This is probably the best answer as it doesn't require any meddling with the main/master branch to get the workflow in a runnable state.
    – gcode
    Commented Apr 10, 2023 at 19:01
  • 3
    It really is the easiest option! Just add push: and submit the changes. After that, the runner will start up. In the next commit, remove push: from your workflow. Voilà! Thanks you!
    – Ruble
    Commented Dec 21, 2023 at 9:18
  • 1
    Good answer - if you do this though you will probably need to provide default values for your input parameters.
    – Joman68
    Commented Mar 7 at 23:18
  • 1
    @huyz, You don't have to push to main, or even develop, just a feature branch.
    – code11
    Commented Sep 3 at 13:27
0

As an option you may fork third-party repository to yours, and do PR, merging to your main branch. After that you'll be able to debug workflow on your repository.

Another option is to add on: pull_requst: and test it by creating pull request.

0

If you already modify your workflow, as shown in the other answers (suggesting to add PR) and then use the GitHub CLI (executable gh), you might as well do this.

on:
  workflow_dispatch: {}
  push:
    branches:
    - features/myfeature

This way you don’t need to use the CLI. The pipeline will run once you push. Then you have to remove that branch trigger again, as you would do with the pr trigger.

So after all it's still not ideal, but at least you don’t jump through more hoops using the GitHub CLI.

-1

Whether you use on push: or on pull:, you will likely need to provide default values for your input parameters (as they will all be set to null when the workflow is triggered).

For example:

name: 'My Workflow'
on:
  workflow_dispatch:
    inputs:
      logLevel:
        description: Logging level
        type: string
        required: true
  push:

env:
  LOG_LEVEL: ${{ inputs.logLevel || 'DEBUG' }}

In the above example inputs.logLevel is null when run on push so the || expression defaults it to DEBUG.

See this answer for more details on how to set default values for input parameters.

Your Answer

By clicking “Post Your Answer”, you agree to our terms of service and acknowledge you have read our privacy policy.

Not the answer you're looking for? Browse other questions tagged or ask your own question.