diff --git a/code-review/config.mdx b/code-review/config.mdx index 26298be..2c143ea 100644 --- a/code-review/config.mdx +++ b/code-review/config.mdx @@ -6,6 +6,7 @@ description: "Use .hacktron/config.yaml to control which pull and merge requests Add a `.hacktron/config.yaml` file to your repository to control Hacktron's Code Review behavior: - **Skip** specific pull and merge requests so they aren't scanned. +- **Include** specific pull and merge requests to be scanned. - **Fail** the Hacktron check when a finding meets a severity threshold, so risky changes can't merge. This is separate from [`.hacktron/rules.md`](/code-review/rules), which shapes the *quality* of a review. `config.yaml` controls *whether* a PR is scanned and *whether* its check passes. @@ -47,6 +48,8 @@ skip: paths: - "vendor/**" - "**/*.md" + authors: + - dependabot[bot] # Fail the Hacktron check when a finding is at or above this severity. fail_on: @@ -57,18 +60,24 @@ Every key is optional. An empty or absent `config.yaml` means Hacktron behaves a ## Skip scans -Use the `skip` block to tell Hacktron not to scan a pull or merge request. When a PR matches, Hacktron records a **skipped** check on the PR/MR and posts a short comment naming the rule that matched. No scan runs, and **no developer seat is used**. +Branches, labels, authors, and keywords can be set per repository here, or org-wide in [Organization settings](/platform/organization-settings#scan-filters). Repo config overrides only the dimensions it sets; other dimensions keep the org default. -Rules are evaluated in this order; the first match wins: +The `skip` block tells Hacktron not to scan a pull or merge request. A match records a **skipped** check with a comment naming the rule, and uses no developer seat. + +Rules are evaluated in this order, first match applies: | Key | Matches when | Match style | |---|---|---| -| `skip.labels` | the PR/MR carries one of these labels | exact, case-insensitive | +| `skip.branches` | the PR/MR targets one of these branches | case-insensitive glob | +| `skip.labels` | the PR/MR carries one of these labels | case-insensitive | | `skip.keywords` | the PR/MR **title** contains one of these strings | case-insensitive substring | | `skip.paths` | **every** changed file matches one of these patterns | gitignore-style globs | +| `skip.authors` | the PR/MR was opened by one of these usernames | case-insensitive | ```yaml skip: + branches: + - "release/legacy/**" # skip PRs targeting a legacy release branch labels: - hacktron-skip # label the PR "hacktron-skip" to skip it keywords: @@ -76,8 +85,18 @@ skip: paths: - "docs/**" # skip when the PR only touches these paths - "**/*.md" + authors: + - "dependabot[bot]" # skip all PRs opened by dependabot ``` + + `skip.branches` and `include.branches` (and their org-wide equivalents) accept + glob patterns mixed with literals: `*`, `**`, `?`, and `{a,b}` brace expansion. + Matching is case-insensitive. `[`, `]`, and a leading `!` are literal, not + special syntax. Each list allows up to 50 patterns, up to 100 characters each. + Labels, authors, and keywords allow up to 20 entries each. + + `skip.paths` skips a scan **only when every changed file matches** one of the patterns. If even one changed file falls outside the patterns, the PR is @@ -87,6 +106,37 @@ skip: A manual `@hacktronai review` comment always runs a scan, even when a `skip` rule would otherwise match — use it to force a one-off review of an otherwise-skipped PR. +## Include scans + +Use the include block to scan **only** pull and merge requests that match specific rules. Hacktron records a skip check comment on PRs/MRs it doesn't scan. + +```yaml +include: + branches: + - "main" + - "release/**" # only scan PRs targeting main or a release branch + labels: + - security-review # only scan PRs labelled "security-review" + authors: + - alice # always scan Alice's and Bob's PRs + - bob + keywords: + - "please review" # only scan PRs whose title contains this +``` + +| Key | Matches when | +|---|---| +| `include.branches` | the PR/MR targets one of these branches (case-insensitive glob) | +| `include.labels` | the PR/MR carries at least one of these labels (case-insensitive) | +| `include.authors` | the PR/MR was opened by one of these usernames (case-insensitive) | +| `include.keywords` | the PR/MR title contains one of these strings (case-insensitive substring) | + +`include.labels: [feature, bugfix]` matches a PR with either label. Setting `include` on more than one dimension requires matching all of them: `include.branches: [main]` with `include.authors: [alice]` only scans Alice's PRs targeting `main`. + + + `skip` and `include` can both be set for the same dimension: `skip.labels: [wip]` with `include.labels: [feature]` scans PRs labelled `feature`, except ones also labelled `wip`. + + ## Fail the check on findings By default, the Hacktron check is green as long as the scan completes. Findings are posted as inline comments but don't block the merge. Configure a severity threshold to turn the check **red** when a finding is at or above that level. @@ -106,21 +156,7 @@ You can set the threshold org-wide from the settings page, or per repository in - Set a default for all repositories in your organization: - - - - Select your organization, then go to **Settings**. - - - Locate **Severity threshold**, above the SLA Thresholds card. - - ![Severity threshold settings card](/images/severity_threshold.png) - - - Pick a severity from the dropdown: **Critical**, **High**, **Medium**, or **Low**. Select **Off** to disable the gate org-wide. - - + Set a default for all repositories in your organization from [Organization settings](/platform/organization-settings#check-gate). diff --git a/code-review/setup.mdx b/code-review/setup.mdx index 6770d9c..c933dc3 100644 --- a/code-review/setup.mdx +++ b/code-review/setup.mdx @@ -41,12 +41,11 @@ You also need permission to connect your Git provider. For more details, choose - For each repository, choose whether Hacktron should review pull requests or - merge requests targeting all branches or only specific branches such as - `main` or `production`. - - Branches - + Hacktron reviews all branches by default. Restrict this org-wide in + [Organization settings](/platform/organization-settings#scan-filters), or + per repository via `skip.branches` / `include.branches` in + `.hacktron/config.yaml`. See [Repository + configuration](/code-review/config) for the syntax. Go to an existing pull request or merge request and comment `@hacktronai review`. diff --git a/docs.json b/docs.json index 102437a..4d29841 100644 --- a/docs.json +++ b/docs.json @@ -73,7 +73,8 @@ "group": "Account", "pages": [ "platform/account-settings", - "platform/security-settings" + "platform/security-settings", + "platform/organization-settings" ] }, { diff --git a/images/scan_filters.png b/images/scan_filters.png new file mode 100644 index 0000000..7504b86 Binary files /dev/null and b/images/scan_filters.png differ diff --git a/platform/dashboard.mdx b/platform/dashboard.mdx index 6628d20..249aec7 100644 --- a/platform/dashboard.mdx +++ b/platform/dashboard.mdx @@ -18,22 +18,11 @@ by clicking on **Export**. ## Resolution Health - From the settings page, you can configure SLA tresholds for remediating findings of different severities. - - SLA thresholds - - This is used to track your resolution health. Hacktron calculates your Mean Time to Resolution (MTTR), - and the percentage of findings that are resolved within the SLA tresholds. + Hacktron calculates your Mean Time to Resolution (MTTR) and the percentage of findings resolved within your SLA thresholds. Resolution health - ## Check gate - - From the settings page, you can also set an org-wide **Severity threshold**. - - Severity threshold settings card - - See [Fail the check on findings](/code-review/config#fail-the-check-on-findings) for details and per-repository overrides. + Configure the resolution window and compliance target per severity in [Organization settings](/platform/organization-settings#sla-thresholds). diff --git a/platform/organization-settings.mdx b/platform/organization-settings.mdx new file mode 100644 index 0000000..df42fc8 --- /dev/null +++ b/platform/organization-settings.mdx @@ -0,0 +1,85 @@ +--- +title: "Organization settings" +description: "Configure scan filters, the check gate, and SLA thresholds for your organization." +--- + +Organization settings apply to every repository unless a repository's `.hacktron/config.yaml` overrides them. Only organization admins and owners can change these settings. + + + + Select your organization, then go to **Settings**. + + + +## Scan filters + +Choose which pull and merge requests Hacktron scans by default, across four dimensions: branches, labels, authors, and keywords. + + + + Locate **Filters**. + + + Select **Add filter**. Choose a dimension and a direction, then enter one or more values. + + Filters card + + + +| Dimension | Match style | +|---|---| +| Branches | Glob pattern, case-insensitive (e.g. `release/*`) | +| Labels | Exact name, case-insensitive | +| Authors | Exact username, case-insensitive | +| Keywords | Substring in the PR/MR title, case-insensitive | + + + **Include** and **Skip** can both be set for the same dimension: Skip takes priority within that dimension. Setting a filter for one dimension has no effect on the others. + + +Want per-repo control? Override any dimension in `.hacktron/config.yaml`. See [Repository configuration](/code-review/config) for the glob syntax, limits, and how repo config overrides org defaults. + +## Check gate + +Set an org-wide severity threshold that fails a PR or MR check when a finding meets or exceeds it. + + + + Locate **Severity threshold**. + + Severity threshold settings card + + + Pick a severity: **Critical**, **High**, **Medium**, or **Low**. Select **Off** to disable the gate org-wide. + + + +See [Fail the check on findings](/code-review/config#fail-the-check-on-findings) for the full severity table and per-repository overrides. + +## SLA thresholds + +Set the resolution window and minimum compliance target for each severity. + + + + Locate **SLA Thresholds**. + + SLA thresholds settings card + + + For each severity, set the number of days findings have to be resolved in, and the minimum percentage that should meet it. + + + +These values drive the Resolution Health widget on the [dashboard](/platform/dashboard#resolution-health), including Mean Time to Resolution (MTTR) and SLA compliance. + +## Related + + + + Connect a Git provider, enable repositories, and choose covered branches. + + + Use `.hacktron/config.yaml` to override scan filters and the check gate per repository. + +