Understanding Workflow Dispatch in GitHub Actions – A Beginner’s Guide

GitHub Actions is a powerful tool that lets you automate your software development tasks, like building, testing, and deploying your code. But sometimes, you don’t want these tasks to run automatically on every push. What if you want to run a workflow manually whenever you need it?

This is where workflow_dispatch comes in! Let’s break it down.

---

What is workflow_dispatch?

Think of a workflow in GitHub Actions like a recipe. Normally, the recipe might run automatically every time someone pushes code to your repository.

But with workflow_dispatch, you get a “manual trigger” button. This means you can go to GitHub, click Run workflow, and choose exactly how and when you want it to run.

---

Why is it useful?

1. Manual control: Run workflows only when needed (like deploying your app to production).

2. Custom inputs: You can ask the user for parameters like branch name, microservices to deploy, or environment.

3. Flexible automation: Combine manual control with automation for advanced workflows.

---

How to use workflow_dispatch

Here’s a simple example:

name: Deploy-App

on:
  workflow_dispatch:
    inputs:
      branch:
        description: 'Branch to deploy'
        required: true
        default: 'main'
      deploy-api:
        description: 'Deploy API service'
        required: true
        type: boolean
        default: true

Breaking it down:

• name: Deploy-App → Name of your workflow.

• on: workflow_dispatch → Makes the workflow run manually.

• inputs: → Parameters you can ask the user to provide when triggering the workflow.

  • branch → Which branch should we deploy?

  • deploy-api → Should we deploy the API service? (true/false)

When a developer clicks Run workflow, they’ll see these inputs in GitHub and can set them as needed.

---

How it looks in GitHub

When you open your repository:

1. Go to Actions.

2. Select your workflow (e.g., Deploy-App).

3. Click Run workflow.

4. Fill in the inputs, like branch name or checkboxes for services.

5. Click Run → the workflow starts with the parameters you chose.

---

Advanced Usage

workflow_dispatch works perfectly with matrix builds and multi-service deployments.

For example, you can:

• Select which microservices to build (microservice-a-api, mircoserivce-b-api).

• Choose which markets/regions to deploy (pak, ind, bang ).

• Generate unique Docker image tags based on branch name + date + run number.

• Automatically push your images to Azure Container Registry (ACR).

• Trigger Helm/Flux deployments to update Kubernetes clusters.

All this happens after you click the Run button and provide inputs — giving you total control.

---

Key Points for Students

1. workflow_dispatch = Manual workflow trigger.

2. You can ask for inputs — like a form for your workflow.

3. Useful for deployments or tasks that shouldn’t run on every push.

4. Can be combined with matrix strategy to run multiple jobs in parallel.

5. Perfect for teaching CI/CD because students can see the workflow run step by step after choosing their inputs.

---

Example Use Case

Imagine you have a microservices app with microservice-a-api and mircoserivce-b-api.

• You don’t want to deploy every time you push code.

• You want to deploy only when ready, and maybe only microservice-a-api to uat first.

Using workflow_dispatch, you:

1. Click Run workflow.

2. Select branch = uat.

3. Check only scan-api.

4. Workflow builds Docker image → pushes to registry → updates your Kubernetes cluster.

✅ Control is yours!

---

Conclusion

workflow_dispatch is like having a start button for your automation.

• Developers can trigger workflows on demand.

• Inputs make workflows dynamic and flexible.

• Perfect for deployments, testing, or advanced automation pipelines.