Master GitHub Actions Triggers

Build a trigger playground repo with push, PR, and manual workflow triggers.

Introduction

30 Second Summary

Every time you push code to a team project, something needs to decide whether to run tests, deploy updates, or notify your teammates. That decision starts with a trigger.

In this project, you will build a reference repository containing multiple GitHub Actions workflow files, each demonstrating a different way to trigger automated pipelines.

What You'll Build

A "Trigger Playground" repository with YAML workflow files that fire on push events, pull request events, and manual dispatch.

By the end of this project, you'll have:

  • A public GitHub repository with multiple workflow YAML files demonstrating different trigger types.
  • Real-time observations of each trigger firing on the GitHub Actions tab.
  • A reusable reference repository you can copy trigger patterns from in future projects.
  • Secret Mission: Add a scheduled cron trigger and combine multiple trigger types into a single workflow file.

Are there any prerequisites?

You need basic Git knowledge (commits, branches, push, and pull), a GitHub account, and Git installed on your machine. No CI/CD experience is required.

Set Up Your Repository

GitHub Actions workflows need a home. Every workflow file lives inside a specific directory in your repository called .github/workflows/.

In this step, you will create a public repository on GitHub, clone it to your machine, and set up the directory structure that GitHub Actions expects.

In this step, get ready to:
  • Create a public repository on GitHub.
  • Clone the repository to your local machine.
  • Set up the .github/workflows/ directory.
Create a new public repository on GitHub
  • Open your browser and go to github.com.
  • Sign in to your GitHub account.
  • In the upper-right corner of the page, click the + dropdown menu.
  • Click New repository.
  • In the Repository name box, type actions-trigger-playground.
  • Select Public for the repository visibility.
  • Select Add a README file.
  • Click Create repository.

Why public?

GitHub Actions is free and unlimited on public repositories. A public repo means you can trigger as many workflow runs as you want without worrying about usage limits.

GitHub redirects you to your new repository page. You should see the repository name actions-trigger-playground at the top and a single README.md file listed.

Don't see your repository?

Make sure you clicked Create repository at the bottom of the form. If the page still shows the form, scroll down to find the button.

Help me create my GitHub repository.

Clone the repository to your local machine

Now you need a local copy of this repository so you can create workflow files on your machine and push them up.

  • Open your terminal by pressing Cmd+Space (macOS) or the Windows key (Windows) to open your search bar.
  • Type Terminal (macOS) or Git Bash (Windows) and press Enter to open it.
  • Move to your Desktop by running this command:
cd ~/Desktop
  • Clone your repository by running this command:
git clone https://github.com/[[GITHUB_USERNAME="your-github-username"]]/actions-trigger-playground.git

Where do I find the clone URL?

On your repository page, click the green Code button. Copy the HTTPS URL shown there and paste it in place of the full command above.

  • Move into the cloned repository folder by running:
cd actions-trigger-playground

You should see your terminal prompt change to show actions-trigger-playground as the current directory.

Seeing 'repository not found'?

Double-check that you replaced the username in the URL with your actual GitHub username. The repository must also be the one you just created (not a typo in the name).

If you see an authentication prompt, make sure you are signed in to Git with the same account that owns the repository.

Help me clone my GitHub repository.

Create the workflows directory structure

GitHub Actions only recognizes workflow files stored in the .github/workflows/ directory. You need to create this folder structure before adding any workflow files.

  • Create the workflows directory by running this command:
mkdir -p .github/workflows

What does this command do?

The -p flag tells mkdir to create parent directories as needed. It creates both .github/ and workflows/ inside it in one command.

The leading dot in .github makes it a hidden directory. This is a GitHub convention for storing repository configuration.

  • Confirm the directory exists by running:
ls .github

You should see workflows listed in the output.

Not seeing the workflows folder?

Make sure you ran the mkdir command from inside the actions-trigger-playground folder. Run pwd to check your current location.

Help me create the .github/workflows directory.

