Trackers and notifications (dry run by default)

Plan tracker and notification updates; --apply sends them. This page documents every command in the trackers group, in the order sbomflow help trackers lists them. Each command's section is generated from the command itself — its summary, description and options from the parser, and its reads, writes, exit codes, examples and see-also from the command catalog — so it says exactly what sbomflow <command> --help says. Every example below is executed offline by the test suite, and every non-zero exit code is either produced by an executed probe or carries a recorded reason why no offline probe can produce it.

See the CLI overview for how the thirteen groups fit together and the command reference for every command's options in one place.

Overview#

sbomflow sync-issues (GitHub), sync-jira, sync-servicenow, sync-dependencytrack, notify.

Network — opt-in

Sync/notify commands are dry-run by default. They only contact an external
system when you pass --apply, and credentials come from environment variables,
never from evidence artifacts.

sync-issues and sync-jira label what they plan. Without --labels, the default follows the requirement regime the run recorded in its own evidence-pack.json (never the current config): sbomflow,cra-evidence for a cra run, sbomflow,release-evidence for a run recorded under requirement_regime: none. When the regime cannot be established — no pack, an unreadable one, a regime spelling this build does not recognise — the cra default applies and the dry run says so in a Labels: line. An explicit --labels always wins. sync-servicenow, sync-dependencytrack and notify carry no labels.

Who this is for: engineering managers, repository maintainers, IT service teams, platform teams and team leads.

`sbomflow sync-issues`#

Sync evidence-gap issues to GitHub (dry run by default; --apply to push).

text

Plan the GitHub issues a run's evidence gaps call for and write github-issue-
plan.json into the output directory. A dry run by default: no network. --apply
makes the real GitHub API calls and needs GITHUB_TOKEN; issues are matched by
marker, so a re-run updates rather than duplicates.

Fact	Value
Group	`trackers` — Trackers & notifications (dry run by default)
Stability	stable
Regime	any
Reads	issues.json in an output directory.
Writes	github-issue-plan.json, the dry-run plan, into the directory
Network	apply-gated — Dry-run planning is offline; GitHub API use is possible only with --apply. Gates: --apply.
Exit codes	`0` planned, or with --apply delivered · `2` missing artifacts, or a refused --apply
Machine output	artifact-suffices — dry-run by default: writes the machine-readable sync plan artifact; delivery is a separate explicit step

Options

Option	Value	Default	Allowed	Required	Help
`-h, --help`	(flag)	none	—	no	show this help message and exit
`EVIDENCE_DIR`	`EVIDENCE_DIR`	none	any	yes	Directory produced by 'analyze' (has issues.json).
`--repo`	`REPO`	none	any	yes	Target repository as 'owner/name'.
`--apply`	(flag)	false	—	no	Make real GitHub API calls (requires GITHUB_TOKEN). Off = dry run, no network.
`--labels`	`LABELS`	none	any	no	Comma-separated issue labels. Default: sbomflow,cra-evidence for a cra run, sbomflow,release-evidence for a run recorded under requirement_regime none (read from its evidence-pack.json).

Examples

Plan the GitHub issues for a run's evidence gaps, sending nothing.

sbomflow sync-issues out --repo example/gateway

Plan them with your own labels.

sbomflow sync-issues out --repo example/gateway --labels security,release

See also: sbomflow sync-jira, sbomflow sync-servicenow, sbomflow notify, sbomflow help network.

`sbomflow sync-jira`#

Export (or, with --apply, sync) a Jira issue plan from issues.json.

text

Plan the Jira issues a run's issues.json calls for and write jira-issue-
plan.json into the output directory. A dry run by default: no network. --apply
creates or updates the issues by marker and needs --base-url, a Jira email and
JIRA_API_TOKEN.

Fact	Value
Group	`trackers` — Trackers & notifications (dry run by default)
Stability	stable
Regime	any
Reads	issues.json in an output directory.
Writes	jira-issue-plan.json, the dry-run plan, into the directory
Network	apply-gated — Dry-run planning is offline; Jira API use is possible only with --apply. Gates: --apply.
Exit codes	`0` planned, or with --apply delivered · `2` missing artifacts, or a refused --apply
Machine output	artifact-suffices — dry-run by default: writes the machine-readable sync plan artifact; delivery is a separate explicit step

