How do you configure custom secret scanning patterns in GitHub, and what strategies ensure comprehensive coverage of proprietary credential formats?

Imagine you are running airport security. The built-in scanners detect standard contraband like weapons and explosives (GitHub's partner patterns for AWS keys, Stripe tokens, etc.), but your airline also has custom VIP passes with a unique format that the standard scanners do not recognize. Custom secret scanning patterns are like programming the scanner to also flag those VIP passes—you define the shape of what to look for, and the system catches it automatically across every piece of luggage (repository) that passes through.

GitHub's built-in secret scanning detects over 200 credential formats from partner providers like AWS, Azure, Stripe, and Twilio. When a partner pattern match is found, GitHub can automatically notify the issuing provider to revoke the credential. Custom patterns extend this by letting you define regular expressions for proprietary secrets: internal API keys, database connection strings, JWT signing keys with custom prefixes, or any credential format unique to your organization. Patterns use Hyperscan-compatible regex syntax, which supports most PCRE features but not backreferences or lookaheads.

Each custom pattern consists of a primary regex (the secret itself), optional 'before' and 'after' regexes for context matching, and a test string for validation. The before/after regexes help reduce false positives by requiring the secret to appear in a specific context—for example, requiring 'DB_PASSWORD=' before a 40-character hex string. Patterns can be scoped at three levels: repository (only that repo), organization (all repos in the org), or enterprise (all repos across all orgs). Organization and enterprise patterns propagate automatically to new repositories, ensuring no gaps in coverage as the organization grows.

For the payments-api team at acme-corp, a comprehensive custom pattern strategy covers several proprietary formats: internal service mesh tokens (prefixed with 'acme_svc_'), database connection strings containing the internal domain, Vault transit keys, and internal HMAC secrets used for webhook verification. Each pattern goes through a dry-run phase first—GitHub scans existing repository content and shows potential matches without creating alerts, letting you tune the regex to minimize false positives. In production, patterns should be ordered by specificity: start with patterns that have distinctive prefixes (low false-positive rate) and add broader patterns with before/after context anchors. Push protection, when enabled for custom patterns, blocks contributors from pushing code containing matches, providing a pre-commit safety net.

The primary gotcha is regex performance: overly broad patterns with excessive backtracking can timeout during scanning, and GitHub silently skips repositories that exceed the scan time limit. Test patterns against a corpus of realistic code before deploying at scale. Another issue is the 500-custom-pattern limit per organization—sounds generous until you realize that environment-specific connection strings and multi-format API keys consume patterns quickly. Use alternation within patterns (pattern1|pattern2) to consolidate. False positive management is critical: security teams that create alerts for every match quickly experience alert fatigue. Use the 'before' and 'after' context regex to narrow matches, mark confirmed false positives as 'closed/false-positive' to train your team's triage instincts, and integrate alert webhooks with your SIEM for automated enrichment.