Your repository is set up and ready. Next up, you will create your first workflow file and watch it trigger automatically when you push code.

Create a Push Trigger Workflow

Every GitHub Actions workflow needs a trigger. The trigger tells GitHub exactly when to run the workflow's jobs.

In this step, you'll create your first workflow file with a push trigger. This will fire every time you push changes to the main branch, but only when specific file paths are modified.

In this step, get ready to:
  • Create a push trigger workflow file with branch and path filters.
  • Add project files that match the path filter.
  • Push everything to GitHub and observe the workflow execute on the Actions tab.
Create the push trigger workflow file

The on key in a workflow YAML file defines which events cause the workflow to run. You'll use the push event with filters to control exactly which pushes trigger it.

  • In your text editor, create a new file at .github/workflows/push-trigger.yml inside your actions-trigger-playground folder, then paste the following code:
name: Push Trigger Demo

on:
  push:
    branches:
      - main
    paths:
      - 'src/**'
      - '*.js'
      - '!docs/**'

jobs:
  build:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v6
      - name: Display trigger info
        run: |
          echo "Workflow triggered by: ${{ github.event_name }}"
          echo "Branch: ${{ github.ref_name }}"
          echo "Commit SHA: ${{ github.sha }}"
          echo "Commit message: ${{ github.event.head_commit.message }}"

What does this workflow do?

The on.push section defines when this workflow triggers. It only fires on pushes to main that include changes in files matching the path filters.

  • branches: - main restricts the trigger to the main branch only. Pushes to other branches are ignored.
  • paths: - 'src/**' matches any file inside the src/ directory. '*.js' matches JavaScript files in the root.
  • '!docs/**' uses the ! prefix to exclude the docs/ directory. Changes only to docs will not trigger the workflow.
  • The jobs section runs on ubuntu-latest, checks out the code, and prints information about what triggered the run.
  • Save push-trigger.yml.

File not saving in the right place?

Make sure the file is inside .github/workflows/ and not directly in your repository root. The file must end with .yml or .yaml. GitHub will not detect workflow files stored anywhere else.

help me figure out why GitHub isn't detecting my workflow file

✔️ Awesome, I've got everything!

Great. Double check you've saved your file in the correct location.

ⓧ I'd like to double check the full code

name: Push Trigger Demo

on:
  push:
    branches:
      - main
    paths:
      - 'src/**'
      - '*.js'
      - '!docs/**'

jobs:
  build:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v6
      - name: Display trigger info
        run: |
          echo "Workflow triggered by: ${{ github.event_name }}"
          echo "Branch: ${{ github.ref_name }}"
          echo "Commit SHA: ${{ github.sha }}"
          echo "Commit message: ${{ github.event.head_commit.message }}"
Add project files to match the path filter

