Event Triggers

Triggers define when your automation runs. Cheffed supports several trigger types, each with specific configuration options.

GitHub Issue Trigger

Responds to GitHub issue events in your repositories.

Configuration

Option	Description
Repository	Which repo to monitor for issues
Event Type	opened, edited, labeled, or all
Label Filter	Only trigger on issues with specific labels

Label Filtering

Filter triggers by issue labels to target specific workflows:

Include labels - Only trigger when issue has these labels:

• bug - Trigger on bug reports
• automate - Trigger on issues tagged for automation
• enhancement - Trigger on feature requests

Example: An automation with label filter bug only triggers when:

1. A new issue is created with the bug label, OR
2. The bug label is added to an existing issue

Context Passed to Session

When a GitHub issue triggers an automation, the session receives:

{
  "issue": {
    "number": 42,
    "title": "Login button not working",
    "body": "When I click login, nothing happens...",
    "labels": ["bug", "auth"],
    "author": "username",
    "url": "https://github.com/org/repo/issues/42"
  },
  "repository": {
    "name": "repo",
    "owner": "org",
    "default_branch": "main"
  }
}

The agent can use this context to understand the issue and take action.

GitHub Pull Request Trigger

Responds to pull request events.

Configuration

Option	Description
Repository	Which repo to monitor for PRs
Event Type	opened, synchronize, merged, or all
Base Branch Filter	Only trigger for PRs targeting specific branches
Label Filter	Only trigger on PRs with specific labels

Event Types

• opened - New PR created
• synchronize - New commits pushed to PR
• merged - PR merged into target branch
• all - Any PR event

Branch Filtering

Target automations to specific branches:

• main - Only PRs targeting main
• develop - Only PRs targeting develop
• release/* - PRs targeting release branches (pattern matching)

Context Passed to Session

{
  "pull_request": {
    "number": 123,
    "title": "Add user authentication",
    "body": "This PR implements...",
    "head_branch": "feature/auth",
    "base_branch": "main",
    "author": "username",
    "url": "https://github.com/org/repo/pull/123",
    "diff_url": "https://github.com/org/repo/pull/123.diff"
  },
  "repository": {
    "name": "repo",
    "owner": "org"
  }
}

Trigger Conditions

Multiple Conditions

Some triggers support multiple conditions that must all match:

Trigger: GitHub Issue
Repository: my-org/my-app
Labels: bug AND priority:high

Both conditions must be true for the automation to run.

Negative Conditions

Exclude certain events:

Trigger: GitHub Issue
Repository: my-org/my-app
Labels: bug
Exclude Labels: wontfix, duplicate

Issues with wontfix or duplicate labels won’t trigger the automation.

Rate Limiting

Automations include built-in rate limiting to prevent runaway executions:

• Per-automation limit: Maximum executions per hour
• Debouncing: Brief delay to batch rapid sequential events
• Duplicate detection: Prevents re-triggering on the same event

Troubleshooting Triggers

Automation Not Triggering

Check these common issues:

1. Automation disabled - Ensure the toggle is on
2. Wrong repository - Verify the repo is correctly selected
3. Label mismatch - Confirm issue/PR has required labels
4. GitHub App not installed - Check GitHub integration
5. Webhook not configured - Verify webhook is active in GitHub settings

Unexpected Triggers

If automation triggers when it shouldn’t:

1. Review trigger conditions
2. Check label filters for typos
3. Verify event type selection
4. Review recent execution history for patterns

Next Steps

• Configure Actions for triggered events
• Set up GitHub integration
• Monitor Execution History