Options

Option	Value	Default	Allowed	Required	Help
`-h, --help`	(flag)	none	—	no	show this help message and exit
`EVIDENCE_DIR`	`EVIDENCE_DIR`	none	any	yes	Directory produced by 'analyze' (has issues.json).
`--project-key`	`PROJECT_KEY`	none	any	yes	Target Jira project key.
`--issue-type`	`ISSUE_TYPE`	Task	any	no	Jira issue type name.
`--labels`	`LABELS`	none	any	no	Comma-separated labels. Default: sbomflow,cra-evidence for a cra run, sbomflow,release-evidence for a run recorded under requirement_regime none (read from its evidence-pack.json).
`--apply`	(flag)	false	—	no	Create/update Jira issues by marker (network). Requires --base-url, JIRA_EMAIL/--jira-email, and JIRA_API_TOKEN. Off = dry run, no network.
`--base-url`	`BASE_URL`	none	any	no	Jira Cloud base URL, e.g. https://acme.atlassian.net.
`--jira-email`	`JIRA_EMAIL`	none	any	no	Jira account email for Basic auth (or env JIRA_EMAIL).

Examples

Plan the Jira issues for a run, sending nothing.

sbomflow sync-jira out --project-key SEC

Plan them as Bugs with your own labels.

sbomflow sync-jira out --project-key SEC --issue-type Bug --labels security

See also: sbomflow sync-issues, sbomflow sync-servicenow, sbomflow help network.

`sbomflow sync-servicenow`#

Export (or, with --apply, sync) a ServiceNow Table API plan from issues.json.

text

Plan the ServiceNow Table API records a run's issues.json calls for and write
servicenow-issue-plan.json into the output directory. A dry run by default: no
network. --apply creates or updates the records by marker and needs --base-
url, a ServiceNow user and SERVICENOW_PASSWORD.

Fact	Value
Group	`trackers` — Trackers & notifications (dry run by default)
Stability	stable
Regime	any
Reads	issues.json in an output directory.
Writes	servicenow-issue-plan.json, the dry-run plan, into the directory
Network	apply-gated — Dry-run planning is offline; ServiceNow API use is possible only with --apply. Gates: --apply.
Exit codes	`0` planned, or with --apply delivered · `2` missing artifacts, or a refused --apply
Machine output	artifact-suffices — dry-run by default: writes the machine-readable sync plan artifact; delivery is a separate explicit step

Options

Option	Value	Default	Allowed	Required	Help
`-h, --help`	(flag)	none	—	no	show this help message and exit
`EVIDENCE_DIR`	`EVIDENCE_DIR`	none	any	yes	Directory produced by 'analyze' (has issues.json).
`--table`	`TABLE`	none	any	yes	Target ServiceNow table, e.g. incident or a customer-owned task table.
`--short-description-field`	`FIELD`	short_description	any	no	Field used for the tracker item title.
`--description-field`	`DESCRIPTION_FIELD`	description	any	no	Field used for the tracker item body.
`--apply`	(flag)	false	—	no	Create/update ServiceNow records by marker (network). Requires --base-url, SERVICENOW_USER/--servicenow-user, and SERVICENOW_PASSWORD. Off = dry run.
`--base-url`	`BASE_URL`	none	any	no	ServiceNow base URL, e.g. https://acme.service-now.com.
`--servicenow-user`	`SERVICENOW_USER`	none	any	no	ServiceNow username for Basic auth (or env SERVICENOW_USER).

Examples

Plan ServiceNow incident records for a run, sending nothing.

sbomflow sync-servicenow out --table incident

Plan them into a customer-owned table with its own field names.

sbomflow sync-servicenow out --table u_security_task --short-description-field short_description --description-field description

See also: sbomflow sync-issues, sbomflow sync-jira, sbomflow help network.

`sbomflow sync-dependencytrack`#

Plan or upload cyclonedx-sbom.json to OWASP Dependency-Track.

text

Plan the upload of a run's cyclonedx-sbom.json to an OWASP Dependency-Track
project and write dependencytrack-plan.json into the output directory. A dry
run by default: no network. --apply uploads the BOM and needs --base-url and
DEPENDENCYTRACK_API_KEY.

