Bomly Guard

Bomly Guard is the official GitHub Action wrapper around bomly diff. It reviews the dependency changes a pull request introduces — new packages, new vulnerabilities, license violations, denied packages, suspicious (typosquat) names — and gates the merge on policy.

The action is a thin composite wrapper around the CLI. All dependency analysis and Markdown summary rendering come from bomly diff; the action only handles GitHub Actions plumbing: installing the CLI, inferring the PR merge base, exposing outputs, writing the job summary, optionally posting a PR comment, and optionally uploading SARIF to the Security tab.

Source and full reference: bomly-dev/bomly-guard.

Quick start

name: Bomly Guard

on:
  pull_request:

permissions:
  actions: read            # required for SARIF upload on private repos
  contents: read
  pull-requests: write     # required to post the summary comment (when opted in)
  security-events: write   # required for SARIF upload
  issues: write            # PR summary comments post via the issue-comments API

jobs:
  dependency-review:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v5
        with:
          fetch-depth: 0   # full history so base and head refs resolve
      - uses: bomly-dev/bomly-guard@v1
        with:
          fail-on: high
          comment-summary-in-pr: on-failure

fetch-depth: 0 matters: the action compares the PR head against the PR merge base, so it needs enough history to resolve both refs. With a shallow checkout the refs may not be reachable.

Pin to a major tag (@v1) for automatic patch and minor updates, or to an exact release (@v1.2.3) for fully reproducible builds.

How it works

On a pull_request event the action:

1. Installs the Bomly CLI (version input, defaults to latest).
2. Resolves the base and head refs. Pull requests default to the PR merge base for the base and the PR head SHA for the head, so review focuses only on what the PR changes — pre-existing findings on the target branch are ignored.
3. Runs bomly diff --format json with the enrich/audit/analyze and policy flags mapped from the action inputs.
4. Renders the Markdown summary and SARIF side outputs.
5. Writes the job summary, optionally posts (or updates) a PR comment, and optionally uploads SARIF.
6. Exits non-zero when policy fails the review, failing the job.

Because the engine is the same bomly diff you run locally, the policy you enforce on your machine is the policy the action enforces on PRs.

Inputs

Inputs map directly onto CLI flags. Comma-separated values become repeated flags (for example fail-on: high,critical → --fail-on high --fail-on critical).

The action always owns --format json and the Markdown/SARIF side outputs so the job outputs, summary, comment, and code-scanning upload stay stable. The CLI flags --format, --json, --output, and --interactive are intentionally not action inputs.

For the underlying flag semantics, see Auditors (--fail-on, license and package policy), Matchers (--enrich), and the Config Reference.

Outputs

Each output is available to later steps via ${{ steps.<id>.outputs.<name> }}:

• comment-content — the Markdown summary content.
• dependency-changes — all dependency changes as JSON.
• vulnerable-changes — introduced vulnerability findings as JSON.
• invalid-license-changes — introduced license findings as JSON.
• denied-changes — introduced denied-package findings as JSON.
• suspicious-package-changes — introduced suspicious (typosquat) findings as JSON.
• sarif-file — path to the generated SARIF file (when audit is enabled).

These let you wire custom downstream steps — for example, failing only on vulnerable-changes, or forwarding comment-content to a chat notification.

PR comments and job summary

The action always writes a job summary to the workflow run. PR comments are controlled by comment-summary-in-pr:

• never (default) — no comment.
• always — comment on every PR run.
• on-failure — comment only when a finding fails the review.

Comments default to never, so the action only posts when you opt in. Posting goes through the issue-comments API, so grant both pull-requests: write and issues: write. The action updates its existing comment in place rather than stacking a new one on every run.

SARIF upload

When audit is enabled the action produces a SARIF file and, with upload-sarif, sends it to GitHub code scanning via github/codeql-action/upload-sarif. Findings then appear in the repository Security → Code scanning tab.

GitHub requires security-events: write. Private repositories additionally require actions: read and GitHub Code Security enabled. The default upload-sarif: auto skips the upload cleanly when those requirements are not met — Bomly's own policy evaluation still determines the final job result, so a missing code-scanning entitlement never silently passes a failing PR.

Configuration files

config-file accepts either a local path or an external reference of the form owner/repo/path@ref:

      - uses: bomly-dev/bomly-guard@v1
        with:
          config-file: my-org/security-policy/bomly.yaml@main
          external-repo-token: ${{ secrets.POLICY_REPO_TOKEN }}

External reads use external-repo-token when set, otherwise repo-token. A shared policy repo lets you enforce one organization-wide policy across many repositories without copying YAML into each. See the Config Reference for the full config schema.

Action inputs vs. raw CLI

Bomly Guard is the turnkey option for GitHub pull requests. If you need a workflow the action doesn't cover — pushing to main, scheduled scans, non-GitHub CI, or full control over bomly scan/bomly diff flags — call the CLI directly. CI Integration has drop-in recipes for GitHub Actions, GitLab, Jenkins, Azure DevOps, CircleCI, and pre-commit, including a hand-rolled bomly diff PR gate equivalent to what the action automates.

See also

• CI Integration — CLI recipes for every CI system, including raw bomly diff on PRs
• Auditors — policy constraints behind fail-on and the license/package inputs
• Reachability — what analyze: true adds
• Output Formats — SARIF and JSON shapes
• Exit Codes — how policy results map to job pass/fail
• bomly-dev/bomly-guard — action source and release process