Using Workflow Dispatch to trigger parameterized GitHub workflow
A GitHub Workflow can be triggered based on a event, such as push or pull request. There is also an option to trigger a workflow manually and that is using workflow_dispatch.
This particular method is useful when we have a need to configure workflow parameters that are evaluated at runtime. As an example, let’s say we have a requirement from the Sales team who would like to spin up a specific demo environments for different workloads. These demo environments have specific type/size and number of Virtual Machines to support. We can have two workflow parameters, one for the specific type and size and another one for the number of Virtual Machines. Maybe there is also a third parameter to enable seeding the database with some demo data. This becomes a way for us to automate our cloud environments based on our needs. There could be a simple webform frontend which can be created from any modern tools to submit to the GitHub workflow endpoint.
Now we understand the use case, let’s talk about how we can implement this. If you have been following, you will know that we always start with a yml file created in the .github\workflows folder. Once we create the file, we can simply drop the workflow_disptach section as follows. The input will have a description, whether it is required and a default value.
Notice that we included a push action, which is there to initially create the workflow when we first do our git push, otherwise, we will get a 404 NOT FOUND error when we first invoke the workflow API.
To leverage the inputs parameter, we can simply reference it with the following syntax.
${{ github.event.inputs.vmSku }}"To invoke the workflow API, we need a token. We will need to create our personal access token. This can be found under Settings > Developer settings > Personal access token. You will need to have write permission in the repository.
Now, we are ready to invoke the workflow API with the following code. The first thing is to embed your personal access token in the authorization header with token keyword.
The endpoint starts with https://api.github.com/repos/ and has the owner and repo followed by dispatch/actions/workflows/ with the filename of the yml file and ends with dispatches.
The body itself contains the ref which points to the branch of your code and the inputs object which contains the key/value of your input parameters. If everything goes well, you will see a 204 returned as in my example below.
As we can imagine, we can potentially create more yml files so we can trigger additional workflows where these would leverage some common/shared scripts or files.
The source code of what we discussed here is on https://github.com/seekdavidlee/az-vm-workflow-dispatch. This is an actual working copy and I encourage you to fork it for your own repo.
I do hope you have enjoyed this reading and learned something new today.