Your path filter includes src/**, so you need a file inside a src/ directory to trigger the workflow when you push. You'll also create a README.md to document the repository.

  • Create the src directory by running this command in your terminal from the actions-trigger-playground folder:
mkdir src
  • In your text editor, create a new file at src/app.js and paste the following code:
// Simple app file to demonstrate path-based triggers
console.log("Hello from the Actions Trigger Playground!");
console.log("Edit this file and push to trigger the push workflow.");

Why this file?

This file lives inside src/, which matches the 'src/**' path filter in your workflow. When you push this file to main, GitHub compares the changed paths against your filters and triggers the workflow.

  • Save src/app.js.
  • Confirm the file exists by running:
ls src

You should see app.js in the output.

  • Now create a README.md file in the root of your actions-trigger-playground folder, then paste the following:
# Actions Trigger Playground

A reference repository demonstrating different GitHub Actions workflow triggers.

## Workflows

| Workflow | Trigger | File |
|---------|---------|------|
| Push Trigger Demo | Push to main (filtered by path) | `.github/workflows/push-trigger.yml` |
| PR Trigger Demo | Pull request events | `.github/workflows/pr-trigger.yml` |
| Manual Trigger Demo | Manual dispatch with inputs | `.github/workflows/manual-trigger.yml` |

## How to Use

1. Push changes to `src/` or `*.js` files to trigger the push workflow
2. Open a PR targeting `main` to trigger the PR workflow
3. Go to Actions tab and click "Run workflow" on Manual Trigger Demo

What does this README do?

This serves as documentation for your Trigger Playground repository. It lists all the workflows you'll build across this project, making the repo a handy reference you can come back to later.

  • Save README.md.

Seeing issues with file creation?

Make sure src/app.js is inside the src/ folder (not the root). Make sure README.md is in the repository root (same level as the .github folder).

help me check my file structure is correct

Push to GitHub and verify the workflow runs

Now for the exciting part. You'll push all your files to main and watch GitHub automatically detect the push event, match it against your path filter, and execute the workflow.

  • Stage, commit, and push all your changes by running these commands:
git add .
git commit -m "Add push trigger workflow and project files"
git push origin main

What do these commands do?

  • git add . stages all new and changed files for commit.
  • git commit -m creates a snapshot of your staged changes with a descriptive message.
  • git push origin main sends your commit to GitHub on the main branch. This push triggers the workflow because src/app.js matches the path filter.
  • Open your browser and navigate to your actions-trigger-playground repository on GitHub.
  • Click the Actions tab in the repository header.

You should see a workflow run titled with your commit message. A green checkmark means the run completed successfully.

  • Click on the workflow run to see the details.
  • Click the build job, then expand the Display trigger info step to see the echo output.

You should see the event name, branch, commit SHA, and your commit message printed in the logs.

Don't see the workflow run?

Make sure push-trigger.yml is inside .github/workflows/ and was included in your push. Check that the YAML indentation is correct. Even a single misaligned space can break the file.

Also verify that you pushed a file matching the path filter (src/app.js satisfies src/**). If you only pushed the workflow file itself without any matching path, the workflow will not trigger.

help me debug why my push trigger workflow didn't run

Why use path filters?

Path filters let you avoid running expensive CI/CD pipelines on every single push. In a real project, you might only want tests to run when source code changes, not when someone edits documentation.

The !docs/** exclusion pattern demonstrates this. Changes limited to a docs/ folder would skip the workflow entirely, saving runner minutes and speeding up your team's feedback loop.

Your first workflow is live. Next up, you'll create a workflow that triggers automatically when someone opens a pull request.

Create a Pull Request Trigger Workflow

Your push trigger workflow is running and filtering events by branch and file path. Now it's time to respond to a completely different event: pull requests.

Pull requests are where teams review code before merging it into the main branch. A workflow that runs automatically on every PR gives you instant feedback without anyone needing to remember to trigger it. In this step, you'll create a workflow that fires whenever someone opens or updates a pull request.

In this step, get ready to:
  • Create a pull request trigger workflow file.
  • Open a pull request to test the trigger.
  • Observe the workflow running as a status check on your PR.
Write the pull request trigger workflow

The pull_request event fires whenever someone opens, updates, or reopens a pull request targeting a specific branch. You can filter by activity type so the workflow only runs on the events you care about.

  • In your text editor, create a new file called pr-trigger.yml inside the .github/workflows/ folder.
  • Add the following workflow definition to the file:
name: PR Trigger Demo

on:
  pull_request:
    branches:
      - main
    types:
      - opened
      - synchronize
      - reopened

jobs:
  review:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v6
      - name: Display PR info
        run: |
          echo "Workflow triggered by: ${{ github.event_name }}"
          echo "PR Title: ${{ github.event.pull_request.title }}"
          echo "PR Author: ${{ github.event.pull_request.user.login }}"
          echo "Source Branch: ${{ github.head_ref }}"
          echo "Target Branch: ${{ github.base_ref }}"

What does this workflow do?

  • branches: - main means this workflow only runs for PRs that target the main branch. PRs targeting other branches are ignored.
  • types: filters which pull request activities trigger the workflow. opened fires when the PR is first created. synchronize fires when new commits are pushed to the PR branch. reopened fires when a closed PR is reopened.
  • The job prints useful PR context like the title, author, source branch, and target branch using GitHub Actions context variables.
  • Save pr-trigger.yml.
  • Push the new workflow file to main by running these commands in your terminal:
git add .github/workflows/pr-trigger.yml
git commit -m "Add PR trigger workflow"
git push

Why doesn't the push trigger fire here?

Your push-trigger workflow only runs for changes to src/** or *.js files. The new .github/workflows/pr-trigger.yml path doesn't match those filters, so the push trigger stays quiet.

Push rejected or authentication error?

  • Make sure you're on the main branch. Run git branch to check.
  • If Git asks for credentials, confirm you're using a personal access token or SSH key that has write access to the repository.

Help me fix a git push authentication error

Create a branch and open a pull request

To trigger the PR workflow, you need an actual pull request. You'll create a new branch, make a small change, push it, and then open a PR on GitHub.

  • Create a new branch and switch to it by running this command:
git checkout -b feature/test-pr-trigger
  • Open src/app.js in your text editor and add this line at the bottom of the file:
// This change will trigger the PR workflow when we open a pull request
console.log("Testing the PR trigger!");
  • Save src/app.js.
  • Commit and push the new branch by running these commands:
git add src/app.js
git commit -m "Test PR trigger"
git push -u origin feature/test-pr-trigger

What does the -u flag do?

The -u flag (short for --set-upstream) links your local branch to the remote branch on GitHub. After setting this once, future pushes on this branch only need git push with no extra arguments.

  • Open your browser and go to your actions-trigger-playground repository on GitHub.
  • You should see a banner at the top saying your branch had recent pushes. Click the Compare & pull request button.
  • Leave the base branch as main and the compare branch as feature/test-pr-trigger.
  • Enter a title for your pull request, for example Test PR trigger workflow.
  • Click Create pull request.

Don't see the Compare & pull request banner?

  • The banner disappears after a few minutes. Click the Pull requests tab at the top of your repository, then click New pull request.
  • Select main as the base branch and feature/test-pr-trigger as the compare branch.

Help me create a pull request on GitHub

Observe the PR workflow running

The moment you created the pull request, GitHub detected that it matched your PR trigger workflow. The workflow should already be running.

  • On your pull request page, scroll down to the status checks section near the bottom. You should see PR Trigger Demo with a yellow spinning icon (in progress) or a green checkmark (complete).
  • Click Details next to the status check to view the workflow run logs.
  • Expand the Display PR info step in the logs. You should see your PR title, your GitHub username, the source branch feature/test-pr-trigger, and the target branch main printed in the output.

Where else can I see this run?

You can also find it under the Actions tab of your repository. The run will be labeled with your PR title and show pull_request as the event type.

No status check appearing on the PR?

  • Confirm that pr-trigger.yml is on the main branch, not on your feature branch. Workflow files must exist on the default branch to respond to events.
  • Check that the branches: filter in your YAML says - main. If the PR targets a different branch, the workflow won't trigger.
  • Open the Actions tab directly to check if the run appears there with an error.

Help me debug why my PR workflow isn't running

✔️ Awesome, I've got everything!

Great. Double check you've saved your file and that the workflow ran successfully.

ⓧ I'd like to double check the full code

name: PR Trigger Demo

on:
  pull_request:
    branches:
      - main
    types:
      - opened
      - synchronize
      - reopened

jobs:
  review:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v6
      - name: Display PR info
        run: |
          echo "Workflow triggered by: ${{ github.event_name }}"
          echo "PR Title: ${{ github.event.pull_request.title }}"
          echo "PR Author: ${{ github.event.pull_request.user.login }}"
          echo "Source Branch: ${{ github.head_ref }}"
          echo "Target Branch: ${{ github.base_ref }}"

You've now seen how CI/CD pipelines can give instant feedback on every pull request. Next up, you'll create a workflow that runs only when you decide to trigger it manually.

Create a Manual Dispatch Trigger Workflow

Your PR trigger workflow fired automatically the moment you opened a pull request. You now have two workflows that respond to code changes without any manual intervention.

Sometimes you need a workflow that runs only when you decide. The workflow_dispatch trigger lets you start a workflow on demand from the GitHub Actions tab, complete with custom input fields you define in YAML.

In this step, get ready to:
  • Create .github/workflows/manual-trigger.yml with custom input definitions.
  • Push the workflow to main and trigger it manually from the Actions tab.
  • Verify that custom input values appear in the workflow run logs.
Create the manual dispatch workflow file

The workflow_dispatch event turns your workflow into an on-demand tool. You define input fields in the YAML file, and GitHub Actions renders them as a form in the Actions tab.

  • Create a new file at .github/workflows/manual-trigger.yml in your text editor with the following content:
name: Manual Trigger Demo

on:
  workflow_dispatch:
    inputs:
      environment:
        description: 'Environment to deploy to'
        required: true
        type: choice
        options:
          - development
          - staging
          - production
      log_level:
        description: 'Log level'
        required: true
        default: 'info'
        type: choice
        options:
          - debug
          - info
          - warning
          - error

jobs:
  deploy:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v6
      - name: Display inputs
        run: |
          echo "Deploying to: ${{ inputs.environment }}"
          echo "Log level: ${{ inputs.log_level }}"
          echo "Triggered by: ${{ github.actor }}"
          echo "Run number: ${{ github.run_number }}"

What does this code do?

The on: workflow_dispatch block tells GitHub this workflow can be triggered manually from the UI. The inputs section defines form fields that appear when you click the Run workflow button.

  • type: choice creates a dropdown menu with predefined options. The learner picks from the list instead of typing freeform text.
  • default: 'info' pre-selects a value so the field is not blank when the form appears.
  • ${{ inputs.environment }} and ${{ inputs.log_level }} read the values the user chose at dispatch time.
  • ${{ github.actor }} prints who triggered the run, and ${{ github.run_number }} gives the sequential run count.
  • Save manual-trigger.yml.

Why does workflow_dispatch need to be on the default branch?

GitHub only shows the Run workflow button for workflow files that exist on the default branch. If you push a workflow_dispatch workflow to a feature branch, the button will not appear until the file reaches main.

Seeing a YAML syntax error?

YAML is strict about indentation. Make sure each nested level uses exactly two spaces (not tabs). The options list items should align directly under one another.

help me fix a YAML indentation error in my workflow file

✔️ Awesome, I've got everything!

Great. Make sure you have saved the file before moving on.

ⓧ I'd like to double check the full code

name: Manual Trigger Demo

on:
  workflow_dispatch:
    inputs:
      environment:
        description: 'Environment to deploy to'
        required: true
        type: choice
        options:
          - development
          - staging
          - production
      log_level:
        description: 'Log level'
        required: true
        default: 'info'
        type: choice
        options:
          - debug
          - info
          - warning
          - error

jobs:
  deploy:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v6
      - name: Display inputs
        run: |
          echo "Deploying to: ${{ inputs.environment }}"
          echo "Log level: ${{ inputs.log_level }}"
          echo "Triggered by: ${{ github.actor }}"
          echo "Run number: ${{ github.run_number }}"
Push the workflow to GitHub
  • Stage, commit, and push the new workflow file by running these commands:
git add .github/workflows/manual-trigger.yml
git commit -m "Add manual dispatch workflow"
git push origin main
  • Return to your repository on GitHub.
  • Click the Actions tab.
  • In the left sidebar, confirm you see Manual Trigger Demo listed as a workflow.

Don't see Manual Trigger Demo in the sidebar?

Make sure your git push completed successfully. Check the terminal output for errors. The workflow only appears in the sidebar after the file is on the main branch.

help me troubleshoot why my workflow is not showing up in the Actions tab

Run the workflow manually from the Actions tab

With the file on main, the Run workflow button is now available. This button only appears for workflows that use the workflow_dispatch event.

  • In the left sidebar of the Actions tab, click Manual Trigger Demo.
  • Above the list of workflow runs, click the Run workflow button.
  • A dropdown appears with input fields. Select production from the Environment to deploy to dropdown.
  • Select debug from the Log level dropdown.
  • Click the green Run workflow button at the bottom of the dropdown.

A new workflow run appears in the list. Click on it to open the run details.

  • Click the deploy job in the left panel.
  • Expand the Display inputs step.
  • Confirm you see the values you chose printed in the logs: Deploying to: production and Log level: debug.

What should I see?

The run logs show four lines of output. The first two display the input values you selected. The third shows your GitHub username (the actor who triggered the run). The fourth shows the sequential run number.

Run workflow button not appearing?

The Run workflow button only shows for workflows that use workflow_dispatch and exist on the default branch. Double-check that your file is on main and that on: workflow_dispatch is at the top of the file with correct indentation.

help me figure out why the Run workflow button is missing

Secret mission

Schedule Trigger and Multi-Trigger Workflow

Ready to level up? In this secret mission, you will combine multiple trigger types into a single workflow file and add a cron-based schedule trigger. This requires you to understand how triggers compose together and how to use conditional logic to respond differently depending on what fired the workflow.

Clean Up Your Resources

Clean Up Your Resources

This project runs entirely on GitHub Actions with a public repository, so there are no ongoing costs. Decide whether to keep your resources running, pause them to come back later, or delete them entirely.

Resources you used:

  • GitHub repository actions-trigger-playground.
  • Local project folder actions-trigger-playground on your Desktop.
  • Workflow files in .github/workflows/ (stored inside the repository).

Keep everything running

No action needed. Choose this if you want to keep your trigger playground as a reference repository you can copy from in future projects.

  • Your workflows remain active. The scheduled workflow (multi-trigger.yml) will run daily at midnight UTC, but this costs nothing on a public repository.
  • GitHub automatically disables scheduled workflows on public repositories after 60 days of inactivity. If you stop pushing to the repo, the schedule will turn itself off.
  • Your local folder stays on your Desktop.

Pause - I'll come back to this later

Disable the scheduled workflow so it stops running while you are away. You can re-enable it any time.

  • Open your actions-trigger-playground repository on GitHub.
  • Click the Actions tab.
  • In the left sidebar, click Multi-Trigger Demo.
  • Click the ... dropdown menu and select Disable workflow.
  • Repeat for any other workflows you want to pause.
  • Your local folder stays on your Desktop for when you return.

Delete - I don't want to use this again

Remove the GitHub repository and the local project folder completely.

  • Delete the GitHub repository:
  • Open your actions-trigger-playground repository on GitHub.
  • Click Settings in the repository navigation bar.
  • Scroll down to the Danger Zone section.
  • Click Delete this repository.
  • Click I want to delete this repository, read the warnings, then click I have read and understand these effects.
  • Type the repository name to confirm, then click Delete this repository.

Delete the local folder by running one of these commands in your terminal:

macOS

cd ~/Desktop
rm -rf actions-trigger-playground

Windows

cd ~/Desktop
rmdir /s /q actions-trigger-playground

That's a Wrap!

That's a Wrap!

Nice work! You just built a complete reference repository that demonstrates how to control exactly when GitHub Actions workflows run.

You've learned how to:

  • Build push-trigger workflows with branch filters and path filters to control which code changes fire a pipeline.
  • Build pull-request-trigger workflows that automatically run checks when a PR is opened against your main branch.
  • Build manual-dispatch workflows with custom inputs that let you trigger deployments on-demand from the Actions tab.
  • Secret Mission: Created a multi-trigger workflow combining push, manual dispatch, and scheduled cron triggers in a single file.

Ready to quiz yourself?