How to trigger a step manually with GitHub Actions

Manual triggering of workflows in GitHub Actions can be achieved through several methods, primarily using the workflow_dispatch event. Below, I will detail how to set up and use this feature.

1. Update the workflow file to enable manual triggering

First, you need to add the workflow_dispatch event to your workflow file to enable manual triggering. This can be done by editing the YAML workflow file located in your repository's .github/workflows directory. For example, if you have a workflow file named ci.yml, you can modify it as follows:

yaml
name: CI

on:
  push:
    branches:
      - main
  pull_request:
    branches:
      - main
  workflow_dispatch:  # Add this line to enable manual triggering

jobs:
  build:
    runs-on: ubuntu-latest

    steps:
    - uses: actions/checkout@v2
    - name: Run a one-line script
      run: echo Hello, world!

In the above example, workflow_dispatch: has been added under the on key. This means the workflow can now be triggered automatically when pushing to the main branch or manually initiated.

2. Manually trigger the workflow via GitHub UI

After updating and committing the workflow file to your repository, you can manually trigger the workflow through the GitHub UI.

Follow these steps:

1. Log in to your GitHub account and navigate to the repository containing the workflow.
2. Click the 'Actions' tab to enter the GitHub Actions interface.
3. On the left, you will see different workflows; select the one you want to manually trigger.
4. At the top of the workflow, you will see a 'Run workflow' button; click it.
5. If needed, select a branch, then click 'Run workflow' to trigger the workflow.

3. Use additional input options

The workflow_dispatch event also supports defining input parameters, allowing you to provide additional options when manually triggering the workflow. For example:

yaml
on:
  workflow_dispatch:
    inputs:
      logLevel:
        description: 'Log level'
        required: true
        default: 'warning'
      environment:
        description: 'Environment name'
        required: true

With this setup, when you trigger the workflow via the GitHub UI, you will be prompted to fill in additional options such as the log level and environment name.

Summary

By adding the workflow_dispatch event to your workflow file and using the GitHub UI, you can manually trigger GitHub Actions workflows. This method is useful for scenarios requiring manual control or running workflows under specific conditions, such as deploying to production without code commits.

1. Using workflow_dispatch event

GitHub allows you to manually trigger workflows by using the workflow_dispatch event in your workflow file. First, you need to specify workflow_dispatch as the trigger event. For example:

yaml
name: Manual Trigger Example

on:
  workflow_dispatch:
    inputs:
      logLevel:
        description: 'Log level'
        required: true
        default: 'warning'
      tags:
        description: 'Comma separated project tags'

jobs:
  build:
    runs-on: ubuntu-latest
    steps:
      - name: Checkout
        uses: actions/checkout@v2
      - name: Run a one-line script
        run: echo Hello, world!
      - name: Run a multi-line script
        run: |
          echo Add other actions to build,
          echo test, and deploy your project.

On the main page of your GitHub repository, click the 'Actions' tab above the repository name, select the workflow you want to manually trigger, and you will see a 'Run workflow' button on the right. Click this button, select a branch, and fill in any required input parameters (if the workflow has defined inputs), then click 'Run workflow' to trigger execution.

2. Using repository_dispatch event

Another method is using the repository_dispatch event, which allows external events to trigger GitHub Actions. First, add repository_dispatch as the trigger event in your workflow file:

yaml
name: Repository Event Trigger Example

on:
  repository_dispatch:
    types: [build]

jobs:
  build:
    runs-on: ubuntu-latest
    steps:
      - name: Checkout
        uses: actions/checkout@v2
      - name: Run a script
        run: echo "This workflow was triggered by a repository dispatch event."

Then, you can trigger the workflow using the GitHub API by sending a POST request to the following URL:

shell
https://api.github.com/repos/<owner>/<repo>/dispatches

You need to provide a valid GitHub token and include the event type and client payload in the request, for example:

bash
curl -X POST https://api.github.com/repos/<owner>/<repo>/dispatches \
-H 'Authorization: token YOUR_GITHUB_TOKEN' \
-H 'Accept: application/vnd.github.v3+json' \
-d '{"event_type": "build", "client_payload": {"env": "production"}}'

Summary

Manual triggering of GitHub Actions provides flexibility, allowing developers to start workflows as needed. By configuring workflow_dispatch or repository_dispatch events, developers can easily run CI/CD pipelines without code changes. This is particularly useful when additional control over workflow execution is required, such as deploying to production or running specific tests.

Manual triggering of GitHub Actions workflows can be achieved through several methods. I will detail two common approaches: using workflow_dispatch and repository_dispatch events.

1. Using workflow_dispatch event

workflow_dispatch is a straightforward method that allows users to manually run workflows from the GitHub repository's Actions tab or via the GitHub API. To use this method, you need to explicitly declare workflow_dispatch in your workflow file.

Step 1: Add workflow_dispatch: to your workflow file (typically located in .github/workflows/ directory as a YAML file). For example:

yaml
name: Manual Workflow
on:
  workflow_dispatch:
    # Optionally, define inputs here:
    inputs:
      logLevel:
        description: 'Log level'
        required: true
        default: 'warning'
jobs:
  build:
    runs-on: ubuntu-latest
    steps:
      - name: Check out repository
        uses: actions/checkout@v2
      - name: Run a one-line script
        run: echo "Manual dispatch event triggered!"

Step 2: Commit and push the changes to your repository.

Step 3: On the GitHub repository page, click the 'Actions' tab, select the relevant workflow from the left, and click the 'Run workflow' button in the top-right corner. Select a branch and fill in any input parameters (if applicable), then click 'Run workflow' to trigger the workflow.

2. Using repository_dispatch event

Another option is using repository_dispatch event. This method allows more customization and integration with external systems because it triggers workflows by sending a POST request to the GitHub API.

Step 1: Declare repository_dispatch as the trigger condition in your workflow file:

yaml
name: API Triggered Workflow
on:
  repository_dispatch:
    types: [build-event]
jobs:
  build:
    runs-on: ubuntu-latest
    steps:
      - name: Check out repo
        uses: actions/checkout@v2
      - name: Run a script
        run: echo "Repository dispatch event triggered!"

Step 2: Use curl or another tool to send a POST request to the GitHub API to trigger the workflow. You need to generate a personal access token (with repo and workflow permissions) and use it in the request:

bash
curl -X POST -H "Accept: application/vnd.github.v3+json" \
    -H "Authorization: token YOUR_PERSONAL_ACCESS_TOKEN" \
    https://api.github.com/repos/USERNAME/REPOSITORY_NAME/dispatches \
    -d '{"event_type": "build-event"}'

Note: In this request, event_type must match the type defined in your workflow file.

Summary

Both methods provide developers and project maintainers with greater flexibility to manually trigger workflows. With workflow_dispatch, you can simply trigger workflows from the GitHub UI, while repository_dispatch offers API-triggered execution, enabling integration with external systems and automation of workflow execution.