Skip to main content

Glossary & Core Concepts

A concise reference for key terms across Ship Guard.
Use this to align team language, speed onboarding, and improve configuration accuracy.

Core Configuration​

  • Rule
    A declarative check defined in .github/ship-guard.yml.
    Each rule evaluates pull request (PR) changes and produces findings (warnings or errors).
    Common examples:

    • banned-terms
    • require-changelog
    • require-tests
    • max-file-size
    • ai-review
    • policy-question.

  • Condition
    The rule type that determines how a rule operates.
    Examples:

    • banned-terms (string match),
    • require-changelog (file presence),
    • ai-review (AI-based analysis),
    • policy-question (RAG-backed policy query).

  • Severity
    Indicates the importance of a finding:

    • warning: advisory only
    • error: blocks merges when branch protection is enabled
      If not specified, Ship Guard applies the global default_severity.

  • Paths / ExcludePaths
    Glob patterns to include or exclude files from rule evaluation.
    Order: include via paths → exclude via excludePaths.

  • Enabled
    Boolean flag to toggle a rule on or off without removing it. Useful for phased rollouts.

  • Tags
    Free-form labels for organization and analytics (e.g., security, frontend, compliance).

  • Error Code (errorCode)
    Optional short identifier for categorizing findings (e.g., CONFIG_ERROR, AI_REVIEW, TESTS_MISSING).
    You can define your own, or Ship Guard assigns a sensible default per rule type.

AI & Knowledge​

  • AI Review (ai-review)
    An AI-powered rule that analyzes PR diffs using a custom prompt.
    Ideal for nuanced checks (error handling, accessibility, API contracts).
    Supports structured outputs (e.g., JSON) for precise inline feedback.

  • Policy Question (policy-question)
    A repository-level AI rule that answers compliance or policy-related questions (e.g., “Is MongoDB approved?”).
    Grounded in your organization’s knowledge base (RAG).

  • RAG Source Weight
    A relevance score (0.0–1.0) indicating how authoritative a document is for retrieval.

    Guidelines:

    • 0.9–1.0 → Critical (security policies, ADRs)
    • 0.7–0.8 → Important (standards, API contracts)
    • 0.4–0.6 → Helpful context
    • 0.1–0.3 → Background info
    rag_sources:
      - path: "docs/adr/001-use-postgresql.md"
        weight: 0.95  # High priority
      - path: "README.md"
        weight: 0.2   # General context only

  • RAG Sync The process of indexing documentation for retrieval during AI analysis.

    Sync modes:

    • Basic (Hobby) — auto-sync on config file changes
    • On-demand (Pro, Scale) — manual sync via dashboard
    • Advanced (Scale) — scheduled or selective reindexing
  • Prompt Instruction text for ai-review and policy-question. Best prompts are specific, scoped, and request structured outputs.

Incident Memory​

Ship Guard’s memory system that learns from past incidents to prevent recurrence. If a developer edits code similar to a previous failure, Ship Guard automatically warns them with relevant incident context.

Available on Pro and Scale plans.

  • Incident A stored record of a production issue. Includes title, summary, severity, tags, and post-mortem link.

    Title: INC-042: SQL Injection in search endpoint
    Severity: High
    Tags: security, database, user-input
    Summary: Unsanitized user input led to SQL injection vulnerability...

  • Incident Analytics (Scale only) Dashboard tracking prevention metrics, showing how past incidents were avoided in new PRs.

Execution & Results​

  • Check Run GitHub status check summarizing rule outcomes. Can be enforced through branch protection.

  • Bot Comment Structured PR comment listing detailed findings with code anchors and fix suggestions.

  • Finding A single issue reported by a rule — includes file/line, severity, message, and suggested fix.

  • Default Severity (default_severity) Global fallback applied when a rule doesn’t define a severity.

  • Global Settings (settings) Top-level Ship Guard configuration controlling global behavior — e.g., templates, max findings, integrations, enableAIReviews.

Governance & Workflow​

  • Branch Protection GitHub feature that blocks merges until required checks (e.g., Ship Guard) pass.

  • Required Status Check A named check (e.g., “Ship Guard”) configured as mandatory in branch protection.

  • Sandbox Repository Safe test repo for experimenting with new or modified rules before org-wide rollout.

Performance & Safety​

  • Max Findings / Max Findings in Comment Limits to prevent noise — caps total findings and per-comment subsets.

  • Content Filtering Redacts sensitive data before sending it to AI models.

  • Max Tokens Upper bound for AI response length (controls cost and verbosity).

  • File Limits (AI) Caps like maxFilesPerReview or maxFileSizeKB to limit scope and cost.

Analytics & Reporting​

  • Rule Tags & Error Codes Used to segment dashboards, track issues by category, and analyze patterns over time.

  • Finding Trends Aggregated metrics highlighting recurring issue types (e.g., repeated SEC-001 findings).

Common Conditions (Quick Reference)​

ConditionDescription
banned-termsDisallow specific strings or regex (e.g., TODO, console.log, secrets)
require-changelogRequire a CHANGELOG or PR entry
require-testsEnsure test files are added or modified
max-file-sizeEnforce file size limits (KB)
max-line-lengthLimit line length
max-file-additionsLimit number of new files per PR
security-scanPerform basic regex-based security checks
ai-reviewAI-powered diff analysis
policy-questionRAG-backed compliance or policy Q&A

💡 This glossary is version-controlled. If something’s missing or unclear, suggest an update via GitHub Issues.