Running manual CI workflows on non‐main branches via GitHub CLI

Context

GitHub CI workflows in the repository that have the condition on: workflow_dispatch can be run manually. However, the GitHub website will only display workflows that are also available on the main branch of the repository (currently master). To be able to run workflows that have the on: workflow_dispatch condition, but are not on the main branch, one must use the GitHub CLI.

Procedure

Adding a new workflow

First, you must create a branch of NEURON that adds a new workflow (workflow must be inside the .github/workflows/ directory), and push it to GitHub.

GitHub CLI

To install GitHub CLI, you can do the following:

• on MacOS: brew install gh
• on Linux: follow the instructions here

Once GH CLI is installed, you first need to authenticate:

gh auth login

Follow the instructions there. If you are using an authentication token to login, you need to first generate one. To do this, you can go to your settings page, and open "Developer settings":

Then expand "Personal access tokens" and click on "Fine-grained tokens":

Finally, click on "Generate new token", and follow the procedure from there.

Launching workflows

To launch a workflow, you can run:

gh workflow run [workflow_filename] --ref [branch] -f [key1=val1] -f [key2=val2]

where:

• [workflow_filename]: the full name of the workflow file, including the file extension (typically something like neuron-wheels.yml)
• [branch]: the name of the branch where to take the workflow from
• -f [key1=val2] ...: any keys and corresponding values of inputs

For example, with the following inputs:

platform:
  default: ubuntu-latest
  required: false
python:
  required: true
some_flag:
  type: boolean
  default: false
  required: false

You could launch the workflow with the flags:

-f python=3.9 -f some_flag=true

If all of the required inputs of a given workflow have defaults set, then one can also launch a workflow run without any -f flags.