Events are GitHub webhook events that trigger rule evaluation in Rulesets. The when property of a rule defines which events will cause the rule to be processed.

​
Event Format

GitHub events follow the format event_name.action. For example:

  • pull_request.opened - Triggered when a pull request is opened
  • pull_request_review.submitted - Triggered when a review is submitted

​
Supported Events

EventDescription
pull_request.openedWhen a new pull request is created
pull_request.editedWhen a pull request’s title or body is edited
pull_request.reopenedWhen a closed pull request is reopened
pull_request.synchronizeWhen new commits are pushed to the PR branch
pull_request.labeledWhen a label is added to a pull request
pull_request.unlabeledWhen a label is removed from a pull request
pull_request.ready_for_reviewWhen a draft PR is marked as ready for review
pull_request.converted_to_draftWhen a PR is converted to draft
pull_request.assignedWhen a user is assigned to a pull request
pull_request.unassignedWhen a user is unassigned from a pull request
pull_request.milestonedWhen a milestone is added to a pull request
pull_request.demilestonedWhen a milestone is removed from a pull request

​
Using Wildcards

You can use wildcards to match multiple actions for an event:

when:
  - "pull_request.*" # Matches any pull request action

This will trigger the rule for any pull request event, such as opened, edited, synchronized, etc.

​
Multiple Event Types

You can specify multiple event types to trigger a rule:

when:
  - "pull_request.opened"
  - "pull_request.edited"
  - "pull_request.synchronize"

​
Best Practices

Be specific - only trigger rules on the events they need to run for
Group related events when a rule should run in similar situations
Consider performance by avoiding unnecessary triggers

Use wildcards (e.g., pull_request.*) carefully as they may trigger rules more frequently than expected

​
Examples

​
Basic Event Trigger

ruleset:
  - name: "Title Check"
    when:
      - "pull_request.opened"
      - "pull_request.edited"
    validate:
      - type: "title"
        match: "^(feat|fix): .+"

​
Comprehensive PR Lifecycle

ruleset:
  - name: "PR Size Check"
    when:
      - "pull_request.opened"
      - "pull_request.synchronize"
    validate:
      - type: "size"
        files: 10

  - name: "Required Approvals"
    when:
      - "pull_request_review.submitted"
      - "pull_request_review.dismissed"
    validate:
      - type: "approvals"
        count:
          min: 2

  - name: "Final Checklist"
    when:
      - "pull_request.ready_for_review"
    validate:
      - type: "taskList"
        include: ["Checklist"]

​
Event Context

Each event provides different context data that can be used in validations and actions. The most common context data includes:

  • Pull request details (title, body, number, state)
  • Repository information (name, owner)
  • User information (login, name)
  • Labels, assignees, milestones
  • Changed files (for certain events)

This context data is available for use in templates and for validators to check against.