Manual Trigger In GitHub Actions

Table of contents

Reading Time: 4 minutes

This blog will give you an idea of the different options in which we can implement manual trigger using GitHub Actions.
In this we will have the answer of following question.

Is there a way to trigger a workflow manually in GitHub Actions?

There are different event by using which we can trigger the workflow like push, pull-request and many more. You can the detail information here.

You can also refer this blog to get GitHub Actions overview

But here, we will only see the Manual Trigger events

workflow_dispatch
repository_dispatch

Manual Trigger is important in some situations. When we need to execute an event from outside or without making any changes to the source code.

workflow_dispatch

Using this event you can run a specific workflow manually through the user-interface of GitHub actions. Once you added this event into your workflow.

Example:

on:
  workflow_dispatch:

You can run/execute this workflow through UI. Follow the below steps to execute workflow.

1: You will have a ‘Run workflow’ button on the Actions tab, enabling you to easily trigger a run.

2: You can choose on which branch the workflow should run on.

3: In addition, you can optionally specify inputs, which GitHub will present as form elements in the UI.

repository_dispatch:

You can use the GitHub API to trigger a webhook event called repository_dispatch. When you want to trigger a workflow for an activity that happens outside of GitHub.

To manually trigger the repository_dispatch event, we need to interact with the following GitHub API endpoint:

POST /repos/:owner/:repo/dispatches

Using the repository name (hello-world), along with my GitHub username (sakshigawande12). We can build the full path for the endpoint we’ll be interacting with:

https://api.github.com/repos/sakshigawande12/hello-world/dispatches

To make the POST request to this endpoint, we need to do several things:

Add a custom media type in the Accept header
Authenticate the call using an Authorization header. And a personal access token with repo permissions for the repository we’re working with
Specify an event_type in the POST body

Adding the custom media type

The following custom media type is required to make the call to the /repos/:owner/:repo/dispatches endpoint:

application/vnd.github.everest-preview+json

To add this to our curl command, we will add an Accept header as follows:

-H "Accept: application/vnd.github.everest-preview+json"

Authenticating the POST request

To authenticate the request, you’ll need to use, or generate, a new personal access token that has access to the repository you’re working with. That token must have the repo scope provided to it.

you can follow the steps to create personal access token here

Once you have your token, we’ll update our curl command by adding an Authorization header as follows:

-H "Authorization: token your-token-here"

Adding an event_type

The last part of building our request is to define the event_type property in the POST body.

--data '{"event_type": "do-something"}'

In this example, we’ll name our event “do-something”.

With all of our command components defined, we can build our final curl command like this:

curl -H "Accept: application/vnd.github.everest-preview+json" \
    -H "Authorization: token <your-token-here>" \
    --request POST \
    --data '{"event_type": "do-something"}' \
    https://api.github.com/repos/sakshigawande12/hello-world/dispatches

When we run this command, a webhook event will be received by our repository. To manually trigger a GitHub actions workflow from this webhook event, we can update our action to respond to the repository_dispatch trigger

Responding to the repository_dispatch event in a GitHub Actions workflow

Responding to the repository_dispatch trigger in our workflow requires a small update as follows

name: Do Something That Needs Scheduled
on:
  repository_dispatch:
    types: do-something

In the on: block of our workflow configuration, we’ve added repository_dispatch. Additionally, we’ve passed a type which matches the event_type we specified in our curl command.

At this point, we’ve done it. We can now manually trigger our GitHub actions workflow using curl from the command line.

If we do not specify the types property of the repository_dispatch trigger, our workflow will run in response to any repository_dispatch event. Otherwise it will limit for particular event type.

That event also has a client_payload property we can use to add additional data with which to customize our workflow.

With this client_payload property, we can pass configuration values, text, etc.

Let’s imagine we want to send some simple text with our repository_dispatch event and then print that text out during our workflow.

curl -H "Accept: application/vnd.github.everest-preview+json" \
    -H "Authorization: token <your-token-here>" \
    --request POST \
    --data '{"event_type": "do-something", "client_payload": { "text": "a title"}}' \
    https://api.github.com/repos/n8ebel/GitHubActionsAutomationSandbox/dispatches

Up till now we have seen how to trigger workflow manually.

But now the question is how we can trigger a particular step of workflow after a particular manual intervention ?

Can you manually trigger a particular step of GitHub Actions?

The answer is No. Github does not provide any action to trigger a particular step manually like other CI tool (i.e jenkins, circle-ci etc). But yes we can achieve this by other option like checking commit , if the commit msg is “deploy to prod” then and then only we deploy to production. Means we only execute the step who deploy application to the production if commit matches other wise we skip that step.

Example to how we can achieve that

You can run a git command to get the commit message : git log –format=%B -n 1 <commit>

Please set this commit message as the value of an environment variable using set-env command or the following action

- name: set environment variables
        uses: allenevans/set-env@v2.0.0
        with:
          MY_ENV_VAR: 'my value'

or directly using ‘env’ in workflow

 env:
    my_env_var: $(git log --format=%B -n 1 ${{ github.event.after }})

Then you can add if condition in all your next steps, to judge if commit message included specific keywords

- name: Checkout submodules
        shell: bash
        run: |
            auth_header=$(git log --format=%B -n 1 ${{ github.event.after }})
            echo $auth_header

      - name: set environment variables
        uses: allenevans/set-env@v2.0.0
        with:
          MY_ENV_VAR_2: {{$auth_header}}

      - name: if statement
        if: contains(env.MY_ENV_VAR_2 , 'try once again')
        run: echo $MY_ENV_VAR_2

For creating or triggering the workflow manually using both the event mention above, you can refer my example from here