Manually running Github actions (workflow_dispatch)


In my research on the simplest way to implement CI/CD deployment rollback using Github Actions, I decided the simplest-but-not-too-simple solution would be to run a workflow manually. But I could not find a satisfying answer to one key question:

If I run a workflow with “Use workflow from [select a branch]” then
1) does it use the workflow file from the selected branch or does it always run the main branch workflow file?
2) does the Checkout step certainly use the selected branch?

OK then two questions. The answers seem more or less obvious, but since being wrong would seriously affect operation of a live system, I created a test repo. The repo has two branches, main and not_main, and I added a version of a workflow, “Workflow one,” to each branch. The workflow identifies its branch by printing out hardcoded text to show where it came from, and it identifies which Checkout branch was used by printing contents of a repo file. Here are the results:

Results of running the action with Use workflow from [main]
Results of running the action with Use workflow from [not_main]

So as you might have expected, if you Use workflow from <selected branch>, then

  • The workflow file from the selected branch is the one that’s run, and
  • A Checkout step (without explicitly specifying a ref to branch/tag, etc) will also check out the selected branch

Why this was not quite obvious

The concern arose from this anomaly: On the Actions page, the All Workflows list you get to pick from only shows the workflows that exist in the default (typically, main) branch. This sort of implies all you can run are main branch workflows, but that’s not true. The way it works is a little goofy.
To demonstrate, I added a workflow only to the not_main branch, and I added another workflow only to the main branch.

  • The All Workflows list on the Actions page now list both of the workflows that exist in main branch (but not the workflow that exists only in not_main, so there’s no obvious way to run that one.)
  • You are allowed to pick a workflow from the list that exists only in main and then choose to run it in the non_main branch, even though it’s doomed to fail like this:

Implications and options

  • For a named workflow, you can have different workflow content in each branch and when you run it manually it will use the version from the correct branch. If you want them to be the same, of course that’s possible too.
  • If you want to use a workflow that exists in a non-default branch, there must be an identically-named workflow in the default branch. It can be a no-op, but it must be valid because Github does a sniff test when a workflow is saved.

Our CD/CD deploy triggers on creating a new “v…” tag (e.g, “v1.0.1”.) Our corresponding “rollback” strategy is to create a second workflow that:

  • is virtually-identical to the deploy workflow, but
  • is only triggerable manually, and
  • requires an input to specify the tag version you want to roll back to

I am sure there are more elegant ways, but that’s good enough. Automating things you rarely need to do can be a serious time waster.