Follow this guide to quickly set up your first ruleset and start automating PR workflows.

​
Basic Configuration

After installing the Rulesets GitHub App, create a configuration file in your repository:

ruleset:
  - name: "Basic PR Validation"
    when:
      - "pull_request.opened"
      - "pull_request.edited"
    validate:
      - type: "title"
        length:
          min: 10
        message: "PR title must be at least 10 characters"
      - type: "description"
        no_empty: true
        message: "PR description cannot be empty"
    on_success:
      - label:
          add: ["valid-pr"]
    on_failure:
      - comment:
          body: |
            Thanks for your contribution! Please ensure your PR meets our guidelines:
            
            - PR title should be descriptive and at least 10 characters
            - PR description should not be empty
            
            {{ validation_summary }}

Save this configuration to .github/Ruleset.yml in your repository.

​
How It Works

This basic rule:

  • Triggers when PRs are opened or edited
  • Validates that PR titles are at least 10 characters long
  • Ensures PR descriptions are not empty
  • Adds a “valid-pr” label when validations pass
  • Comments with guidance when validations fail

The {{ validation_summary }} template variable will be replaced with details about which validations passed or failed.

​
Common Configurations

Here are some common use cases to help you get started:

​
Conventional Commits

Enforce Conventional Commits format for PR titles:

ruleset:
  - name: "Conventional Commits"
    when:
      - "pull_request.opened"
      - "pull_request.edited"
    validate:
      - type: "title"
        match: "^(feat|fix|docs|style|refactor|perf|test|build|ci|chore|revert)(\\(\\w+\\))?: .+"
    on_failure:
      - comment:
          body: "Please follow the conventional commit format for your PR title"

​
PR Size Limits

Limit the size of PRs to keep them manageable:

ruleset:
  - name: "PR Size Limit"
    when:
      - "pull_request.opened"
      - "pull_request.synchronize"
    validate:
      - type: "size"
        files: 10
        total: 500
    on_failure:
      - label:
          add: ["large-pr"]

​
Auto-Assign Reviewers

Automatically assign reviewers to new PRs:

ruleset:
  - name: "Auto Assign Reviewers"
    when:
      - "pull_request.opened"
    on_success:
      - requestReview:
          reviewers: ["username1", "username2"]
          teams: ["team-name"]

​
Branch Naming Convention

Enforce branch naming standards:

ruleset:
  - name: "Branch Naming"
    when:
      - "pull_request.opened"
    validate:
      - type: "branch"
        head:
          match: "^(feature|bugfix|hotfix)/[a-z0-9-_]+"
    on_failure:
      - comment:
          body: "Branch names should follow pattern: type/description"

​
Next Steps

  • Explore Rules to understand the structure in depth
  • Check out Validators to learn about different validation types
  • See Actions for all available actions you can take
  • Browse Examples for more advanced configurations