Correct PRODUCT_RELEASE behaviour and document RELEASE_INCLUDES

content/sbomify-action/configuration.md

@@ -75,6 +75,7 @@ Non-SBOM `BOM_TYPE` values are uploaded verbatim to sbomify: augmentation, enric
 | `SBOMIFY_TOKEN`          | none                      | sbomify API token. **Takes precedence over `TOKEN`.**                           |
 | `COMPONENT_ID`           | none                      | sbomify component ID. Required for upload and for sbomify-sourced augmentation. |
 | `PRODUCT_RELEASE`        | none                      | JSON array of product and version strings.                                      |
+| `RELEASE_INCLUDES`       | none                      | JSON array of releases of other products that each product release includes.    |
 | `API_BASE_URL`           | `https://app.sbomify.com` | Override for self-hosted instances.                                             |
 | `OIDC_AUDIENCE`          | `sbomify.com`             | Audience for trusted publishing. Derived from `API_BASE_URL` when self-hosted.  |
 | `SBOMIFY_UPLOAD_TIMEOUT` | `120`                     | Upload timeout in seconds. Raise for very large SBOMs.                          |
@@ -183,6 +184,7 @@ sbomify-action --lock-file requirements.txt --enrich --no-upload -o sbom.cdx.jso
 | `--token`, `--component-id`                                    | `TOKEN`, `COMPONENT_ID`            |
 | `--component-name`, `--component-version`, `--component-purl`  | matching variables                 |
 | `--product-release`                                            | `PRODUCT_RELEASE`                  |
+| `--release-includes`                                           | `RELEASE_INCLUDES`                 |
 | `--api-base-url`, `--oidc-audience`                            | matching variables                 |
 | `--working-dir`                                                | `WORKING_DIR`                      |
 | `--telemetry`, `--no-telemetry`                                | `TELEMETRY`                        |

content/sbomify-action/publishing.md

@@ -114,7 +114,8 @@ PRODUCT_RELEASE: '["product_one:v1.0.0", "product_two:v2.0.0"]'
 Behaviour worth knowing:
 
 - **Get or create.** Existing releases are reused; missing ones are created.
-- **Partial failures warn rather than fail.** If some releases tag and others do not, the run logs a warning and continues - the SBOM is already stored, so failing the build would not help.
+- **Any failed release fails the run.** If some releases tag and others do not, the run exits non-zero. The SBOM is already stored, but a release that silently misses it is worse than a red build.
+- **With OIDC, the component must be in every product listed.** A trusted-publishing token can only tag into releases of products that contain its component; any other product returns 403. An API token can tag into any product in the same workspace.
 - Requires credentials and `COMPONENT_ID`, since it talks to the sbomify API.
 
 A common pattern is to tag releases only on tagged builds:
@@ -123,6 +124,24 @@ A common pattern is to tag releases only on tagged builds:
 PRODUCT_RELEASE: ${{ startsWith(github.ref, 'refs/tags/') && format('["your-product-id:{0}"]', github.ref_name) || '' }}
 ```
 
+### Including another product's release
+
+`PRODUCT_RELEASE` puts this component's SBOM into a release. When the release also ships with another product, such as a toolchain it downloads at run time, include that product's release instead of tagging your SBOMs into it:
+
+```yaml
+env:
+  COMPONENT_ID: your-component-id
+  LOCK_FILE: requirements.txt
+  PRODUCT_RELEASE: '["your-product-id:v2.0.0"]'
+  RELEASE_INCLUDES: '["toolchain-product-id:tools-1.4.0"]'
+```
+
+Each release in `PRODUCT_RELEASE` links every release in `RELEASE_INCLUDES`, in the same `product_id:version` format. The included release is left untouched: v2.0.0 lists the toolchain, and the toolchain's release does not list your product. The linked release shows on your release page, and its SBOMs are part of your release's combined SBOM.
+
+- **Requires `PRODUCT_RELEASE`.** It says which releases do the including.
+- **The included release must already exist** in the same workspace. A missing one fails the run; a link that already exists does not.
+- **Works with OIDC.** The token needs its component in the including product only, not in the product it includes.
+
 See [how to create a software release](/faq/how-do-i-create-a-software-release/) and [versioning SBOMs](/guides/how-to-version-sboms/).
 
 ## Dependency Track