Repository configuration

A .hacktron/config.yaml file in your repository controls how Review treats its pull and merge requests. It can:

• exclude specific pull and merge requests, so they aren’t scanned

• include only specific pull and merge requests in scanning

• fail the Hacktron check when a finding meets a severity threshold, so risky changes can’t merge

.hacktron/rules.md is separate: it shapes the quality of a review. config.yaml decides whether a pull request is scanned and whether its check passes.

Configuration hierarchy

Each category (exclude.*, include.*, fail_on.severity) is resolved on its own, not the whole file at once:

1. config.yaml is used if the repository sets that category.

2. Organization settings are used otherwise.

The FAQ works through examples of how repository and organisation settings combine.

File location

Place the file in the .hacktron directory at the root of the repository:

.hacktron/
  config.yaml
  rules.md
apps/
packages/
package.json

Hacktron accepts either .hacktron/config.yaml or .hacktron/config.yml. If both exist, it uses .yaml.

Example

1
# Exclude a PR/MR from being scanned when any rule below matches.
2
exclude:
3
  labels:
4
    - hacktron-exclude
5
  keywords:
6
    - "[exclude hacktron]"
7
  paths:
8
    - "vendor/**"
9
    - "**/*.md"
10
  authors:
11
    - dependabot[bot]
12

13
# Fail the Hacktron check when a finding is at or above this severity.
14
fail_on:
15
  severity: high

Every key is optional. An empty or missing config.yaml doesn’t turn filtering off, because the organisation’s filters still apply (see configuration hierarchy). With no repository or organisation filters set, Hacktron scans every covered pull request, and the check stays green unless the scan itself fails with an error.

Exclude scans

The exclude block tells Hacktron not to scan a pull or merge request. A match records a skipped check and uses no developer seat.

Hacktron checks the rules in this order, and the first match applies:

1
exclude:
2
  branches:
3
    - "release/legacy/**" # exclude PRs targeting a legacy release branch
4
  labels:
5
    - hacktron-exclude # label the PR "hacktron-exclude" to exclude it
6
  keywords:
7
    - "[exclude hacktron]" # put this anywhere in the PR/MR title to exclude it
8
  paths:
9
    - "docs/**" # exclude when the PR only touches these paths
10
    - "**/*.md"
11
  authors:
12
    - "dependabot[bot]" # exclude all PRs opened by dependabot
13
    - "*-bot" # glob: exclude any author ending in "-bot"

Glob pattern syntax

exclude.branches, exclude.paths, exclude.authors, include.authors, and include.branches, and the organisation-wide equivalents of each, accept glob patterns mixed with literals. Matching is case-insensitive.

For author names, * and ** usually behave the same, because author names don’t contain /. The characters [, ], and a leading ! are literal. Bracket classes, negation, nested braces, and extended glob forms such as @(a|b) aren’t supported.

The same limits apply to repository and organisation settings:

• up to 50 entries in each filter category

• up to 100 characters in each pattern

• up to five * characters in each pattern

• up to 10 comma-separated alternatives in one brace expression

If a repository pattern goes over these limits, Hacktron treats the repository’s configuration as invalid and scans with the fail-open behaviour described below.

Matching nested branches with * and **

* matches within one path segment, and ** also crosses /.

Use release/* for one-level branches such as release/2.4, and release/** for any depth. Add a literal segment, as in release/legacy/**, to target only that subtree.

Combine exclude and include to leave out a subtree: include.branches: ["release/**"] with exclude.branches: ["release/legacy/**"] scans every release branch except release/legacy/**.

Include scans

The include block scans only the pull and merge requests that match its rules. On the ones it doesn’t scan, Hacktron records a skipped check and, if code review comments are on, posts a skip comment.

1
include:
2
  branches:
3
    - "main"
4
    - "release/**" # only scan PRs targeting main or a release branch
5
  labels:
6
    - security-review # only scan PRs labelled "security-review"
7
  authors:
8
    - alice # ...and were opened by Alice, Bob, or a bot account
9
    - bob
10
    - "*-bot"
11
  keywords:
12
    - "please review" # ...and title contains "please review"

Within a category, any value matches: include.labels: [feature, bugfix] matches either label. Across categories, include needs every category to match: include.branches: [main] with include.authors: [alice] scans only Alice’s pull requests to main.

Fail the check on findings

By default, the Hacktron check is green as long as the scan completes, and findings are posted as inline comments that don’t block the merge. Set a severity threshold to turn the check red when a finding is at or above that level.

A pull request whose Hacktron check failed on a finding

The threshold is inclusive: high fails the check on high and critical findings, while critical fails it only on critical ones.

You can set the threshold for the whole organisation in the settings, or for one repository in config.yaml (see configuration hierarchy).

1
fail_on:
2
  severity: high   # fail the check on any high or critical finding

How invalid configuration is handled

Hacktron is fail-open about configuration:

• A missing, empty, or malformed config.yaml is ignored. Hacktron scans normally and the check stays green.

• Unknown keys are ignored, so a configuration can carry settings for future features without breaking today’s scans.

• A value of the wrong type on a known key, such as fail_on.severity: 7, makes Hacktron ignore the whole file. Keep values in the shapes shown above.

FAQ

Related