Skip to main content
Mapagam

Working with Workflow Triggers

1. Triggering on Push Events

Event Description Configuration Notes
push Triggers on push to a branch or tag push: Can be filtered by branch, tag, or paths

Example: Basic Push Trigger

on:
  push:
    branches:
      - main
      - "release/*"

Example: Push with Path Filtering

on:
  push:
    paths:
      - "src/**"
      - "package.json"

Example: Push with Tag Filtering

on:
  push:
    tags:
      - "v[0-9]+.*"
Note: The push event does not trigger on tags created by a workflow.

2. Triggering on Pull Requests

Trigger Description Example
pull_request Runs the workflow when a pull request is opened, synchronized, or reopened. 
on:
  pull_request:
    branches: [ main ]
pull_request_target Runs the workflow when a pull request is opened, synchronized, or reopened on the base branch. Unlike pull_request, this runs in the context of the base branch. 
on:
  pull_request_target:
    branches: [ main ]

Example: Trigger on pull request

name: Pull Request Workflow
on:
  pull_request:
    branches: [ main, develop ]
    types: [ opened, synchronize, reopened ]

jobs:
  build:
    runs-on: ubuntu-latest
    steps:
      - name: Checkout code
        uses: actions/checkout@v4
Note: The pull_request event does not run on workflows triggered by pull requests from forks.

Key Points

  • pull_request runs on pull request events in the same repository.
  • pull_request_target runs in the context of the base branch, useful for security-sensitive workflows.
  • Use branches to filter by branch names.
  • Use types to specify the event types (e.g., opened, synchronize).

3. Triggering Manually

Trigger Type Description Configuration
workflow_dispatch Allows manual triggering of a workflow from the GitHub UI or API. 
on:
  workflow_dispatch:
    inputs:
      environment:
        description: 'Environment to deploy to'
        required: true
        default: 'staging'

Example: Manual Trigger with Inputs

name: Manual Deployment
on:
  workflow_dispatch:
    inputs:
      environment:
        description: 'Target environment'
        required: true
        options:
          - staging
          - production
      version:
        description: 'Version to deploy'
        required: false
        default: 'latest'

jobs:
  deploy:
    runs-on: ubuntu-latest
    steps:
      - name: Deploy to ${{ github.event.inputs.environment }}
        run: |
          echo "Deploying version ${{ github.event.inputs.version }} to ${{ github.event.inputs.environment }}"
Note: The workflow_dispatch trigger enables manual execution of workflows via the GitHub UI or API, useful for ad-hoc deployments or testing.

4. Triggering on Schedule

Property Value Description
on.schedule schedule Triggers the workflow at a scheduled time using cron syntax.

Example: Schedule Trigger

on:
  schedule:
    # Runs every day at 12:00 UTC
    - cron: '0 12 * * *'
Note: The cron syntax follows the crontab format, with five fields: minute, hour, day of month, month, and day of week. GitHub Actions uses UTC time zone for scheduling.

Schedule Trigger Details

  • Uses cron syntax for scheduling.
  • Timezone is UTC by default.
  • Supports multiple schedules per workflow.

5. Triggering on Issues

Event Description Configuration
issues.opened Triggers when an issue is opened { "issues": { "types": [ "opened" ] } }
issues.edited Triggers when an issue is edited { "issues": { "types": [ "edited" ] } }
issues.closed Triggers when an issue is closed { "issues": { "types": [ "closed" ] } }
issues.reopened Triggers when a closed issue is reopened { "issues": { "types": [ "reopened" ] } }
issues.assigned Triggers when an issue is assigned to a user { "issues": { "types": [ "assigned" ] } }
issues.unassigned Triggers when an issue is unassigned from a user { "issues": { "types": [ "unassigned" ] } }
issues.labeled Triggers when a label is added to an issue { "issues": { "types": [ "labeled" ] } }
issues.unlabeled Triggers when a label is removed from an issue { "issues": { "types": [ "unlabeled" ] } }

Example: Automatically assign issues to a team member

on:
  issues:
    types: [opened]

jobs:
  assign-issue:
    runs-on: ubuntu-latest
    steps:
      - name: Assign issue to team member
        uses: actions/github-script@v6
        with:
          script: |
            const assignees = ['user1', 'user2'];
            const randomAssignee = assignees[Math.floor(Math.random() * assignees.length)];
            github.rest.issues.addAssignees({
              owner: context.repo.owner,
              repo: context.repo.repo,
              issue_number: context.issue.number,
              assignees: [randomAssignee]
            });

Example: Comment on issue when labeled

on:
  issues:
    types: [labeled]

jobs:
  comment-on-label:
    runs-on: ubuntu-latest
    steps:
      - name: Add comment to labeled issue
        uses: actions/github-script@v6
        with:
          script: |
            const label = context.payload.label.name;
            github.rest.issues.createComment({
              owner: context.repo.owner,
              repo: context.repo.repo,
              issue_number: context.issue.number,
              body: `This issue has been labeled as "${label}".`
            });
Note: The issues event does not support filtering by label or assignee. Use github-script or similar actions to implement custom filtering logic.

6. Triggering on Releases

Trigger Description Example
release Triggers on release events (created, edited, deleted, published) 
on:
  release:
    types: [created, published]

Example: Release Trigger Configuration

on:
  release:
    types: [published]
jobs:
  deploy:
    runs-on: ubuntu-latest
    steps:
      - name: Deploy to production
        run: echo "Deploying release v${{ github.event.release.tag_name }}"
Note: The release trigger only works for GitHub Releases, not Git tags.

