GitHub Rulesets Insights

GitHub Rulesets Insights provide visibility into how your repository protection rules are evaluated when contributors push changes. These logs capture detailed information about each rule suite evaluation, including which rules passed or failed, the actor who triggered the evaluation, and the specific repository and branch involved.

Use Cases

• Compliance Monitoring: Track when and why rules block or allow pushes to protected branches
• Security Auditing: Review rule evaluations to ensure branch protection policies are working as expected
• Troubleshooting: Investigate why specific pushes were blocked or allowed
• Policy Enforcement: Verify that required checks and approvals are being enforced

Prerequisites

GitHub Token

You’ll need a GitHub fine grained access token with the following access:

• Repository access: Select the specific repositories you want to monitor, or “All repositories” for organization-wide access
• Repository permissions:
  • Administration: Read-only (required to access rule suite data)

To create a fine-grained token:

1. Go to GitHub Settings → Developer Settings → Personal access tokens → Fine-grained tokens
2. Click “Generate new token”
3. Give it a descriptive name
4. Under “Resource Owner” select your org or the appropriate owner for access.
5. Under “Repository access”, select the repositories to monitor or organization wide
6. Under “Permissions”, set “Administration” to “Read and write” access
7. Click “Generate token” and save it securely

Scope Options

You can collect ruleset insights at two different scopes:

Organization Level

Collects rule suite evaluations across all repositories in your organization. This is useful for:

• Centralized security monitoring
• Organization-wide compliance reporting
• Detecting rule evaluation patterns across multiple repositories

When using organization scope, enter just the organization name (e.g., runreveal).

Repository Level

Collects rule suite evaluations for a specific repository only. This is useful for:

• Focused monitoring of critical repositories
• Reducing data volume when you only care about specific projects
• Per-team or per-project visibility

When using repository scope, enter the repository in owner/repo format (e.g., runreveal/app or myuser/my-project).

RunReveal Source Setup

1. Log into RunReveal and navigate to Sources → Add Source
2. Select “GitHub Rulesets” from the source list
3. Choose whether to monitor at the Organization or Repository level
4. For Organization scope: Enter your GitHub organization name (e.g., runreveal)
5. For Repository scope: Enter the full repository path in owner/repo format (e.g., runreveal/app)
6. Paste your GitHub API token
7. Click “Create” to start collecting data

Data Collected

The GitHub Rulesets source collects the following information for each rule suite evaluation:

Rule Evaluations

For each rule in the suite, you’ll see:

• rule_type - The type of rule (e.g., required_status_checks, pull_request, required_signatures)
• enforcement - The enforcement level (active, evaluate, disabled)
• result - Whether the rule passed, failed, or was bypassed
• details - Additional context about why the rule passed or failed

Polling Frequency

This source polls the GitHub API every 5 minutes for new rule suite evaluations.

Rate Limits

The GitHub API has rate limits that may affect how much data can be collected per polling cycle:

• For authenticated requests: 5,000 requests per hour
• The source automatically handles rate limiting by backing off when limits are approached

If you have a high volume of rule suite evaluations, the source may take multiple polling cycles to catch up on historical data.

Example Events

Rule Suite Evaluation (Passed)

{
  "id": 12345678,
  "actor_id": 1234567,
  "actor_name": "developer",
  "repository_name": "my-app",
  "ref": "refs/heads/main",
  "before_sha": "abc123...",
  "after_sha": "def456...",
  "pushed_at": "2024-01-15T10:30:00Z",
  "result": "pass",
  "evaluation_result": "pass",
  "rule_evaluations": [
    {
      "rule_type": "required_status_checks",
      "enforcement": "active",
      "result": "pass"
    },
    {
      "rule_type": "pull_request",
      "enforcement": "active",
      "result": "pass"
    }
  ]
}

Rule Suite Evaluation (Failed)

{
  "id": 12345679,
  "actor_id": 1234567,
  "actor_name": "developer",
  "repository_name": "my-app",
  "ref": "refs/heads/main",
  "pushed_at": "2024-01-15T10:35:00Z",
  "result": "fail",
  "rule_evaluations": [
    {
      "rule_type": "required_signatures",
      "enforcement": "active",
      "result": "fail",
      "details": "Commit is not signed"
    }
  ]
}

Troubleshooting

No Data Appearing

1. Verify your API token has the correct permissions (repo scope for classic, or Administration: Read-only for fine-grained)
2. Ensure your organization or repository has rulesets configured
3. Check that pushes have occurred to trigger rule evaluations
4. Verify the organization name is spelled correctly (case-sensitive)

Missing Rule Evaluations

The API only returns rule suite evaluations from the last month. Historical data older than one month is not available through the API.

Rate Limit Errors

If you see rate limit warnings in the logs, the source will automatically back off and retry. For organizations with high push volumes, consider monitoring at the repository level for critical repos only.