Introduction

We wanted to give some thoughts on how we can improve the control over our GitHub Actions workflows, especially for those pieces of tasks that require manual intervention. Instead of using automated triggers, we can use a manual trigger called workflow_dispatch, really useful when we need workflows to run at specific times.

What’s the workflow_dispatch event?

That said, this event, on the other hand, is designed to kick a workflow off manually from GitHub's UI or even via API. Rather, it is better suited for performing activities such as deploying to production, where the right moment of execution needs to be decided by a human.

We only need to add a simple configuration in our workflow file under the .github/workflows directory.

.github/workflows/manual-trigger.yml

name: Workflow Dispatch Example

on:
  workflow_dispatch:

jobs:
  job:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4
      - run: |
          echo "Hello, world!"
          sleep 10

Adding inputs for more dynamic workflows

One great feature of workflow_dispatch is that we can define inputs. It means we can pass parameters to the workflow when it's triggered, hence much flexible.

.github/workflows/manual-trigger.yml

name: Custom Build Workflow

on:
  workflow_dispatch:
    inputs:
      build_type:
        description: 'Type of build to execute'
        required: true
        default: 'development'
      include_tests:
        description: 'Run tests during the build'
        required: false
        default: 'false'

jobs:
  build:
    runs-on: ubuntu-latest
    steps:
      - name: Checkout code
        uses: actions/checkout@v4
      - name: Setup Node.js
        uses: actions/setup-node@v3
        with:
          node-version: '14'
      - name: Install dependencies
        run: npm install
      - name: Build project
        run: |
          echo "Building project with type ${{ github.event.inputs.build_type }}"
          if [ "${{ github.event.inputs.include_tests }}" = "true" ]; then
            echo "Running tests..."
            npm test
          fi

How to trigger the workflow

You can trigger the workflow either from the GitHub UI. Here's a quick look at how to trigger via UI:

1. In the repo, click on the Actions tab.
2. Select the workflow that you want to run. 3. Click on Run workflow, fill in the required inputs, and click Run.

Conclusion

Great for adding flexibility in your CI/CD pipelines, the workflow_dispatch event fully controls when and how specific workflows are triggered. Workflows can be manually started through the GitHub UI or API to customize them for particular needs, such as deploying to different environments or handling time-sensitive tasks that require human oversight.

Monitoring GitHub Actions Workflows

CICube is a GitHub Actions monitoring tool that provides you with detailed insights into your workflows to further optimize your CI/CD pipeline. With CICube, you will be able to track your workflow runs, understand where the bottlenecks are, and tease out the best from your build times. Go to cicube.io now and create a free account to better optimize your GitHub Actions workflows!