Pack schema reference

This page documents every field in a Pullminder rule pack YAML file. For a step-by-step walkthrough of creating a pack, see the Authoring custom packs guide.

Full schema

slug: string               # Required. Unique pack identifier.
name: string               # Required. Display name.
kind: detection | policy   # Required. Pack type.
action: flag | warn | block # Required. Default action on findings.
version: integer           # Required. Integer version (e.g., 3).
schema_version: integer    # Optional. Schema version.
author: string             # Optional. GitHub handle (required for publishing).
max_weight: integer        # Optional. Max weight per finding. Default: 10.

scoring:                   # Optional. Tiered scoring thresholds.
  - min_findings: integer  #   Minimum findings to reach this score.
    score: integer         #   Risk score contribution at this tier.

patterns:                  # Required for detection packs. Array of pattern objects.
  - name: string           #   Required. Human-readable pattern name.
    rule_id: string        #   Required. Unique identifier (e.g., "SEC-001").
    regex: string          #   Required. RE2-compatible regular expression.
    language: string       #   Required. Language filter ("*" for all).
    severity: string       #   Required. One of: critical, error, high, medium, low, info.
    category: string       #   Required. Freeform category (e.g., "security").
    description: string    #   Optional. Detailed explanation of the finding.
    fix_templates:         #   Optional. Array of suggested fix strings.
      - string

overrides:                 # Optional. Exclusion rules.
  ignore_paths:            #   Optional. Glob patterns for paths to skip.
    - string
  ignore_authors:          #   Optional. GitHub usernames to skip.
    - string

Top-level fields

slug

Type: string — Required

Unique identifier for the pack within a registry. Must be lowercase and may contain only letters, numbers, and hyphens. This value is used in CLI commands and API calls to reference the pack.

slug: my-custom-check

name

Type: string — Required

Human-readable display name shown in the dashboard, PR comments, and CLI output.

name: My Custom Check

kind

Type: enum — Required

Determines how the pack is evaluated:

Value	Description
detection	Pattern-based matching against the PR diff. Requires at least one entry in patterns.
policy	Evaluates structural properties of the PR (description, commit messages, test coverage).

kind: detection

action

Type: enum — Required

The default behavior when the pack produces findings. Users can override this per-pack in the dashboard.

Value	Description
flag	Add findings to the risk score and include them in the reviewer brief. No inline comments.
warn	Post inline comments on the PR for each finding. Findings also affect the risk score.
block	Set the Pullminder status check to “failure”, preventing the PR from being merged until findings are resolved.

action: flag

version

Type: integer — Required

Integer version of the pack. Increment each time you modify the pack’s patterns or configuration.

version: 3

schema_version

Type: integer — Optional

The version of the pack schema this file conforms to. Can be omitted; when present the only supported value is 1.

schema_version: 1

author

Type: string — Optional

GitHub handle of the pack author. Used for attribution in the registry and verified during publishing. Required only when publishing to the community registry.

author: your-github-handle

max_weight

Type: integer — Optional — Default: 10

The maximum weight that any single finding from this pack can contribute to the risk score. This cap prevents a single pack from dominating the overall score.

max_weight: 10

scoring array

Each entry defines a scoring tier. The pack’s contribution to the risk score is the highest tier whose min_findings threshold is met by the number of findings in the PR.

scoring[].min_findings

Type: integer — Required

Minimum number of findings from this pack required to reach this score tier.

scoring[].score

Type: integer — Required

The risk score contribution when this tier is reached.

scoring:
  - min_findings: 1
    score: 5
  - min_findings: 3
    score: 10
  - min_findings: 5
    score: 15

patterns array

An array of pattern objects. Required for detection packs. Each pattern defines a single detection rule.

patterns[].name

Type: string — Required

Human-readable name for the pattern. Displayed in the reviewer brief and dashboard findings list.

- name: Hardcoded AWS access key

patterns[].rule_id

Type: string — Required

Unique identifier for the pattern within the pack. Convention is an uppercase prefix followed by a number (e.g., SEC-001, GO-003). Rule IDs must be unique across all patterns in the pack.

  rule_id: SEC-001

patterns[].regex

Type: string — Required

A regular expression matched against each added or modified line in the PR diff. Uses RE2 syntax (Go-compatible). The regex is applied per-line; multiline matching is not supported.

  regex: "AKIA[0-9A-Z]{16}"

patterns[].language

Type: string — Required

Restricts the pattern to files of a specific language. Use * to match all files. Supported values:

Value	File extensions
*	All files
go	.go
python	.py
javascript	.js, .jsx, .mjs
typescript	.ts, .tsx
rust	.rs
ruby	.rb, .erb
php	.php
java	.java
c	.c, .h
cpp	.cpp, .cc, .cxx, .hpp
csharp	.cs
swift	.swift
kotlin	.kt, .kts
yaml	.yaml, .yml
json	.json
dockerfile	Dockerfile, *.dockerfile
terraform	.tf
shell	.sh, .bash, .zsh

  language: go

patterns[].severity

Type: enum — Required

The severity level of findings produced by this pattern. Severity determines the finding’s base weight in the risk score.

Severity	Weight	Use when
critical	10	The finding represents an immediate, exploitable security risk (e.g., leaked production credentials).
error	8	Serious error that should be fixed before merging (e.g., SQL injection, command injection).
high	7	The finding is a serious issue that should be resolved before merging (e.g., unvalidated input in a sensitive path).
medium	5	The finding is a notable concern that warrants reviewer attention (e.g., missing input validation).
low	3	The finding is a minor issue or style violation (e.g., debug logging left in production code).
info	1	The finding is informational and does not significantly affect the risk score (e.g., a TODO comment).

  severity: high

patterns[].category

Type: string — Required

Freeform category used for grouping and filtering findings in the dashboard. Common values include security, code-quality, testing, infrastructure, and dependencies.

  category: security

patterns[].description

Type: string — Optional

A longer explanation of what the pattern detects and why it matters. Displayed in the reviewer brief and finding detail views.

  description: >
    AWS access keys should never appear in source code.
    Use environment variables or a secrets manager instead.

patterns[].fix_templates

Type: array of strings — Optional

Suggested fixes displayed alongside the finding. Each string is a separate suggestion. Providing fix templates helps developers resolve findings quickly.

  fix_templates:
    - "Store the key in AWS Secrets Manager and reference it via environment variable."
    - "Use IAM roles instead of static access keys."

overrides object

Exclusion rules that apply to all patterns in the pack.

overrides.ignore_paths

Type: array of strings — Optional

Glob patterns for file paths that should be excluded from pattern matching. Useful for skipping test fixtures, vendored code, or generated files.

overrides:
  ignore_paths:
    - "**/vendor/**"
    - "**/testdata/**"
    - "**/*.generated.go"

overrides.ignore_authors

Type: array of strings — Optional

GitHub usernames whose PRs should be excluded from this pack’s evaluation. Useful for skipping automated accounts.

overrides:
  ignore_authors:
    - "dependabot[bot]"
    - "renovate[bot]"

Schema version history

Version	Changes
1	Initial schema. Supports detection and policy pack kinds, additive scoring model, pattern-based matching, and path/author overrides.

Future schema versions will be backward-compatible where possible. Packs specifying an older schema_version will continue to work with newer versions of Pullminder.

Complete example

slug: node-security
name: Node.js Security
kind: detection
action: warn
version: 3
max_weight: 10

scoring:
  - min_findings: 1
    score: 5
  - min_findings: 3
    score: 10
  - min_findings: 5
    score: 15

patterns:
  - name: Dynamic code execution
    rule_id: NODE-001
    regex: "\\beval\\s*\\("
    language: javascript
    severity: error
    category: security
    description: >
      Dynamic code execution is a common vector for injection
      attacks. Use safer alternatives like JSON.parse() for data
      or Function() with strict input validation.
    fix_templates:
      - "Replace with JSON.parse() if parsing JSON data."
      - "Use a sandboxed execution environment if dynamic code evaluation is required."

  - name: Child process with shell option
    rule_id: NODE-002
    regex: "child_process.*shell\\s*:\\s*true"
    language: javascript
    severity: error
    category: security
    description: >
      Spawning child processes with shell: true enables shell
      interpretation of the command string, which can lead to
      command injection if any part of the string is user-controlled.
    fix_templates:
      - "Use execFile() or spawn() without the shell option and pass arguments as an array."

  - name: Unvalidated redirect
    rule_id: NODE-003
    regex: "res\\.redirect\\(\\s*req\\.(query|body|params)"
    language: javascript
    severity: medium
    category: security
    description: >
      Redirecting to a URL taken directly from user input can
      lead to open redirect vulnerabilities.
    fix_templates:
      - "Validate the redirect URL against an allowlist of permitted destinations."

overrides:
  ignore_paths:
    - "**/test/**"
    - "**/tests/**"
    - "**/__tests__/**"
  ignore_authors:
    - "dependabot[bot]"