Manage detector definitions as reviewed configuration, but keep dry runs and publishing in the UI until GitHub exposes those steps safely through the API.
Update — August 12, 2026: This guide now covers unpublished API-created patterns, Hyperscan syntax limits, dry-run ownership, and the extra disruption risk when push protection is enabled.
GitHub security teams can now manage secret scanning custom patterns through generally available REST endpoints. The API covers listing, creation, modification, and deletion at repository, organization, and enterprise scope.
Custom patterns are useful for credentials that belong to an internal service or a vendor pattern GitHub does not detect by default. The API makes those definitions easier to standardize, but it also makes a bad detector easier to distribute.
What is—and is not—automated
The available endpoints provide the basic CRUD lifecycle for custom patterns. GitHub says dry runs and final publishing still happen in the web interface. That boundary is helpful: a team can automate inventory and draft changes while retaining a human checkpoint before a noisy pattern becomes active.
The API is available to secret scanning customers at all three management levels. Access tokens should receive only the scope needed for the chosen level.
Treat patterns like production rules
Store the intended token format, examples that must match, examples that must not match, owner, affected services, and last review date. Test against representative history before publishing. A pattern that matches too broadly can bury real exposures in alert noise; one that is too narrow creates false confidence.
Changes should go through review because deletion or weakening can reduce coverage across many repositories at once.
A practical automation boundary
Use the API to detect configuration drift, prepare new definitions, and report coverage. Keep dry-run result review and publication as an explicit security task. Log who requested the rule, who approved it, and which repositories were tested before enterprise-wide rollout.
Creating a pattern is not publishing it
The REST API can create custom patterns in an unpublished state. Before a pattern produces alerts or blocks pushes, the security owner should run it against selected repositories in the GitHub interface, inspect the resulting sample, and decide whether the expected true positives justify any false positives. GitHub documents dry runs on up to ten repositories and a sample of up to 1,000 results at enterprise scope.
Treat a published detector as a policy change. It can scan the full Git history of covered repositories, and enabling push protection for a commonly occurring pattern can interrupt contributors. Plan the communication, bypass path, and alert owner before changing the pattern from observation to enforcement.
Build the detector from test cases, not one regular expression
GitHub custom patterns use Hyperscan regular-expression constructs, which are a subset of PCRE. A pattern copied from another tool may therefore fail or behave differently. Define an expected token shape, surrounding delimiters, must-match requirements, must-not-match examples, and sample strings that should never alert before you automate deployment.
Keep these tests next to the pattern definition. A change in a token format, a new test fixture, or a false-positive report should produce a reviewed update to the detector rather than an ad-hoc exception in one repository.
- Keep the pattern, positive examples, negative examples, owner, and affected service in reviewed configuration.
- Use a small dry run before organization- or enterprise-wide publication.
- Check whether the creator has the required scope to edit and dry-run the pattern at the selected level.
- Enable push protection only after measuring likely contributor disruption and documenting an exception process.
- Periodically review alert volume, bypasses, false positives, and the continued validity of the token format.
This article explains the practical implications of the primary material below. PatchMemo does not publish vendor copy as editorial coverage and does not accept payment for positive coverage.
PatchMemo independently selects and evaluates the topics it covers. Analysis and recommendations are ours; sources are linked so readers can check the underlying claims. We clearly label sponsorships and affiliate relationships, and neither determines coverage or conclusions.