7. Triggering on Repository Events

Event Description Notes
push Triggers on git push to a branch or tag Includes new commits, tags, and branch changes
pull_request Triggers on pull request creation, update, or merge Can filter by branch, status (open/closed), and action
issues Triggers on issue creation, update, or deletion Supports actions like opened, edited, closed, assigned
issue_comment Triggers on comment creation or update on an issue Useful for automating responses to comments
create Triggers on creation of a branch or tag Useful for initializing workflows when new branches are created
delete Triggers on deletion of a branch or tag Can be used to clean up resources or notify on deletion
release Triggers on release creation, update, or deletion Supports actions like published, edited, deleted
workflow_run Triggers when another workflow completes successfully or fails Allows workflows to be chained together

Example: Triggering on Push to Main Branch

on:
  push:
    branches:
      - main

Example: Triggering on Pull Request

on:
  pull_request:
    types: [opened, synchronize, closed]
Note: The pull_request event does not trigger on every pull request update. It only triggers when the PR is opened, synchronized (updated), or closed.

8. Triggering on Forks

By default, workflows triggered by pull_request events do not run on forks. This is a security measure to prevent unauthorized code execution.

Event Description Notes
pull_request Triggers on pull request creation or updates Does not run on forks unless configured otherwise
pull_request_target Triggers on pull request creation or updates, but runs in the context of the base repository Runs on forks if configured; can access secrets and run with elevated permissions

Example: Using pull_request_target to run workflows on forks

on:
  pull_request_target:
    branches: [ main ]
    types: [ opened, synchronize ]

jobs:
  security-check:
    runs-on: ubuntu-latest
    steps:
      - name: Checkout code
        uses: actions/checkout@v4
        with:
          ref: ${{ github.event.pull_request.head.sha }}

      - name: Run security scan
        run: |
          echo "Running security checks on forked PR"
Note: When using pull_request_target, the workflow runs in the context of the base repository, which means it has access to secrets and can make changes to the base branch. This is useful for workflows that need to interact with the base repository, such as code review or security scanning.
Warning: Be cautious when using pull_request_target on forks, as it can lead to unintended consequences if the forked repository contains malicious code. Ensure that workflows are properly secured and validated.

9. Using Activity Types

Activity Type Description Trigger Events
push Triggers on git push to a branch or tag push
pull_request Triggers on pull request creation, update, or merge pull_request
schedule Triggers based on a cron schedule schedule
workflow_dispatch Allows manual triggering of the workflow workflow_dispatch
repository_dispatch Triggers when a repository dispatch event is sent repository_dispatch

Example: Using push activity type

on:
  push:
    branches: [ main ]
    paths:
      - 'src/**'

Example: Using pull_request activity type

on:
  pull_request:
    types: [ opened, synchronize, closed ]

Example: Using schedule activity type

on:
  schedule:
    - cron: '0 0 * * *' # Runs daily at midnight

10. Combining Multiple Triggers

GitHub Actions allows combining multiple triggers using the on keyword with a list of events or a combination of event types and conditions.

Trigger Description Example
push Triggers on git push to a branch or tag 
on:
  push:
    branches: [ main ]
pull_request Triggers on pull request creation or updates 
on:
  pull_request:
    branches: [ main ]
schedule Triggers on a cron schedule 
on:
  schedule:
    - cron: '0 0 * * *'
workflow_dispatch Allows manual triggering of the workflow 
on:
  workflow_dispatch:
    inputs:
      environment:
        description: 'Environment to deploy to'
        required: true

Example: Combining push and pull_request triggers

on:
  push:
    branches: [ main, develop ]
  pull_request:
    branches: [ main ]

jobs:
  build:
    runs-on: ubuntu-latest
    steps:
      - name: Checkout code
        uses: actions/checkout@v4

Example: Using schedule and workflow_dispatch together

on:
  schedule:
    - cron: '0 0 * * *'
  workflow_dispatch:
    inputs:
      debug_mode:
        description: 'Enable debug mode'
        type: boolean
        default: false

jobs:
  cleanup:
    runs-on: ubuntu-latest
    steps:
      - name: Cleanup old artifacts
        if: ${{ github.event.inputs.debug_mode == 'true' }}
        run: echo "Debug mode enabled"

11. Filtering by Branches and Tags

Filter Type Example Description
branches main Triggers workflow on pushes to the main branch
branches feature/* Triggers workflow on pushes to any branch matching the pattern feature/*
branches release/v* Triggers workflow on pushes to any branch starting with release/v
tags v* Triggers workflow on pushes to any tag matching the pattern v*
tags v1.0.* Triggers workflow on pushes to any tag matching the pattern v1.0.*

Example: Filtering by Branches

on:
  push:
    branches:
      - main
      - feature/*

Example: Filtering by Tags

on:
  push:
    tags:
      - v*

12. Using Webhook Events

Event Description Trigger
push Triggers on git push to a branch or tag on.push
pull_request Triggers on pull request creation, update, or merge on.pull_request
issues Triggers on issue creation, update, or deletion on.issues
release Triggers on release creation or update on.release

Example: Using push event

on:
  push:
    branches: [ main ]
    paths: [ 'src/**' ]

jobs:
  build:
    runs-on: ubuntu-latest
    steps:
      - name: Checkout code
        uses: actions/checkout@v4

Example: Using pull_request event

on:
  pull_request:
    types: [ opened, synchronize, closed ]

jobs:
  test:
    runs-on: ubuntu-latest
    steps:
      - name: Run tests
        run: npm test

Was this article helpful?

Related Cheat Sheets