Manually triggering GitHub Actions

Sometimes there are scenarios where you might need to manually trigger a GitHub Actions workflow. This guide explores how to set up and use manual triggers for GitHub Actions, which can be particularly useful for deployments, manual tests, or any process where you want more control over when a particular action should be run.

Understanding manual triggers in GitHub Actions

Manual triggers in GitHub Actions allow workflows to be started manually from the GitHub UI or through an API call. This feature is useful to supplement automated triggers, such as when you need to control when specific actions are taken, like deploying to a production environment after a manual review.

GitHub workflow dispatch event

The primary way to manually trigger a GitHub Action is through the workflow_dispatch event. This event allows you to provide inputs when triggering a workflow, giving you flexibility in how the workflow should behave for that particular run.

Setting up a manual trigger

Modifying the workflow file

To enable manual triggers, you need to modify your workflow file (usually found in .github/workflows) to include the workflow_dispatch trigger:

name: Manually Triggered Workflow
on:
  workflow_dispatch:
    inputs:
      logLevel:
        description: 'Log level'
        required: true
        default: 'warning'
      environment:
        description: 'Environment to deploy'
        required: false
        default: 'staging'
jobs:
  build:
    runs-on: ubuntu-latest
    steps:
      - name: Checkout
        uses: actions/checkout@v2
      - name: Run a one-line script
        run: echo "Hello, ${{ github.event.inputs.environment }}!"

Adding the workflow_dispatch field, along with the inputs logLevel and environment will allow you to manually specify these inputs when triggering the workflow manually. In this case when you trigger the workflow in the UI, it will prompt you to specify values for these two inputs.

Details of the workflow_dispatch event

• Inputs: You can define inputs that users can set when they trigger the workflow. These inputs can be accessed within the workflow using the github.event.inputs context.

Accessing the workflow

Once the workflow_dispatch is added to your workflow file:

1. Go to the Actions tab of your GitHub repository.
2. Select the workflow you want to run.
3. Click the "Run workflow" dropdown.
4. Fill in the inputs (if any) and click "Run workflow".

This initiates the workflow manually with the parameters you've provided.

Practical examples

Example 1: Manual deployment trigger

This workflow allows manual triggers for deployments, with the user specifying which environment to deploy to:

name: Manual Deployment
on:
  workflow_dispatch:
    inputs:
      environment:
        description: 'Target environment'
        required: true
        default: 'development'
jobs:
  deploy:
    runs-on: ubuntu-latest
    steps:
      - name: Checkout code
        uses: actions/checkout@v2
      - name: Deploy
        run: ./deploy.sh ${{ github.event.inputs.environment }}
        env:
          DEPLOY_ENV: ${{ github.event.inputs.environment }}

In this setup, the deploy.sh script would handle the deployment based on the environment input provided at the workflow's runtime.

Example 2: Manual test execution

This example allows for manual triggering of tests, where parameters can specify the test suite or tags:

name: Manual Test Execution
on:
  workflow_dispatch:
    inputs:
      testType:
        description: 'Type of tests to run'
        required: true
        default: 'integration'
jobs:
  test:
    runs-on: ubuntu-latest
    steps:
      - name: Checkout code
        uses: actions/checkout@v2
      - name: Run Tests
        run: npm run test -- --type ${{ github.event.inputs.testType }}

For further reading see the official GitHub documentation.