Fact	Value
Group	`trackers` — Trackers & notifications (dry run by default)
Stability	stable
Regime	any
Reads	cyclonedx-sbom.json and the evidence pack in an output directory.
Writes	dependencytrack-plan.json, the dry-run upload plan, into the directory
Network	apply-gated — Dry-run planning is offline; upload is possible only with --apply. Gates: --apply.
Exit codes	`0` planned, or with --apply uploaded · `2` missing artifacts, or a refused --apply
Machine output	artifact-suffices — dry-run by default: writes the machine-readable sync plan artifact; delivery is a separate explicit step

Options

Option	Value	Default	Allowed	Required	Help
`-h, --help`	(flag)	none	—	no	show this help message and exit
`EVIDENCE_DIR`	`EVIDENCE_DIR`	none	any	yes	Directory produced by 'analyze' (has cyclonedx-sbom.json).
`--base-url`	`BASE_URL`	none	any	no	Dependency-Track base URL. Required with --apply.
`--project-name`	`PROJECT_NAME`	none	any	no	Dependency-Track project name (default: evidence-pack product_name).
`--project-version`	`PROJECT_VERSION`	none	any	no	Dependency-Track project version (default: evidence-pack product_version).
`--no-auto-create`	(flag)	false	—	no	Do not set autoCreate=true in the Dependency-Track upload payload.
`--apply`	(flag)	false	—	no	Upload the BOM (network). Requires DEPENDENCYTRACK_API_KEY. Off = dry run.

Examples

Plan the SBOM upload to Dependency-Track, sending nothing.

sbomflow sync-dependencytrack out

Name the project and version, and ask Dependency-Track not to create it.

sbomflow sync-dependencytrack out --project-name Gateway --project-version 2.4.1 --no-auto-create

See also: sbomflow sync-issues, sbomflow bundle, sbomflow help network.

`sbomflow notify`#

Plan (and optionally deliver) review-queue/gate notifications for an output dir.

text

Plan notifications about a run's review queue and gate outcome for the
channels named (Slack, Teams, a webhook or email) and write notification-
plan.json into the output directory. A dry run by default: no network. --apply
delivers, reading each channel's secret from the environment; secrets are
never recorded.

Fact	Value
Group	`trackers` — Trackers & notifications (dry run by default)
Stability	stable
Regime	any
Reads	the review queue and gate outcome in an output directory.
Writes	notification-plan.json, the dry-run plan, into the directory
Network	apply-gated — Dry-run planning is offline; delivery is possible only with --apply. Gates: --apply.
Exit codes	`0` planned, or with --apply delivered · `2` no or unknown channel, missing artifacts, or a refused --apply
Machine output	artifact-suffices — writes the notification plan artifact; delivery is a separate explicit step

Options

Option	Value	Default	Allowed	Required	Help
`-h, --help`	(flag)	none	—	no	show this help message and exit
`EVIDENCE_DIR`	`EVIDENCE_DIR`	none	any	yes	Directory produced by 'analyze'.
`--channel`	`CHANNEL`	none	slack, teams, webhook, email	no	Notification channel (repeatable): slack, teams, webhook, or email.
`--apply`	(flag)	false	—	no	Actually deliver via configured channels (secrets from env). Default is dry-run.
`--link-base`	`LINK_BASE`	none	any	no	Optional base URL prefixed to report/gate links (e.g. a CI artifact URL).

Examples

Plan Slack and email notifications for a run, sending nothing.

sbomflow notify out --channel slack --channel email

Plan a generic webhook, with links prefixed by a CI artifact URL.

sbomflow notify out --channel webhook --link-base https://ci.example.invalid/artifacts

Name no channel: refused, since there is nothing to plan. Exits 2.

sbomflow notify out

See also: sbomflow sync-issues, sbomflow review, sbomflow help network.

SBOMFlow documentation. Engineering release-evidence support only — not a compliance or conformity claim, and not legal advice.

Trackers and notifications (dry run by default)

Overview#

sbomflow sync-issues#

sbomflow sync-jira#

sbomflow sync-servicenow#

sbomflow sync-dependencytrack#

sbomflow notify#

`sbomflow sync-issues`#

`sbomflow sync-jira`#

`sbomflow sync-servicenow`#

`sbomflow sync-dependencytrack`#

`sbomflow notify`#